oxedi835

A fast EDI 835 (electronic remittance advice) parser for Python, written in Rust.

• Lossless. Every byte of the file is kept, so write() returns the file exactly as it was read.
• Ready-made tables. Payments, claims, service lines and adjustments come out as typed tables that open in Polars, pandas, pyarrow or DuckDB without copying the data.
• Problems are reported, not raised. A file that is valid EDI but has questionable data still parses; each issue is returned as a diagnostic that names the rule, the position and the value.
• Large files. stream yields one transaction at a time, so memory stays bounded.
• Extensible. Add segments or table columns with a small JSON patch, without touching the code.

Install

pip install oxedi835               # no Python dependencies
pip install "oxedi835[polars]"     # with Polars
pip install "oxedi835[pandas]"     # with pandas and pyarrow

Requires Python 3.11 or later. Wheels are available for Linux (x86_64 and aarch64, plus musl on x86_64), macOS (Intel and Apple silicon) and Windows (x86_64).

Quick start

import oxedi835

result = oxedi835.parse_file("remittance.835")

claims = result.tables["claims"].to_polars()      # or .to_pandas()
services = result.tables["services"].to_polars()

print(result.count_claims(), result.sum_payments())  # sum_payments() is a Decimal
print(result.payer["name"], result.payee["name"])

for diagnostic in result.diagnostics:
    print(diagnostic)

oxedi835.parse(data) does the same from bytes. A file that is not an 835 at all (for example, one that does not start with an ISA segment) raises oxedi835.ParseError.

Tables

result.tables.keys() lists them and table.columns lists a table's columns. Amounts are decimals, dates are dates, and text fields are kept as the raw bytes from the file (Arrow binary), so nothing is lost to an encoding guess. Tables follow the Arrow PyCapsule interface, so any Arrow-aware library reads them directly:

import duckdb, polars as pl

claims = result.tables["claims"]
duckdb.sql("select claim_status, sum(payment_amount) from claims group by 1")
pl.DataFrame(result.tables["services"])

Large files

from pathlib import Path

for batch in oxedi835.stream(Path("big.835").read_bytes()):
    services = batch.tables["services"].to_polars()

Each batch holds the tables and diagnostics of one transaction. Pass by="2100" (or any other loop id) to get one batch per claim instead. Parsing releases the GIL, so several files can be parsed in parallel from threads.

Writing the file back

data = Path("remittance.835").read_bytes()
assert oxedi835.parse(data).document.write() == data

Extending the spec

The structure of the 835 and the columns of each table are defined by a JSON spec. A patch in JSON Merge Patch format (RFC 7386) adapts it to a payer's variations:

spec = oxedi835.Spec.builtin().patch({
    "tables": {"claims": {"columns": {
        "contract_class": {"segment": "REF", "where": {"1": "CE"}, "element": 2}
    }}}
})
result = oxedi835.parse(data, spec=spec)   # claims now has a contract_class column

Objects merge key by key, while arrays are replaced whole: to allow an extra segment in a loop, list the loop's full segments:

{"loops": {"1000A": {"segments": ["N3", "N4", "REF", "PER", "XX"]}}}

parse and stream both accept spec=.

Coming from another library

Coming from edi-835-parser? See the migration guide.

Versioning

The project follows semantic versioning. While the version is 0.x, a minor release may change the API. See the changelog.

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.