Getting Started

Installation

Requires Python 3.10 or later.

Understanding the file structure

A fixed-width file has one or more of these row types:

Row type	Role
Header	First line with metadata (file date, type, etc.)
Detail	Data lines — can have multiple layouts
Footer	Last line with summary data (record counts, totals)

All rows in a file share the same line length.

Step 1 — Define your columns

Each column is an instance of a typed class from pyfwf.columns. The first argument is the field name, the second is the width in characters.

Step 2 — Define your row descriptors

Wrap each column list in the matching descriptor class from pyfwf.descriptors.

Then create a FileDescriptor that ties them together:

header and footer are optional. details must contain at least one DetailRowDescriptor.

Step 3 — Read the file

Pass an open file (or string, StringIO, or list of lines) and the FileDescriptor to Reader.

Each row is a plain dict mapping column names to typed Python values:

Step 4 — Write values back (to_str)

Each column also knows how to serialise a Python value back to a fixed-width string:

Rendering a Markdown table

You can render a FileDescriptor as a Markdown table — useful for documentation:

Output:

## Supported input types for Reader

Input type Notes
TextIOWrapper (open file)	Standard file object
StringIO	In-memory text stream
str	Raw string content
list	List of raw line strings

The newline argument defaults to “nr”. Pass “n” or “r” if your file uses a different line ending.