Writing

Turn tables back into an 835. See Writing for the guide.

write

write(
    tables: TablesLike,
    envelope: Envelope,
    spec: Optional[Spec] = None,
    allow_findings: Literal[False] = False,
) -> bytes

write(
    tables: TablesLike,
    envelope: Envelope,
    spec: Optional[Spec] = None,
    *,
    allow_findings: Literal[True],
) -> tuple[bytes, list[WriteFinding]]

write(
    tables: TablesLike,
    envelope: Envelope,
    spec: Optional[Spec] = None,
    allow_findings: bool = False,
) -> Union[bytes, tuple[bytes, list[WriteFinding]]]

write(
    tables: TablesLike,
    envelope: Envelope,
    spec: Optional[Spec] = None,
    allow_findings: bool = False,
) -> Union[bytes, tuple[bytes, list[WriteFinding]]]

Writes tables with a spec's schema as one interchange.

tables is the tables of a parse, or a mapping of table names to Arrow, Polars or pandas tables with the spec's columns (a table left out has no rows, a column left out is null). spec defaults to the spec that parsed the tables, else the built-in 5010 spec. The written file is read back with the spec, and every diagnostic of that read is a finding.

A null cell in the middle of a segment is written as an empty element, which reads back as empty text; only trailing nulls read back as null.

Strict by default: any finding raises WriteError and nothing is returned. With allow_findings the bytes are returned with the findings, (bytes, findings). When a value holds a delimiter the file is not read back, so the findings then lack those of reading it.

Envelope

Who sends and receives an interchange, when, its first control number and its delimiters. The writer derives the rest of the envelope: counts, later control numbers, codes and fixed widths.

sender_id property

sender_id: str

The sender id.

sender_qualifier property

sender_qualifier: str

The sender id's qualifier.

receiver_id property

receiver_id: str

The receiver id.

receiver_qualifier property

receiver_qualifier: str

The receiver id's qualifier.

usage_indicator property

usage_indicator: str

The usage indicator, e.g. P (production) or T (test).

control_number property

control_number: int

The first control number.

date property

date: date

The date.

time property

time: time

The time.

application_sender property

application_sender: Optional[str]

The functional group's sender code, when it is not the sender id.

application_receiver property

application_receiver: Optional[str]

The functional group's receiver code, when it is not the receiver id.

line_break property

line_break: bool

Whether a line break follows each segment.

delimiters property

delimiters: Delimiters

The delimiters written.

__new__

__new__(
    *,
    sender_id: str,
    receiver_id: str,
    date: date,
    time: time,
    sender_qualifier: str = "ZZ",
    receiver_qualifier: str = "ZZ",
    usage_indicator: str = "P",
    control_number: int = 1,
    application_sender: Optional[str] = None,
    application_receiver: Optional[str] = None,
    delimiters: Optional[Delimiters] = None,
    line_break: bool = False,
) -> Envelope

date (a datetime.date) and time (a datetime.time without a time zone, whole seconds) stamp the interchange and the group: the interchange header holds the date without its century and the time without its seconds, the group header keeps both. delimiters defaults to *, :, ~ and the repetition separator ^; line_break adds a line break after each segment.

WriteError

Bases: ValueError

Tables that cannot be written as a valid file; nothing was written.

The message names every reason: the rule, where (table, row and column, or envelope field) and the value. findings holds them one by one; it is empty when the refusal is about the spec, the tables' columns or the delimiters rather than about the data.

WriteFinding

One reason tables do not make a valid file. A value, never raised.

kind property

kind: str

The kind of finding, e.g. MissingParent or ReadBack.

table property

table: Optional[str]

The table at fault, when a table is.

row property

row: Optional[int]

The row at fault (its position in the table), when a row is.

column property

column: Optional[str]

The column at fault, when a column is.

field property

field: Optional[str]

The envelope field at fault, when one is.

diagnostic property

diagnostic: Optional[Diagnostic]

The diagnostic of reading the written file back, for a ReadBack.

message property

message: str

The finding as one sentence: the rule, where and the value.