Install & Compatibility
Where this runs
tested against v0.2.3 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.089s · 18.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.080s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Interchange
✓ from pydifact.segmentcollection import Interchange
✗ from pydifact.segmentcollection import SegmentCollection
`SegmentCollection` was removed/deprecated in versions 0.2.x+ in favor of `Interchange`.
Segment
✓ from pydifact.segments import Segment
This quickstart demonstrates how to parse an EDIFACT interchange from a string and iterate through its messages and segments. It also shows how to construct a new interchange programmatically and serialize it into an EDIFACT string.
from pydifact.segmentcollection import Interchange
from pydifact.segments import Segment
# Example EDIFACT data (Interchange containing one message)
edifact_data = (
"UNA:+,? '\n"
"UNB+UNOC:1+1234+3333+200102:2212+42'\n"
"UNH+42z42+PAORES:93:1:IA'\n"
"MSG+1:45'\n"
"IFT+3+XYZCOMPANY AVAILABILITY'\n"
"ERC+A7V:1:AMD'\n"
"UNT+5+42z42'\n"
"UNZ+2+42'"
)
# --- Reading an EDIFACT interchange from a string ---
interchange = Interchange.from_str(edifact_data)
print("\n--- Reading Interchange ---")
for message in interchange.get_messages():
for segment in message.segments:
print(f"Segment tag: {segment.tag}, content: {segment.elements}")
# --- Creating an EDIFACT interchange ---
new_interchange = Interchange()
new_interchange.add_segment(Segment("UNA", [":", "+", ",", "?", " ", "'"])) # Optional, if custom control characters are needed
new_interchange.add_segment(Segment("UNB", ["UNOC:1", "SENDER", "RECEIVER", "20230101:1000", "REF123"]))
new_message = new_interchange.new_message("ORDER", "D", "96A", "UN")
new_message.add_segment(Segment("BGM", ["220", "ORDER123"]))
new_message.add_segment(Segment("DTM", ["137:20230101:1000"]))
new_interchange.add_message(new_message)
print("\n--- Serializing Interchange ---")
print(new_interchange.serialize(break_lines=True))
Debug
Known issues
breakingThe API is not yet stable and frequent breaking changes can occur between minor versions. Always consult the `CHANGELOG.md` before upgrading.fixPin your `pydifact` version in `requirements.txt` to prevent unexpected upgrades, or thoroughly review the changelog before updating.
affects: All versions < 1.0.0
breakingThe `SegmentCollection` class has been removed/deprecated. Functionality has been moved to the `Interchange` and `Message` classes.fixReplace `SegmentCollection` instances with `Interchange` for top-level EDIFACT documents and `Message` for individual messages within an interchange.
affects: 0.2.x+
breakingCalls to `Segment()` now *must* provide the segment tag name as the first positional parameter.fixUpdate `Segment()` instantiations to `Segment('TAG', ['element1', 'element2'])` instead of `Segment(['element1', 'element2'])` (if that syntax was previously supported or inferred). affects: 0.2.x+
breakingSupport for Python versions older than 3.10 has been dropped.fixEnsure your project runs on Python 3.10 or a newer version to use `pydifact` 0.2.x and above. For older Python versions, you must use an older `pydifact` release (e.g., < 0.2.0).
affects: 0.2.x+
gotchaWhen defining custom control characters, if you previously used positional arguments instead of keyword arguments, the introduction of a 'reserved' character parameter in some versions might shift argument positions and cause unexpected behavior.fixAlways use keyword arguments (e.g., `Characters(data_separator='|')`) when instantiating `pydifact.control.Characters` to ensure forward compatibility.
affects: 0.1.9
Errors
Common errors & fixes
AttributeError: module 'collections' has no attribute 'Iterable'
This error typically occurs when using an older version of `pydifact` (e.g., <0.2.0) with Python 3.10 or newer. Python 3.10 removed `collections.Iterable` in favor of `collections.abc.Iterable`.
fixUpgrade `pydifact` to version 0.2.0 or higher: `pip install --upgrade pydifact`. These versions explicitly require Python >=3.10 and correctly use `collections.abc.Iterable`.
EdiFactSyntaxError: ...
Pydifact is designed to raise `EdiFactSyntaxError` when it encounters malformed EDIFACT syntax, rather than silently attempting to parse or ignore errors.
fixImplement proper error handling (e.g., `try-except EdiFactSyntaxError`) around parsing operations, or preprocess/validate EDIFACT files to ensure they conform to the expected syntax before feeding them to pydifact.
My code only reads the first message, not all messages in an interchange.
Users sometimes confuse the `Interchange` and `Message` classes or assume direct iteration over `Interchange` yields messages. The `Interchange` object represents the entire EDIFACT file, which can contain multiple messages.
fixAfter creating an `Interchange` object, you must explicitly call `interchange.get_messages()` to retrieve an iterable of `Message` objects. Then, iterate over each `Message` to access its `segments` property.
Upgrade
Version history
0.2.3latest on PyPI · released Apr 10, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer for full compatibility and to avoid `AttributeError` with `collections.Iterable`.