pyiso8583

library4.0.1pypypi✓ verified 87d ago

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.

serialization aws data

pip install pyiso8583

github ↗package ↗

INSTALL

IMPORT

SIG · PYISO8583

pyiso8583

serializationpythonv4.0.1

Install

1.6s avg

Import

13ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.014s · 18MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.013s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

iso8583

✓ import iso8583

default_ascii

✓ from iso8583.specs import default_ascii as spec

DecodeError

✓ from iso8583.decoder import DecodeError

EncodeError

✓ from iso8583.encoder import EncodeError

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.

import iso8583 from iso8583.specs import default_ascii as spec import pprint # Example ISO8583 raw message (MTI '0200', Field 2 '1234567890', Field 12 '123456') encoded_raw_message = b'02004000000000000000101234567890123456' # Decode the message decoded_data, encoded_fields_info = iso8583.decode(encoded_raw_message, spec) print("Decoded data:") pprint.pprint(decoded_data) # Modify the decoded message for a response (e.g., '0210' response, add field 39) decoded_data['t'] = '0210' decoded_data['39'] = '00' # Encode the modified message back to raw bytes response_raw_message, response_encoded_fields_info = iso8583.encode(decoded_data, spec) print("\nEncoded response raw message:") print(response_raw_message) print("\nEncoded response fields info:") pprint.pprint(response_encoded_fields_info)

Debug

Known issues

breakingUpgrading 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.

fix

Consult the official 'Change Log' on Read the Docs for specific migration steps. Test your application thoroughly after upgrading.

affects: >=4.0.0

gotchaIncorrect 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.

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.

affects: All

gotchaHandling 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.

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).

affects: All

Errors

Common errors & fixes

iso8583.decoder.DecodeError: Message is too short: field <FIELD_NUMBER> pos <POSITION>

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.

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.

iso8583.encoder.EncodeError: Data length for field <FIELD_NUMBER> is <ACTUAL_LENGTH>, expected <EXPECTED_LENGTH>

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.

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.

TypeError: Decoded ISO8583 data must be dict, not <TYPE>

The `doc_dec` argument passed to `iso8583.encode()` was not a Python dictionary.

fix

Ensure that the first argument to `iso8583.encode()` is always a dictionary containing the ISO8583 field data.

TypeError: Encoded ISO8583 data must be bytes or bytearray, not <TYPE>

The `s` argument passed to `iso8583.decode()` was not a bytes or bytearray instance.

fix

Ensure that the first argument to `iso8583.decode()` is always a `bytes` or `bytearray` object representing the raw ISO8583 message.

Upgrade

Version history

4.0.1latest on PyPI · released Aug 28, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/knovichikhin/pyiso8583 ↗

packagehttps://pypi.org/project/pyiso8583/ ↗