copybook

What it is and what it does

Copybook is a Python parser for VSAM copybook definitions—the schema format used in COBOL and mainframe systems to describe fixed-width record layouts. It reads copybook text (either from a file or string) and builds a tree of field and group objects, exposing metadata like column positions and field lengths. The main use case is extracting that structural information to parse actual fixed-width data files: you define the copybook once, flatten its field list, then use the start positions and lengths to slice and decode each line of raw data according to its PIC clause (numeric, character, signed, etc.).

The package depends only on pyparsing for tokenization and installs with low friction. It supports a range of numeric and character PIC notations, OCCURS and REDEFINES clauses, and groups. However, the project is no longer maintained—the last release was in September 2022 and the repository has seen no commits since May 2023—so it will not receive updates for new Python versions, bug fixes, or unsupported copybook features.

Use it for:

• Parse legacy mainframe data exports in fixed-width format using their original COBOL copybook definitions.
• Extract field positions and data types from copybooks to automate ETL pipelines that consume VSAM or sequential files.
• Convert copybook metadata into column mappings for data analysis or database loading tools.
• Validate or document the structure of fixed-width files by comparing them against their copybook schema.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Copybook parses VSAM copybook definitions and extracts field structure and position information to enable parsing of fixed-width data files.

Yes, if you need to parse VSAM copybooks and can tolerate an abandoned package. The MIT license is permissive, install friction is low, and there are no known vulnerabilities. However, do not expect maintenance, bug fixes, or support for new Python versions. Suitable for stable, low-change integration tasks; risky for production systems requiring ongoing support.

Install

copybook on PyPI

pip install copybook

uv add copybook

poetry add copybook

Installing copybook

Before you install

Installation is straightforward with a single runtime dependency (pyparsing). However, the package is abandoned—no releases since 2022-09-15 and no commits since 2023-05-17—so expect no maintenance or bug fixes going forward.

License in practice

MIT license is permissive and poses no restrictions on use, modification, or distribution.

Quickstart

import copybook
text = """
       01  WORK-BOOK.
        10  TAX-RATE        PIC S9(13)V9(2)
                    SIGN LEADING SEPARATE.
"""
root = copybook.parse_string(text)
list_of_fields = root.flatten()
for field in list_of_fields:
    if type(field)==copybook.Field:
        str_field = line[field.start_pos:field.start_pos+field.get_total_length()]
        print(f"{field.name}: {field.parse(str_field)}")

Verify before relying

• Whether the package handles all COBOL PIC clause variations encountered in production copybooks
• Compatibility with Python versions beyond 3.7, given the classifier but unspecified requires_python
• Performance characteristics on large copybooks or high-volume fixed-width file parsing

Package facts

Evidence: copybook-1.0.16-py3-none-any.whl

Tags

More Text Processing packages