Metadata-Version: 2.4
Name: free-decimal-correspondence
Version: 0.1.2
Summary: Free Decimal Classification lookup library
License: Apache-2.0
Project-URL: Source, https://github.com/thien/fdc
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# fdc — Free Decimal Classification

A Python library for looking up Free Decimal Classification codes.
Built from the [FDC correspondence file](https://github.com/JohnMarkOckerbloom/fdc).

## Quick start

```python
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:

```python
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:

```python
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

```bash
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:

```bash
python -m fdc.build
```

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


