pydifact

Pydifact provides a framework for extending its functionality via plugins, following the Simple Plugin Framework pattern. To create a plugin, you can use the PluginMount metaclass.

Specifically, the SegmentProvider class in pydifact.segments uses PluginMount, meaning it is designed to be extensible through plugins.

The Segment class is a low-level internal class. To implement specialized EDIFACT segments, you should subclass Segment.

When subclassing, you must:

1. Provide a tag attribute (the 3-letter uppercase alphanumeric segment code).
2. Implement a validate() method to handle segment-specific validation logic.

If you do not set __omitted__ = True in your subclass, it will be automatically registered in the Segment.plugins list, making it available via the SegmentFactory.

from pydifact.segments import Segment

class MyCustomSegment(Segment):
    tag = "ABC"
    
    def validate(self, syntax_version: str, directory: str) -> None:
        # Custom validation logic here
        pass

The Interchange class provides factory methods to instantiate an EDIFACT interchange from raw data.

• Interchange.from_str(string, parser=None, characters=None): Parses an EDIFACT string into an Interchange instance.
• Interchange.from_file(file, encoding='iso8859-1', parser=None): Reads an EDIFACT file from disk using the specified encoding and parses it.

Note: If the input contains a UNA segment, the Interchange will automatically update its control characters and set the has_una_segment flag.

from pydifact.segmentcollection import Interchange

# From string
interchange = Interchange.from_str("UNB+...\n...UNZ+...")

# From file
interchange = Interchange.from_file("data.edi", encoding="utf-8")

An Interchange can contain multiple messages. Use get_messages() to iterate through them. This method parses the segments between UNH (header) and UNT (footer) tags into Message objects.

If the interchange structure is invalid (e.g., a UNH is not closed by a UNT), an EDISyntaxError will be raised.

for message in interchange.get_messages():
    print(f"Message Type: {message.type}, Version: {message.version}")
    # Process message segments...

The Parser.get_control_characters static method allows you to extract the EDI control characters from a message string (specifically looking for the UNA segment) without performing a full parse.

This is useful if you need to know the delimiters used in a file before deciding how to process it. If the message does not start with UNA, it returns the provided characters object (which defaults to standard EDIFACT characters if none are provided).

from pydifact.parser import Parser
from pydifact.control import Characters

# Example message starting with UNA
message = "UNA:+.? '"

# Extract characters
chars = Parser.get_control_characters(message)
print(chars.segment_terminator) # Output depends on the UNA content

To convert an Interchange or Message back into a raw EDIFACT string, use the serialize() method. This method automatically includes the header and footer segments.

• serialize(break_lines=False): Returns the string representation. If break_lines is True, a line break is inserted after each segment terminator (note: this is common in practice but technically forbidden in some EDIFACT specs).
• __str__(): Calling str(container) is equivalent to calling serialize().

edi_string = interchange.serialize(break_lines=True)

The core data structures in pydifact are:

• Segment: Represents a single EDIFACT segment (a group of elements).
• Token: Represents the smallest unit of data within a segment.
• Tokenizer: Used for breaking down raw text into Token objects.
• Characters: Handles EDIFACT-specific character sets and control characters.