{"id":21673,"library":"overpunch","title":"Overpunch Parser/Formatter","description":"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.","status":"active","version":"1.1","language":"python","source_language":"en","source_url":"https://github.com/truveris/overpunch","tags":["overpunch","ibm","mainframe","cobol","signed-numeric","legacy"],"install":[{"cmd":"pip install overpunch","lang":"bash","label":"PyPI"}],"dependencies":[],"imports":[{"note":"Correct import since v1.0","symbol":"OverpunchParser","correct":"from overpunch import OverpunchParser"},{"note":"Used to convert numbers to overpunch bytes","symbol":"OverpunchFormatter","correct":"from overpunch import OverpunchFormatter"}],"quickstart":{"code":"from overpunch import OverpunchParser, OverpunchFormatter\n\n# Parse an overpunch byte string (last nibble holds sign)\nraw = b'\\x12\\x3d'  # Example: two bytes, last nibble 'D' (negative)\nparser = OverpunchParser()\nresult = parser.parse(raw)\nprint(result)  # -123\n\n# Format a number to overpunch bytes\nformatter = OverpunchFormatter()\nformatted = formatter.format(456)\nprint(formatted)  # b'\\x45\\x6c' (positive)\n","lang":"python","description":"Parse overpunch bytes to int and format int to bytes."},"warnings":[{"fix":"Check the last nibble of the last byte. Use parser.parse() which handles standard encodings.","message":"Overpunch sign nibble encoding: 'C' (positive), 'D' (negative), 'F' (unsigned positive). Ensure your source data uses IBM standard, as some variants differ.","severity":"gotcha","affected_versions":"all"},{"fix":"Prefix zeros manually before formatting, e.g., format as a string with leading zeros, then convert to overpunch.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<=1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Verify the source data uses IBM overpunch standard. If using custom sign nibbles, override or preprocess.","cause":"The last 4 bits of the input bytes do not correspond to an expected sign nibble (0xC, 0xD, 0xF).","error":"ValueError: Last nibble is not a valid sign"},{"fix":"Encode the string to bytes first: parser.parse(my_string.encode()) or use b'...' literal.","cause":"Passing a string instead of bytes to parse().","error":"TypeError: a bytes-like object is required, not 'str'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}