Two-way fixed-width <--> Python dict converter

1.3 · maintenance · verified Sat Apr 11

The `fixedwidth` library provides a straightforward two-way converter for interacting with fixed-width data files or strings in Python. It facilitates easy serialization of Python dictionaries into fixed-width format and deserialization back into dictionaries, based on a user-defined configuration specification. Last updated in 2018 (v1.3), it has been used in production environments for several years and is considered stable, though not actively developed.

Warnings

gotcha The library requires a complete schema definition for all columns up to the maximum width specified. Attempting to parse or format data with gaps in the column definitions or an incomplete schema can lead to unexpected errors or incorrect parsing, as it expects a contiguous layout.
Fix: Ensure your configuration dictionary accounts for all character positions in the fixed-width string, even if some fields are merely padding or ignored data.
gotcha Configuration dictionary fields are strict. A field must define either `end_pos` or `length` in conjunction with `start_pos`. If both `end_pos` and `length` are provided, they must not conflict. Additionally, a `required` field cannot be assigned a `default` value.
Fix: Carefully review the field definitions in your configuration dictionary to adhere to the specified constraints regarding position, length, required status, and default values.
deprecated The `fixedwidth` library (v1.3) has not seen an update since June 2018. While stable and reported to be used in production, users should be aware of its unmaintained status, which might affect compatibility with newer Python versions or address new edge cases. For actively maintained alternatives, consider libraries like `pyfixwidth` or `pandas.read_fwf` for more robust fixed-width file parsing, especially for large datasets.
Fix: Assess the long-term maintenance risk. For new projects or if encountering compatibility issues, consider migrating to a more actively maintained library like `pyfixwidth` or `pandas.read_fwf`.

Install

pip install fixedwidth Install stable version

Imports

FixedWidth
```
from fixedwidth import FixedWidth
```

Quickstart

This quickstart demonstrates how to define a fixed-width specification using a configuration dictionary, then use the `FixedWidth` class to parse a fixed-width string into a Python dictionary and serialize a dictionary back into a fixed-width string.

from fixedwidth import FixedWidth

# Define the fixed-width specification
# A field must have a start_pos and either an end_pos or a length.
# If both end_pos and length are provided, they must not conflict.
# A field may not have a default value if it is required.
# Supported types: 'string', 'integer', 'decimal'.
config = {
    'name': {
        'start_pos': 0,
        'end_pos': 10,
        'type': 'string',
        'required': True,
        'alignment': 'left',
        'padding': ' ',
    },
    'age': {
        'start_pos': 10,
        'length': 3,
        'type': 'integer',
        'required': False,
        'alignment': 'right',
        'padding': '0',
    },
    'city': {
        'start_pos': 13,
        'length': 10,
        'type': 'string',
        'required': True,
        'alignment': 'left',
        'padding': ' ',
    },
}

# Create a FixedWidth instance
fixed_width_spec = FixedWidth(config)

# Example 1: Read from a fixed-width line
fixed_width_line_to_read = "John Doe  025New York   "
data_dict = fixed_width_spec.read(fixed_width_line_to_read)
print("Parsed data:", data_dict)
# Expected output: {'name': 'John Doe', 'age': 25, 'city': 'New York'}

# Example 2: Write to a fixed-width line
data_to_write = {'name': 'Jane Smith', 'age': 30, 'city': 'Los Angeles'}
fixed_width_line_written = fixed_width_spec.write(data_to_write)
print("Formatted line:", fixed_width_line_written)
# Expected output: "Jane Smith030Los Angeles "

view raw JSON →