pobol 0.1.0__tar.gz

pobol-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.3
+Name: pobol
+Version: 0.1.0
+Summary: Call COBOL programs as Python functions — file I/O handled for you
+Author-email: andy@andyreagan.com
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# pobol
+
+[![CI](https://github.com/andyreagan/pobol/actions/workflows/ci.yml/badge.svg)](https://github.com/andyreagan/pobol/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pobol)](https://pypi.org/project/pobol/)
+
+Call COBOL programs as Python functions. Like [maturin](https://github.com/PyO3/maturin) for Rust, but for GnuCOBOL.
+
+**Motivation:** You're migrating COBOL off a mainframe. The programs do real work you want to keep, but they expect VSAM files, DD names, and JCL — none of which exist on Linux/macOS. pobol wraps `cobc` (GnuCOBOL) so you can:
+
+1. Point it at a `.cbl` file — it parses the source and discovers everything  
+2. Pass Python dicts as input records  
+3. Get Python dicts back from the output files  
+
+No copybook transcription, no temp-file juggling, no batch scripts.
+
+## Quick Start
+
+```bash
+uv add pobol          # or: pip install pobol
+```
+
+### Zero-config mode (auto-discovery)
+
+```python
+from pobol import load
+
+# pobol parses the COBOL source, discovers SELECT/FD clauses,
+# extracts record layouts, strips mainframe artifacts, compiles, and
+# handles all file I/O automatically.
+report = load("customer_report.cob")
+
+print(report.file_info)
+# COBOL Program: customer_report.cob
+#
+# INPUTS:
+#   INPUT-FILE (45 bytes): IN-CUST-ID, IN-CUST-NAME, IN-BALANCE
+# OUTPUTS:
+#   OUTPUT-FILE (54 bytes): OUT-CUST-ID, OUT-CUST-NAME, OUT-BALANCE, OUT-DISCOUNT
+
+result = report(input_file=[
+    {"IN-CUST-ID": 1, "IN-CUST-NAME": "Alice", "IN-BALANCE": 2500.00},
+    {"IN-CUST-ID": 2, "IN-CUST-NAME": "Bob",   "IN-BALANCE":  800.00},
+])
+
+for rec in result.output_file:
+    print(rec)
+# {'out_cust_id': 1, 'out_cust_name': 'Alice', 'out_balance': 2500.0, 'out_discount': 250.0}
+# {'out_cust_id': 2, 'out_cust_name': 'Bob',   'out_balance':  800.0, 'out_discount':   0.0}
+```
+
+### Mainframe source — works directly
+
+```python
+# Point at raw mainframe COBOL with sequence numbers, LABEL RECORDS,
+# IBM-370, DD-name assigns — pobol handles it all:
+prog = load("check_disbursement.cbl")
+
+print(prog.file_info)
+# Discovers all 6 files, 4 record layouts under one FD, 60+ fields...
+# Strips sequence numbers, rewrites ASSIGN TO for env-var mapping,
+# removes LABEL RECORDS/RECORDING MODE/BLOCK CONTAINS.
+```
+
+### Explicit copybooks (optional override)
+
+```python
+from pobol import load, parse_copybook
+
+input_cb = parse_copybook("""
+    01  INPUT-RECORD.
+        05  CUST-ID     PIC 9(6).
+        05  CUST-NAME   PIC X(30).
+        05  BALANCE     PIC 9(7)V9(2).
+""")
+output_cb = parse_copybook("""
+    01  OUTPUT-RECORD.
+        05  CUST-ID     PIC 9(6).
+        05  CUST-NAME   PIC X(30).
+        05  BALANCE     PIC 9(7)V9(2).
+        05  DISCOUNT    PIC 9(7)V9(2).
+""")
+
+report = load(
+    "customer_report.cob",
+    inputs={"INPUT-FILE": input_cb},
+    outputs={"OUTPUT-FILE": output_cb},
+)
+```
+
+## How It Works
+
+```
+                                                        ┌──────────────────┐
+  Python dict ──▶ Copybook.encode() ──▶ temp file ──▶  │                  │
+                                                        │  cobc-compiled   │
+  Python dict ◀── Copybook.decode() ◀── temp file ◀──  │  COBOL program   │
+                                                        │                  │
+                                                        └──────────────────┘
+```
+
+1. **Parse source** — discovers SELECT/FD/OPEN clauses, extracts PIC field layouts, detects input vs output files
+2. **Strip mainframe** — removes sequence numbers (cols 1-6), identification (cols 73-80), LABEL RECORDS, RECORDING MODE, BLOCK CONTAINS, fixes SOURCE-COMPUTER
+3. **Rewrite assigns** — converts `ASSIGN TO DATAIN` (DD names) to working-storage paths loaded from `DD_*` environment variables  
+4. **Compile** — `cobc -x` compiles to a native executable (cached by content hash)
+5. **Write inputs** — your Python dicts are encoded as fixed-width records to temp files
+6. **Run** — the executable runs with `DD_*` env vars pointing to temp files
+7. **Read outputs** — output temp files are decoded back into Python dicts
+
+## Handling Multiple Record Types
+
+Real mainframe COBOL often has multiple 01-level records under one FD (header, detail, trailer). pobol discovers all of them:
+
+```python
+prog = load("check_disbursement.cbl")
+
+# See all discovered layouts
+for file_name, layouts in prog.record_layouts.items():
+    for rec_name, copybook in layouts.items():
+        print(f"{file_name}/{rec_name}: {len(copybook.fields)} fields")
+# TXN-DATA-FILE/TXN-DATA-RECORD: 2 fields
+# TXN-DATA-FILE/TXN-DATA-HDR-RECORD: 5 fields
+# TXN-DATA-FILE/TXN-DATA-DETAIL-RECORD: 60 fields
+# TXN-DATA-FILE/TXN-DATA-TRLR-RECORD: 5 fields
+
+# For multi-record files, use raw_files with pre-encoded bytes:
+header_bytes = header_copybook.encode(header_dict)
+detail_bytes = detail_copybook.encode_many(detail_dicts)
+trailer_bytes = trailer_copybook.encode(trailer_dict)
+
+result = prog(raw_files={
+    "TXN-DATA-FILE": header_bytes + detail_bytes + trailer_bytes,
+})
+```
+
+## API Reference
+
+### `load(source, **kwargs) → CobolProgram`
+
+Compile a COBOL source file and return a callable.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `source` | `str \| Path` | required | Path to .cob/.cbl file |
+| `inputs` | `dict[str, Copybook]` | `None` | Override auto-discovered input layouts |
+| `outputs` | `dict[str, Copybook]` | `None` | Override auto-discovered output layouts |
+| `dialect` | `str` | `None` | GnuCOBOL `-std=` dialect |
+| `extra_flags` | `list[str]` | `None` | Extra `cobc` flags |
+| `strip_mainframe` | `bool` | `True` | Strip mainframe format artifacts |
+| `rewrite_assigns` | `bool` | `True` | Rewrite ASSIGN TO for env-var mapping |
+
+### `CobolProgram.__call__(**kwargs) → CobolResult`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `stdin` | `str` | Data for ACCEPT/stdin |
+| `env` | `dict` | Extra environment variables |
+| `timeout` | `float` | Execution timeout (default 30s) |
+| `raw_files` | `dict[str, bytes]` | Pre-encoded file data by SELECT name |
+| `**file_inputs` | `list[dict]` | Input data as list of dicts, keyed by SELECT name |
+
+### `CobolResult`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `.stdout` | `str` | Program stdout (DISPLAY output) |
+| `.stderr` | `str` | Program stderr |
+| `.return_code` | `int` | Exit code |
+| `.outputs` | `dict[str, list[dict]]` | Decoded output files |
+| `.output_file` | `list[dict]` | Shorthand for `.outputs["OUTPUT-FILE"]` |
+
+### `parse_cobol_source(source, **kwargs) → ParsedSource`
+
+Parse without compiling. Returns discovered files, record layouts, and cleaned source.
+
+### Supported PIC Clauses
+
+| PIC | Python type | Notes |
+|-----|-------------|-------|
+| `X(n)`, `XX` | `str` | Left-justified, space-padded |
+| `9(n)`, `999` | `int` | Zero-padded |
+| `S9(n)` | `int` | Trailing sign overpunch |
+| `9(n)V9(m)`, `9(5)V99` | `float` | Implied decimal (mixed forms supported) |
+| `S9(n)V9(m)` | `float` | Signed implied decimal |
+
+## Development
+
+```bash
+uv sync
+uv run pytest -v
+uv run python examples/demo.py
+```
+
+## Prerequisites
+
+- **GnuCOBOL** (`cobc`) — `brew install gnucobol` / `apt install gnucobol`
+- **Python 3.11+**
+
+## License
+
+MIT

pobol-0.1.0/README.md

@@ -0,0 +1,200 @@
+# pobol
+
+[![CI](https://github.com/andyreagan/pobol/actions/workflows/ci.yml/badge.svg)](https://github.com/andyreagan/pobol/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pobol)](https://pypi.org/project/pobol/)
+
+Call COBOL programs as Python functions. Like [maturin](https://github.com/PyO3/maturin) for Rust, but for GnuCOBOL.
+
+**Motivation:** You're migrating COBOL off a mainframe. The programs do real work you want to keep, but they expect VSAM files, DD names, and JCL — none of which exist on Linux/macOS. pobol wraps `cobc` (GnuCOBOL) so you can:
+
+1. Point it at a `.cbl` file — it parses the source and discovers everything  
+2. Pass Python dicts as input records  
+3. Get Python dicts back from the output files  
+
+No copybook transcription, no temp-file juggling, no batch scripts.
+
+## Quick Start
+
+```bash
+uv add pobol          # or: pip install pobol
+```
+
+### Zero-config mode (auto-discovery)
+
+```python
+from pobol import load
+
+# pobol parses the COBOL source, discovers SELECT/FD clauses,
+# extracts record layouts, strips mainframe artifacts, compiles, and
+# handles all file I/O automatically.
+report = load("customer_report.cob")
+
+print(report.file_info)
+# COBOL Program: customer_report.cob
+#
+# INPUTS:
+#   INPUT-FILE (45 bytes): IN-CUST-ID, IN-CUST-NAME, IN-BALANCE
+# OUTPUTS:
+#   OUTPUT-FILE (54 bytes): OUT-CUST-ID, OUT-CUST-NAME, OUT-BALANCE, OUT-DISCOUNT
+
+result = report(input_file=[
+    {"IN-CUST-ID": 1, "IN-CUST-NAME": "Alice", "IN-BALANCE": 2500.00},
+    {"IN-CUST-ID": 2, "IN-CUST-NAME": "Bob",   "IN-BALANCE":  800.00},
+])
+
+for rec in result.output_file:
+    print(rec)
+# {'out_cust_id': 1, 'out_cust_name': 'Alice', 'out_balance': 2500.0, 'out_discount': 250.0}
+# {'out_cust_id': 2, 'out_cust_name': 'Bob',   'out_balance':  800.0, 'out_discount':   0.0}
+```
+
+### Mainframe source — works directly
+
+```python
+# Point at raw mainframe COBOL with sequence numbers, LABEL RECORDS,
+# IBM-370, DD-name assigns — pobol handles it all:
+prog = load("check_disbursement.cbl")
+
+print(prog.file_info)
+# Discovers all 6 files, 4 record layouts under one FD, 60+ fields...
+# Strips sequence numbers, rewrites ASSIGN TO for env-var mapping,
+# removes LABEL RECORDS/RECORDING MODE/BLOCK CONTAINS.
+```
+
+### Explicit copybooks (optional override)
+
+```python
+from pobol import load, parse_copybook
+
+input_cb = parse_copybook("""
+    01  INPUT-RECORD.
+        05  CUST-ID     PIC 9(6).
+        05  CUST-NAME   PIC X(30).
+        05  BALANCE     PIC 9(7)V9(2).
+""")
+output_cb = parse_copybook("""
+    01  OUTPUT-RECORD.
+        05  CUST-ID     PIC 9(6).
+        05  CUST-NAME   PIC X(30).
+        05  BALANCE     PIC 9(7)V9(2).
+        05  DISCOUNT    PIC 9(7)V9(2).
+""")
+
+report = load(
+    "customer_report.cob",
+    inputs={"INPUT-FILE": input_cb},
+    outputs={"OUTPUT-FILE": output_cb},
+)
+```
+
+## How It Works
+
+```
+                                                        ┌──────────────────┐
+  Python dict ──▶ Copybook.encode() ──▶ temp file ──▶  │                  │
+                                                        │  cobc-compiled   │
+  Python dict ◀── Copybook.decode() ◀── temp file ◀──  │  COBOL program   │
+                                                        │                  │
+                                                        └──────────────────┘
+```
+
+1. **Parse source** — discovers SELECT/FD/OPEN clauses, extracts PIC field layouts, detects input vs output files
+2. **Strip mainframe** — removes sequence numbers (cols 1-6), identification (cols 73-80), LABEL RECORDS, RECORDING MODE, BLOCK CONTAINS, fixes SOURCE-COMPUTER
+3. **Rewrite assigns** — converts `ASSIGN TO DATAIN` (DD names) to working-storage paths loaded from `DD_*` environment variables  
+4. **Compile** — `cobc -x` compiles to a native executable (cached by content hash)
+5. **Write inputs** — your Python dicts are encoded as fixed-width records to temp files
+6. **Run** — the executable runs with `DD_*` env vars pointing to temp files
+7. **Read outputs** — output temp files are decoded back into Python dicts
+
+## Handling Multiple Record Types
+
+Real mainframe COBOL often has multiple 01-level records under one FD (header, detail, trailer). pobol discovers all of them:
+
+```python
+prog = load("check_disbursement.cbl")
+
+# See all discovered layouts
+for file_name, layouts in prog.record_layouts.items():
+    for rec_name, copybook in layouts.items():
+        print(f"{file_name}/{rec_name}: {len(copybook.fields)} fields")
+# TXN-DATA-FILE/TXN-DATA-RECORD: 2 fields
+# TXN-DATA-FILE/TXN-DATA-HDR-RECORD: 5 fields
+# TXN-DATA-FILE/TXN-DATA-DETAIL-RECORD: 60 fields
+# TXN-DATA-FILE/TXN-DATA-TRLR-RECORD: 5 fields
+
+# For multi-record files, use raw_files with pre-encoded bytes:
+header_bytes = header_copybook.encode(header_dict)
+detail_bytes = detail_copybook.encode_many(detail_dicts)
+trailer_bytes = trailer_copybook.encode(trailer_dict)
+
+result = prog(raw_files={
+    "TXN-DATA-FILE": header_bytes + detail_bytes + trailer_bytes,
+})
+```
+
+## API Reference
+
+### `load(source, **kwargs) → CobolProgram`
+
+Compile a COBOL source file and return a callable.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `source` | `str \| Path` | required | Path to .cob/.cbl file |
+| `inputs` | `dict[str, Copybook]` | `None` | Override auto-discovered input layouts |
+| `outputs` | `dict[str, Copybook]` | `None` | Override auto-discovered output layouts |
+| `dialect` | `str` | `None` | GnuCOBOL `-std=` dialect |
+| `extra_flags` | `list[str]` | `None` | Extra `cobc` flags |
+| `strip_mainframe` | `bool` | `True` | Strip mainframe format artifacts |
+| `rewrite_assigns` | `bool` | `True` | Rewrite ASSIGN TO for env-var mapping |
+
+### `CobolProgram.__call__(**kwargs) → CobolResult`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `stdin` | `str` | Data for ACCEPT/stdin |
+| `env` | `dict` | Extra environment variables |
+| `timeout` | `float` | Execution timeout (default 30s) |
+| `raw_files` | `dict[str, bytes]` | Pre-encoded file data by SELECT name |
+| `**file_inputs` | `list[dict]` | Input data as list of dicts, keyed by SELECT name |
+
+### `CobolResult`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `.stdout` | `str` | Program stdout (DISPLAY output) |
+| `.stderr` | `str` | Program stderr |
+| `.return_code` | `int` | Exit code |
+| `.outputs` | `dict[str, list[dict]]` | Decoded output files |
+| `.output_file` | `list[dict]` | Shorthand for `.outputs["OUTPUT-FILE"]` |
+
+### `parse_cobol_source(source, **kwargs) → ParsedSource`
+
+Parse without compiling. Returns discovered files, record layouts, and cleaned source.
+
+### Supported PIC Clauses
+
+| PIC | Python type | Notes |
+|-----|-------------|-------|
+| `X(n)`, `XX` | `str` | Left-justified, space-padded |
+| `9(n)`, `999` | `int` | Zero-padded |
+| `S9(n)` | `int` | Trailing sign overpunch |
+| `9(n)V9(m)`, `9(5)V99` | `float` | Implied decimal (mixed forms supported) |
+| `S9(n)V9(m)` | `float` | Signed implied decimal |
+
+## Development
+
+```bash
+uv sync
+uv run pytest -v
+uv run python examples/demo.py
+```
+
+## Prerequisites
+
+- **GnuCOBOL** (`cobc`) — `brew install gnucobol` / `apt install gnucobol`
+- **Python 3.11+**
+
+## License
+
+MIT

pobol-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "pobol"
+version = "0.1.0"
+description = "Call COBOL programs as Python functions — file I/O handled for you"
+readme = "README.md"
+authors = [
+    { email = "andy@andyreagan.com" }
+]
+requires-python = ">=3.11"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.9.30,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pobol-0.1.0/src/pobol/__init__.py

@@ -0,0 +1,25 @@
+"""pobol — call COBOL programs as Python functions."""
+
+from pobol.program import CobolProgram, load
+from pobol.copybook import Copybook, parse_copybook
+from pobol.source_parser import parse_cobol_source, strip_mainframe_format, ParsedSource
+from pobol.exceptions import (
+    CompileError,
+    CobolRuntimeError,
+    CopybookParseError,
+    PyCobolError,
+)
+
+__all__ = [
+    "CobolProgram",
+    "load",
+    "Copybook",
+    "parse_copybook",
+    "parse_cobol_source",
+    "strip_mainframe_format",
+    "ParsedSource",
+    "CompileError",
+    "CobolRuntimeError",
+    "CopybookParseError",
+    "PyCobolError",
+]

pobol-0.1.0/src/pobol/compiler.py

@@ -0,0 +1,79 @@
+"""Thin wrapper around the ``cobc`` compiler shipped with GnuCOBOL."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+from pobol.exceptions import CompileError
+
+# Default directory for caching compiled binaries
+_CACHE_DIR = Path(tempfile.gettempdir()) / "pobol_cache"
+
+
+def _source_hash(source_path: Path) -> str:
+    """Return a short content-hash of the source file for cache-busting."""
+    h = hashlib.sha256(source_path.read_bytes()).hexdigest()[:16]
+    return h
+
+
+def compile_program(
+    source_path: str | Path,
+    *,
+    output_dir: str | Path | None = None,
+    extra_flags: list[str] | None = None,
+    dialect: str | None = None,
+    force: bool = False,
+) -> Path:
+    """Compile a COBOL source file to an executable using ``cobc -x``.
+
+    Parameters
+    ----------
+    source_path:
+        Path to the ``.cob`` / ``.cbl`` file.
+    output_dir:
+        Where to put the binary. Defaults to a temp cache dir.
+    extra_flags:
+        Additional flags passed to ``cobc``.
+    dialect:
+        E.g. ``"ibm"``, ``"mf"``, ``"cobol85"`` — passed as ``-std=<dialect>``.
+    force:
+        Re-compile even if a cached binary exists.
+
+    Returns
+    -------
+    Path to the compiled executable.
+    """
+    source_path = Path(source_path).resolve()
+    if not source_path.exists():
+        raise FileNotFoundError(f"COBOL source not found: {source_path}")
+
+    if output_dir is None:
+        output_dir = _CACHE_DIR
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    h = _source_hash(source_path)
+    exe_name = f"{source_path.stem}_{h}"
+    exe_path = output_dir / exe_name
+
+    if exe_path.exists() and not force:
+        return exe_path
+
+    cmd: list[str] = ["cobc", "-x", "-o", str(exe_path)]
+    if dialect:
+        cmd.append(f"-std={dialect}")
+    if extra_flags:
+        cmd.extend(extra_flags)
+    cmd.append(str(source_path))
+
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise CompileError(str(source_path), result.returncode, result.stderr)
+
+    # Ensure executable bit
+    exe_path.chmod(exe_path.stat().st_mode | 0o111)
+    return exe_path