Maintained fork
Active development of this repository stopped in 2022. The project is continued as x12sdk, which keeps the models, parser and test corpus here and updates them for current runtimes: Pydantic v2 and Python 3.10–3.13. If you are starting a new project, or need a release that installs on a supported Python, use that fork. See #141 for the background.
LinuxForHealth x12 streams ASC 5010 X12 health care transactions into Pydantic Models for a pleasant pythonic parsing experience! Integration options include REST endpoints, CLI (command line), or direct access using the Python SDK.
Supported formats include:
- 005010X212 Claim Status
- 005010X221 Claim Payment
- 005010X222 Professional Claim
- 05010X223 Institutional Claim
- 005010X279 Eligibility
- 005010X220 Enrollment and Maintenance
The LinuxForHealth X12 development environment relies on the following software packages:
- git for project version control
- Python 3.8 or higher for runtime/coding support
pip install --upgrade pip setuptools
git clone https://github.com/LinuxForHealth/x12
cd x12
python3 -m venv venv && source venv/bin/activate && pip install --upgrade pip setuptools
pip install -e .[dev, api] # installs dev packages and optional API endpoint
pytestThe X12 SDK provides an io package which supports streaming X12 segments or transaction models. Segment
streaming parses each segment into a list containing the fields. Model streaming validates the X12 payload, and returns
one or transaction models from the X12 message.
To stream segments, create a X12SegmentReader instance:
from linuxforhealth.x12.io import X12SegmentReader
with X12SegmentReader("/home/edi/270.x12") as r:
# return the segment name and field list
for segment_name, segment_fields in r.segments():
print(segment_name)
print(segment_fields)To stream models, create a X12ModelReader instance:
from linuxforhealth.x12.io import X12ModelReader
with X12ModelReader("/home/edi/270.x12") as r:
for model in r.models():
# common model attributes include "header" and "footer"
print(model.header)
print(model.footer)
# to convert back to X12
model.x12()The X12 CLI parses a X12 input file and returns either a list of X12 segments, or a list of X12 models based on the provided options.
To view help information
user@mbp x12 % source venv/bin/activate
(venv) user@mbp x12 % lfhx12 --help
usage: LinuxForHealth X12 [-h] [-s | -m] [-x] [-p] file
The LinuxForHealth X12 CLI parses and validates X12 messages.
Messages are returned in JSON format in either a segment or transactional format.
positional arguments:
file The path to a ASC X12 file
optional arguments:
-h, --help show this help message and exit
-s, --segment Returns X12 segments
-m, --model Returns X12 models
-x, --exclude Exclude fields set to None in model output
-p, --pretty Pretty print outputTo parse a X12 message into segments with pretty printing enabled
(venv) user@mbp x12 % lfhx12 -s -p demo-file/demo.270
[
{
"ISA00": "ISA",
"ISA01": "03",
"ISA02": "9876543210",
<etc, etc>To parse a X12 message into models with pretty printing enabled
(venv) user@mbp x12 % lfhx12 -m -p demo-file/demo.270
[
{
"header": {
"st_segment": {
"delimiters": {
"element_separator": "*",
"repetition_separator": "^",
"segment_terminator": "~",
"component_separator": ":"
},
"segment_name": "ST",
"transaction_set_identifier_code": "270",
"transaction_set_control_number": "0001",
"implementation_convention_reference": "005010X279A1"
},
"bht_segment": {
<etc, etc>In "model" mode, the -x option excludes None values from output.
LinuxForHealth X12 includes an experimental "api" setup "extra" which activates a Fast API endpoint used to submit X12 payloads.
user@mbp x12 % source venv/bin/activate
(venv) user@mbp x12 % pip install -e ".[api]"
(venv) user@mbp x12 % lfhx12-apiBrowse to http://localhost:5000/docs to view the Open API UI.
API server configurations are located in the config module. The X12ApiConfig model
is a Pydantic Settings Model which can be configured using environment
variables.
user@mbp x12 % source venv/bin/activate
(venv) user@mbp x12 % export X12_UVICORN_PORT=5002
(venv) user@mbp x12 % lfhx12-apiLinuxForHealth X12 adheres to the Black Code Style and Convention
The following command executes the black formatter with default options
user@mbp x12 % source venv/bin/activate
(venv) user@mbp x12 % black ./srcUse the --help flag to view all available options for the black code formatter
(venv) user@mbp x12 % black --helpLinuxForHealth X12 is aligned, to a degree, with the PEP-517 standard. setup.cfg stores build metadata/configuration.
pyproject.toml contains the build toolchain specification and black formatter configurations.
The commands below creates a source and wheel distribution within a clean build environment.
python3 -m venv build-venv && source build-venv/bin/activate && pip install --upgrade pip setuptools build wheel twine
python3 -m build --no-isolation