PyX12 - HIPAA X12 Parser and Validator

Common errors

• ModuleNotFoundError: No module named 'pyx12'

  cause The `pyx12` package is not installed in your current Python environment.
  fix Run `pip install pyx12` to install the library.

• pyx12.errors.X12MapNotFoundException: Can not find map file for ...

  cause The library could not locate the necessary X12 map (schema) file for the transaction set and version being processed, or the configured `X12_MAP_PATH` is incorrect.
  fix Ensure X12 map files are available and their directory is correctly specified via the `X12_MAP_PATH` environment variable or the `map_path` parameter when initializing `X12Message` or `X12N`.

• SyntaxError: invalid syntax (on line ...)

  cause You are attempting to run PyX12 v3.x (Python 3 only) code in a Python 2.x environment, or vice-versa with v2.x on Python 3 (less common).
  fix If using PyX12 v3.x, ensure you are running Python 3.6+. If you require Python 2.x compatibility, you must use PyX12 v2.x and its corresponding syntax.

Warnings

• breaking PyX12 version 3.0.0 and later are Python 3.6+ exclusive. Attempting to run v3.x code with Python 2.x will result in `SyntaxError` or other runtime failures.
  Fix: Ensure your environment uses Python 3.6 or newer for PyX12 v3.x. For Python 2.x compatibility, use PyX12 v2.x.
• gotcha Effective validation of X12 messages requires the correct X12 map (schema) files. These files are not shipped with the `pyx12` library and must be sourced and configured separately (e.g., via the `X12_MAP_PATH` environment variable or `map_path` parameter).
  Fix: Download appropriate X12 map files (e.g., from external sources or provided by your trading partner) and configure their location using the `X12_MAP_PATH` environment variable or by passing the `map_path` argument to `X12Message` or `X12N`.
• gotcha PyX12 provides low-level access to segments and elements. Extracting data into a simple Python dictionary or object structure for specific transaction sets often requires manual traversal and mapping logic, which is not automatically provided by the core library.
  Fix: Implement custom parsing logic on top of the `X12Message` and `X12N` classes to extract specific fields and loop data into your desired Python data structures.

Install

• pip install pyx12 Install PyX12
• pip install pyx12[xml] Install with XML support

Imports

• X12Message

  from pyx12.x12message import X12Message

• X12N

  from pyx12.map_walker import X12N

  X12N is used for walking and validating HIPAA transaction sets.

Quickstart

This quickstart demonstrates how to parse an X12 EDI file using `X12Message` and iterate through its segments. It also shows the basic setup for `X12N` for validation, though full validation requires proper configuration of X12 map files (schemas) which are not included in the basic installation.

import os
from pyx12.x12message import X12Message
from pyx12.map_walker import X12N

# Create a dummy X12 file for demonstration
edi_data = """ISA*00*          *00*          *ZZ*SENDERID       *ZZ*RECEIVERID     *200101*1200*U*00401*000000001*0*T*:~GS*HI*SENDER*RECEIVER*20010101*1200*1*X*004010VICS~ST*837*0001*005010X222~BHT*0019*00*01*20010101*1200*CH~HL*1**20*1~PRV*BI*PXC*01~NM1*85*1*SMITH*JOHN*P***XX*1234567890~PER*IC*JOHN SMITH*TE*5555551212~SE*10*0001~GE*1*1~IEA*1*000000001~"""

# Save the EDI data to a temporary file
file_path = "test_837.edi"
with open(file_path, "w") as f:
    f.write(edi_data)

# Initialize X12Message with the file
try:
    # Using a dummy map_path for basic parsing, real validation requires actual maps
    # For a full validation, set X12_MAP_PATH_INI or pass map_path parameter
    # Example: map_path = os.environ.get('X12_MAP_PATH', './maps')
    msg = X12Message(file_path)

    # Iterate through segments
    print("\n--- Segments --- ")
    for segment in msg.walk_segments():
        print(f"Segment: {segment.get_tag()}, Elements: {segment.get_elements()}")

    # Perform basic validation (requires map files to be configured or provided)
    print("\n--- Validation (requires map files) ---")
    # Note: For this quickstart, actual validation will likely fail without proper map setup.
    # Configure map paths via environment variable or 'map_path' parameter in X12N.
    # os.environ['X12_MAP_PATH'] = 'path/to/your/map/files'
    walker = X12N(msg)
    # validation_result = walker.validate()
    # print(f"Validation Result: {validation_result.get_state()}")
    print("Note: Full validation requires X12 map files. See documentation for setup.")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(file_path):
        os.remove(file_path)