Overpunch Parser/Formatter

1.1 verified Mon Apr 27 auth: no python

A library for parsing and formatting IBM mainframe overpunch (signed numeric) fields. Used to convert between human-readable numbers and the compact byte-level representations common in legacy COBOL systems. Current version 1.1, stable and rarely updated.

pip install overpunch

Common errors

error ValueError: Last nibble is not a valid sign ↓

cause The last 4 bits of the input bytes do not correspond to an expected sign nibble (0xC, 0xD, 0xF).

fix

Verify the source data uses IBM overpunch standard. If using custom sign nibbles, override or preprocess.

error TypeError: a bytes-like object is required, not 'str' ↓

cause Passing a string instead of bytes to parse().

fix

Encode the string to bytes first: parser.parse(my_string.encode()) or use b'...' literal.

Warnings

gotcha Overpunch sign nibble encoding: 'C' (positive), 'D' (negative), 'F' (unsigned positive). Ensure your source data uses IBM standard, as some variants differ. ↓

fix Check the last nibble of the last byte. Use parser.parse() which handles standard encodings.

gotcha Trailing zeros not preserved: formatting an integer may result in bytes without expected leading zeros if the number of digits is less than the desired field width. ↓

fix Prefix zeros manually before formatting, e.g., format as a string with leading zeros, then convert to overpunch.

deprecated The module previously allowed direct string-to-byte parsing without specifying width; v1.1 expects the byte array length to match the number's digit count plus sign nibble. ↓

fix When upgrading to 1.1, ensure your input byte strings have the correct length for the number of decimal digits plus one sign nibble.

Imports

OverpunchParser
```
from overpunch import OverpunchParser
```
Correct import since v1.0
OverpunchFormatter
```
from overpunch import OverpunchFormatter
```
Used to convert numbers to overpunch bytes

Quickstart

Parse overpunch bytes to int and format int to bytes.

from overpunch import OverpunchParser, OverpunchFormatter

# Parse an overpunch byte string (last nibble holds sign)
raw = b'\x12\x3d'  # Example: two bytes, last nibble 'D' (negative)
parser = OverpunchParser()
result = parser.parse(raw)
print(result)  # -123

# Format a number to overpunch bytes
formatter = OverpunchFormatter()
formatted = formatter.format(456)
print(formatted)  # b'\x45\x6c' (positive)