{"id":2491,"library":"ebcdic","title":"ebcdic: Additional EBCDIC Codecs","description":"The `ebcdic` package provides additional EBCDIC codecs for Python, primarily facilitating data exchange with legacy mainframe systems. EBCDIC (Extended Binary Coded Decimal Interchange Code) is a family of character encodings distinct from ASCII and Unicode. It is intended for use in scenarios where interoperability with EBCDIC-native systems is required. The current version is 2.0.1, with releases tied to Python version compatibility.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/roskakori/CodecMapper.git","tags":["codec","text","unicode","ebcdic","mainframe","legacy"],"install":[{"cmd":"pip install ebcdic","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The 'ebcdic' package registers its codecs directly, allowing standard string methods like .encode() and .decode() with EBCDIC codec names.","symbol":"ebcdic","correct":"import ebcdic"}],"quickstart":{"code":"import ebcdic\n\n# Encode a Unicode string to EBCDIC (e.g., cp1141 for Germany/Austria)\nunicode_string = 'hello world'\nebcdic_bytes = unicode_string.encode('cp1141')\nprint(f\"Encoded EBCDIC bytes: {ebcdic_bytes}\")\n\n# Decode EBCDIC bytes back to a Unicode string\ndecoded_string = ebcdic_bytes.decode('cp1141')\nprint(f\"Decoded Unicode string: {decoded_string}\")\n\n# Example with a different codec (cp1047 for Open Systems)\n# Note: Python's standard library may already include some common EBCDIC codecs.\nsample_bytes_cp1047 = b'\\x88\\x85\\x93\\x93\\x96@\\xa6\\x96\\x99\\x93\\x84'\ndecoded_cp1047 = sample_bytes_cp1047.decode('cp1047')\nprint(f\"Decoded with cp1047: {decoded_cp1047}\")","lang":"python","description":"This quickstart demonstrates how to encode a standard Python string to EBCDIC bytes using a specific EBCDIC code page (e.g., 'cp1141') and then decode EBCDIC bytes back to a Unicode string. The `ebcdic` package extends Python's built-in `str.encode()` and `bytes.decode()` methods with additional EBCDIC code page support."},"warnings":[{"fix":"Ensure your Python environment is 3.9+ to use `ebcdic` 2.0.1. For older Python versions, explicitly install an earlier `ebcdic` version (e.g., `pip install ebcdic==1.1.1` for Python 3.4-3.8).","message":"Version 2.0.0 and later of the `ebcdic` package require Python 3.9 or newer. Older Python versions (2.7, 3.4-3.8) require `ebcdic` version 1.1.1, and even older versions (2.6, 3.1-3.3) require `ebcdic` version 1.0.0.","severity":"breaking","affected_versions":"2.0.0+"},{"fix":"Use `ebcdic.ignored_codec_names()` to see which codecs are provided by the standard library and thus 'ignored' by this package. If specific mappings are critical, test thoroughly or consider manual encoding/decoding if conflicts arise.","message":"Some EBCDIC codecs, such as 'cp037', 'cp273', 'cp500', and 'cp1140', may already be provided by Python's standard library and can 'overrule' or conflict with those provided by the `ebcdic` package. This might lead to unexpected behavior if specific mappings from the `ebcdic` package are expected.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always verify the exact EBCDIC code page used by the source system for your data. This information is crucial for accurate encoding and decoding operations.","message":"Using an incorrect EBCDIC code page (e.g., 'cp037' when the data is 'cp1047') will result in garbled or incorrect text during decoding. EBCDIC variants are not universally compatible.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always pass the appropriate EBCDIC code page to the `encoding` parameter of `open()` when reading or writing EBCDIC files: `with open('file.ebcdic', 'r', encoding='cp1047') as f:`.","message":"When performing file I/O with EBCDIC data, it is critical to explicitly specify the correct EBCDIC encoding (e.g., `encoding='cp500'`) in Python's `open()` function. Failing to do so will cause Python to attempt decoding with a default encoding (often UTF-8 or the system default), leading to `UnicodeDecodeError` or corrupted data.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}