{"id":7573,"library":"pyiso8583","title":"pyiso8583","description":"pyiso8583 is a Python package designed for serializing and deserializing ISO8583 data. It converts raw ISO8583 byte streams into Python dictionaries and vice-versa, supporting various custom specifications for field lengths, data encoding (like BCD, ASCII, EBCDIC), and field types (fixed, LLVAR, LLLVAR). The current version is 4.0.1, with releases typically occurring a few times a year, indicating active development.","status":"active","version":"4.0.1","language":"en","source_language":"en","source_url":"https://github.com/knovichikhin/pyiso8583","tags":["iso8583","financial","protocol","serialization","deserialization"],"install":[{"cmd":"pip install pyiso8583","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"iso8583","correct":"import iso8583"},{"symbol":"default_ascii","correct":"from iso8583.specs import default_ascii as spec"},{"symbol":"DecodeError","correct":"from iso8583.decoder import DecodeError"},{"symbol":"EncodeError","correct":"from iso8583.encoder import EncodeError"}],"quickstart":{"code":"import iso8583\nfrom iso8583.specs import default_ascii as spec\nimport pprint\n\n# Example ISO8583 raw message (MTI '0200', Field 2 '1234567890', Field 12 '123456')\nencoded_raw_message = b'02004000000000000000101234567890123456'\n\n# Decode the message\ndecoded_data, encoded_fields_info = iso8583.decode(encoded_raw_message, spec)\nprint(\"Decoded data:\")\npprint.pprint(decoded_data)\n\n# Modify the decoded message for a response (e.g., '0210' response, add field 39)\ndecoded_data['t'] = '0210'\ndecoded_data['39'] = '00'\n\n# Encode the modified message back to raw bytes\nresponse_raw_message, response_encoded_fields_info = iso8583.encode(decoded_data, spec)\nprint(\"\\nEncoded response raw message:\")\nprint(response_raw_message)\nprint(\"\\nEncoded response fields info:\")\npprint.pprint(response_encoded_fields_info)","lang":"python","description":"This quickstart demonstrates how to decode a raw ISO8583 message using the default_ascii specification, modify some fields, and then encode it back into a raw bytearray. It uses `iso8583.decode` and `iso8583.encode` functions."},"warnings":[{"fix":"Consult the official 'Change Log' on Read the Docs for specific migration steps. Test your application thoroughly after upgrading.","message":"Upgrading from `pyiso8583` v3.x.x to v4.x.x may introduce breaking changes. Always review the 'Change Log' in the official documentation before upgrading major versions to understand API modifications, especially around specification structures or function signatures.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Refer to the 'Specifications' section in the documentation (iso8583.specs module) for detailed guidance on creating and validating custom specifications. Pay close attention to `len_count`, `data_enc`, `left_pad`, and `right_pad` for complex field types.","message":"Incorrect or incomplete ISO8583 specifications are a common source of encoding/decoding errors. Ensure your custom specifications accurately define field lengths, data encoding, and types for all expected fields, including proper handling of binary or BCD data padding.","severity":"gotcha","affected_versions":"All"},{"fix":"When defining fields with `data_enc` set to 'b' (binary/BCD) and `len_count` set to 'nibbles', ensure you explicitly define either `left_pad` or `right_pad` with the appropriate padding digit (0-F).","message":"Handling odd-length binary or BCD fields requires specific padding configuration within the field specification (e.g., `left_pad` or `right_pad`). Failure to specify this can lead to incorrect message parsing or generation.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the integrity of the incoming raw ISO8583 message. Check your `spec` dictionary, particularly the `max_len` and `len_type` properties for the reported field, to ensure they correctly match the message format.","cause":"The raw ISO8583 message bytearray is shorter than expected based on the provided specification, or a field's declared length exceeds the remaining message bytes.","error":"iso8583.decoder.DecodeError: Message is too short: field <FIELD_NUMBER> pos <POSITION>"},{"fix":"Review the data being assigned to the field in your Python dictionary (`doc_dec`) and compare it against the `max_len`, `len_type`, and `data_enc` defined for that field in your `spec` dictionary. Adjust the data or the specification to ensure they are compatible.","cause":"The data provided in the Python dictionary for a specific ISO8583 field does not match the length or format expected by the field's definition in the specification.","error":"iso8583.encoder.EncodeError: Data length for field <FIELD_NUMBER> is <ACTUAL_LENGTH>, expected <EXPECTED_LENGTH>"},{"fix":"Ensure that the first argument to `iso8583.encode()` is always a dictionary containing the ISO8583 field data.","cause":"The `doc_dec` argument passed to `iso8583.encode()` was not a Python dictionary.","error":"TypeError: Decoded ISO8583 data must be dict, not <TYPE>"},{"fix":"Ensure that the first argument to `iso8583.decode()` is always a `bytes` or `bytearray` object representing the raw ISO8583 message.","cause":"The `s` argument passed to `iso8583.decode()` was not a bytes or bytearray instance.","error":"TypeError: Encoded ISO8583 data must be bytes or bytearray, not <TYPE>"}]}