██╗ ██╗ ██╗██████╗ ███████╗██████╗ ██╗
╚██╗██╔╝███║╚════██╗ ██╔════╝██╔══██╗██║
╚███╔╝ ╚██║ █████╔╝ █████╗ ██║ ██║██║
██╔██╗ ██║██╔═══╝ ██╔══╝ ██║ ██║██║
██╔╝ ██╗ ██║███████╗ ███████╗██████╔╝██║
╚═╝ ╚═╝ ╚═╝╚══════╝ ╚══════╝╚═════╝ ╚═╝
P Y T H O N T O O L K I T
The ultimate Python toolkit for X12 EDI processing
Parse, validate, and generate healthcare & supply chain transactions with HIPAA compliance
flowchart TB
subgraph Input["📄 Input"]
EDI[("EDI File\n837/835/850...")]
end
subgraph Core["⚙️ Core Engine"]
direction TB
TOK[Tokenizer] --> PARSE[Parser]
PARSE --> LOOP[Loop Builder]
LOOP --> VAL[Validator]
end
subgraph Schema["📋 Schema & Codes"]
direction TB
SCH[(Transaction\nSchemas)]
CODE[(Code\nSets)]
end
subgraph Output["📤 Output"]
direction TB
MODEL[Pydantic Models]
ACK[997/999 Acks]
GEN[EDI Generator]
end
EDI --> TOK
SCH -.-> VAL
CODE -.-> VAL
VAL --> MODEL
MODEL --> ACK
MODEL --> GEN
style Input fill:#e1f5fe
style Core fill:#fff3e0
style Schema fill:#f3e5f5
style Output fill:#e8f5e9
- Parsing - Parse X12 EDI documents with automatic delimiter detection
- Validation - Multi-level validation with HIPAA compliance checks
- Generation - Generate properly formatted X12 EDI output
- Streaming - Memory-bounded streaming for large files
- Acknowledgments - Generate 997/999 functional acknowledgments
- Schema Support - Schema-based validation for 837, 835, 270/271, 850
- Code Validation - NPI, Tax ID, ICD-10, CPT/HCPCS validation
- Trading Partners - Partner configuration management
pip install x12-python
Or install from source:
git clone https://github.com/copyleftdev/x12-python.git cd x12-python pip install -e .
from x12.core.parser import Parser # Parse EDI content parser = Parser() interchange = parser.parse(edi_content) # Access parsed data print(f"Sender: {interchange.sender_id}") print(f"Receiver: {interchange.receiver_id}") for group in interchange.functional_groups: for transaction in group.transaction_sets: print(f"Transaction: {transaction.transaction_set_id}")
from x12.core.validator import X12Validator validator = X12Validator() report = validator.validate(interchange) if report.is_valid: print("Document is valid!") else: for error in report.errors: print(f"Error: {error}")
from x12.core.generator import Generator from x12.models import Segment, Element generator = Generator() # Generate a segment segment = Segment( segment_id="NM1", elements=[ Element(value="85", index=1), Element(value="2", index=2), Element(value="ACME HOSPITAL", index=3), ] ) edi_output = generator.generate(segment) # Output: NM1*85*2*ACME HOSPITAL~
from x12.streaming import StreamingSegmentReader # Process large files with bounded memory with open("large_file.edi") as f: reader = StreamingSegmentReader(f) for segment in reader.segments(): process(segment)
from x12.acknowledgments import AcknowledgmentGenerator generator = AcknowledgmentGenerator( sender_id="RECEIVER", receiver_id="SENDER", ) # Generate 997 acknowledgment ack = generator.generate_997(functional_group)
| Transaction | Version | Description |
|---|---|---|
| 837P | 005010X222A1 | Health Care Claim: Professional |
| 837I | 005010X223A3 | Health Care Claim: Institutional |
| 837D | 005010X224A3 | Health Care Claim: Dental |
| 835 | 005010X221A1 | Health Care Claim Payment/Advice |
| 270/271 | 005010X279A1 | Eligibility Benefit Inquiry/Response |
| 276/277 | 005010X212 | Claim Status Request/Response |
| 834 | 005010X220A1 | Benefit Enrollment and Maintenance |
| 278 | 005010X217 | Health Care Services Review (Prior Auth) |
| 820 | 005010X218 | Premium Payment |
| Transaction | Description |
|---|---|
| 850 | Purchase Order |
| 855 | Purchase Order Acknowledgment |
| 856 | Ship Notice/Manifest (ASN) |
| 860 | Purchase Order Change |
| 810 | Invoice |
x12/
├── core/ # Parser, validator, generator, tokenizer
├── models/ # Segment, Element, Loop, Envelope models
├── schema/ # Schema definitions and loader
├── codes/ # Code set registry and validators
├── streaming/ # Memory-bounded streaming reader
├── acknowledgments/# 997/999 acknowledgment generation
├── trading_partners/ # Partner configuration
└── transactions/ # Transaction-specific models
├── healthcare/ # 837, 835, 270/271 models
└── supply_chain/ # 850, 856, 810 models
# Run all tests pytest tests/ # Run with coverage pytest tests/ --cov=x12 --cov-report=term-missing # Run specific test types pytest tests/unit -v pytest tests/integration -v pytest tests/property -v pytest tests/compliance -v pytest tests/performance -v
# Type checking mypy x12 --strict # Linting ruff check . ruff format .
This project follows Test-Driven Development (TDD):
- Write failing tests first (RED)
- Implement minimal code to pass (GREEN)
- Refactor while keeping tests green (REFACTOR)
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Quick start:
# Clone and setup git clone https://github.com/donjohnson/x12-edi-tools.git cd x12-edi-tools python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" # Run tests pytest tests/
Parser- Parse EDI content into structured objectsGenerator- Generate EDI output from objectsX12Validator- Validate EDI documentsTokenizer- Low-level EDI tokenizationDelimiters- Delimiter detection and configuration
Segment- X12 segment with elementsElement- Individual data elementLoop- Hierarchical loop structureInterchange- ISA/IEA envelopeFunctionalGroup- GS/GE envelopeTransactionSet- ST/SE envelope
SchemaLoader- Load schema definitionsTransactionSchema- Complete transaction schemaSegmentDefinition- Segment structure definitionElementDefinition- Element validation rules
CodeRegistry- Registry of code setsCodeSet- Set of valid codes with descriptionsvalidate_npi()- NPI validation with Luhn checkvalidate_tax_id()- EIN validationvalidate_diagnosis_code()- ICD-10 format validationvalidate_procedure_code()- CPT/HCPCS validation
TradingPartner- Partner configurationPartnerRegistry- Partner managementContactInfo- Contact information
See CHANGELOG.md for version history and release notes.
MIT License - see LICENSE for details.
Copyright (c) 2024 Don Johnson
Built following X12 standards from ASC X12 and HIPAA implementation guides.