description: chiptime Python API entry points: parse, iter_messages, iter_frames, repair, validate — one call, then navigate plain data.¶

Python API — core¶

Five entry points, one mental model: make one call, then navigate the result (the object tree). There are no sessions to open, no configuration objects, no state to manage — every function is input → complete result.

Which entry point?¶

You want	Call
The workout, fully interpreted	`parse` — the main call, 99% of uses
To stream a huge file in constant memory	`iter_messages`
Wire-level bytes forensics	`iter_frames`
A broken file made uploadable	`repair`
"Will this platform accept it?"	`validate`

parse reads everything into a ParseResult; the iterators yield as they go and skip the semantic layer entirely. repair and validate are built on parse — they see exactly what it sees.

Parse¶

chiptime.parse ¶

parse(
    src: Source,
    *,
    mode: Mode = "lenient",
    strip_pii: bool = False,
    include_unknown: bool = True,
    include_raw: bool = False,
) -> ParseResult

Parse a FIT source. lenient (default) recovers and annotates; strict raises the first FitError; forensic maximizes salvage and never drops.

Stream without the semantic layer¶

chiptime.iter_messages ¶

iter_messages(
    src: Source, *, mode: Mode = "lenient"
) -> Iterator[Message]

Profile-applied message stream without building the semantic model.

chiptime.iter_frames ¶

iter_frames(
    src: Source, *, mode: Mode = "lenient"
) -> Iterator[FrameEvent]

Lossless wire-level frame events (forensics layer).

Repair¶

chiptime.repair ¶

Repair: salvage → synthesize missing structure → valid canonical .fit.

Every synthesis lands in provenance (REPAIR_*). Genuinely absent data is refused, never fabricated (taxonomy #16, contract #8).

RepairResult `dataclass` ¶

A repaired file plus the proof of what repair did.

Attributes:

Name	Type	Description
`data`	`bytes`	The complete, valid `.fit` bytes — write them to disk as-is.
`provenance`	`list[ProvenanceEntry]`	Every salvaged, synthesized, and dropped element.
`output_strict_ok`	`bool`	Self-check — the output re-parsed in strict mode.
`parse_result`	`ParseResult \| None`	The salvage parse of the input, for inspection.

Validate¶

chiptime.validate.validate ¶

validate(
    src: Source, platform: Platform = "strict-spec"
) -> list[Finding]