free-decimal-correspondence 0.1.2

Free Decimal Classification lookup library

fdc — Free Decimal Classification

A Python library for looking up Free Decimal Classification codes. Built from the FDC correspondence file.

Quick start

from fdc import Label

label = Label.parse("976.4")
label.best   # '"Texas"'

for layer in label.layers:
    print(f"{layer.code}: {layer.label}")

# 9: History & geography
# 970: "America" + "North America"
# 976: "Gulf States" + "Southwest, Old"
# 976.4: "Texas"

Use .best to get the most specific resolved label without walking layers:

label = Label.parse("999.9")
label.best   # '"Outer Space"'  (last resolved layer)
label.layers[-1].label  # None (no entry for this exact code)

Pass raise_on_error=True for strict mode:

from fdc import Label
from fdc.label import LabelError

try:
    Label.parse("999.9", raise_on_error=True)
except LabelError:
    pass  # no entry for this code

Installing from PyPI

pip install free-decimal-correspondence

The package ships with a pre-built lookup table (fdc/_table.py) so parsing is never needed at runtime. The table is loaded into memory the first time you call Label.parse() - after that, lookups take roughly two microseconds.

Contributing

The taxonomy data lives in the classification/ submodule. If you improve it, rebuild the lookup table before committing:

python -m fdc.build

This regenerates fdc/_table.py from the text file. Commit both the submodule change and the regenerated table.