icfpy

A pure-Python library to parse, validate, build in-memory, write, and convert Indent Comma Format (ICF) files, plus generate ICX companion index files.

• Implements the ICF language specification v1.1 — schema annotations (!indexes / !defaults / !constraints / !expressions), row !overrides, primary objects, defaults + overrides resolution, and multiline value rows — while staying fully backward compatible with v1.0 documents.
• Implements the ICX index specification v1.2 — auto-harvested Tags, per-record Summary providers, @sourcebytes, join_tags/split_tags helpers — plus the resolved export icfpy.write_resolved(...) that bakes defaults/overrides into plain ICF output.
• Python 3.9+, zero runtime dependencies (standard library only).
• JSON output is hand-rolled — no third-party JSON/CSV/XML library.
• A faithful behavioral port of the Java library icfj.

What is ICF?

ICF is a compact, hierarchical, schema-driven data format that combines the compactness of CSV, the readability of YAML, and the hierarchy of JSON/XML. A document declares its schema once (@schema), optionally carries user metadata (@metadata) and shared reference data (@masters), then stores records positionally (@data / @record) as comma-separated rows. See the ICF and ICX specifications for the full format definition.

Install

pip install icfpy

For development from a checkout (with the dev tools):

pip install -e ".[dev]"

Quickstart

import icfpy

# 1. Parse ICF text (or a file path) and navigate the data.
doc = icfpy.parse(open("invoice.icf", encoding="utf-8").read())
data = doc.to_icf_node()
city = data.path("indexdata").path("masterindex").path("Project").path("Location").as_text()

# `path(...)` never raises — absent fields yield IcfMissing, so chains are safe.
missing = data.path("nope").path("still_nope").as_text()   # -> ""

# 2. Validate (never raises on content problems).
result = icfpy.validate(icf_text)
if not result.is_valid:
    for err in result.errors:
        print(err)        # e.g. "ERROR (line 7) [FIELD_COUNT_MISMATCH] ..."

# 3. Build a node from scratch and write it back to ICF text.
root = icfpy.IcfNode.object()
root.put_object("vendor").put("id", "V001").put("email", "v@example.com")
root.put_array("items").add_object().put("sku", "A1").put("qty", 100)
icf = icfpy.write(root)   # infers a schema; object -> one record, array -> many

# 4. Generate the ICX companion index and serialize it.
source = icfpy.parse(icf)
icx_doc = icfpy.generate_icx(source, "invoice.icf", icf)   # populates Line/Offset/Size/Checksum
icx_text = icfpy.write(icx_doc)

Facade API

See DOCUMENTATION.md for the complete public API and CLAUDE.md for the spec gotchas that shape the implementation.

Development

pip install -e .[dev]
pytest              # run the test suite (includes four round-trip fixtures)
ruff check .        # lint
ruff format --check .
mypy src/icfpy      # type-check

License

Copyright (c) 2026 Edison Williams. The ICF/ICX specifications are licensed under CC BY 4.0. The icfpy library is licensed under MIT License.