Metadata-Version: 2.4
Name: bce-codes-to-label
Version: 0.2.0
Summary: Lookup labels for Belgian Crossroads Bank for Enterprises (BCE/KBO) codes
Author: Sagora
License-Expression: MIT
Keywords: bce,belgium,codes,enterprise,kbo,nace
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# bce-codes-to-label

Lookup labels for Belgian Crossroads Bank for Enterprises (BCE/KBO) codes.

Covers NACE codes, legal forms, joint committees, countries, postal codes, and more — with labels in French, Dutch, German, and English (where available).

## Installation

```bash
pip install bce-codes-to-label
```

## Quick start

```python
from bce_codes_to_label import joint_committees, countries, nace, lookup

# Each registry accepts three input forms:
joint_committees("jcc:m100")   # full BCE code
joint_committees("m100")       # suffix (part after ":")
joint_committees("100")        # value only

# Filter by language
countries("BE", lang="fr")
# {'_key': 'BE', '_code': 'cty:mBE', 'label_fr': 'Belgique'}

# Global lookup — returns a result only if there is a unique match across all registries
lookup("jcc:m100")
# {'_registry': 'joint_committees', 'label_fr': '...', '_key': '100', '_code': 'jcc:m100'}
```

## Available registries

| Registry | Prefix | Example | Description |
|---|---|---|---|
| `joint_committees` | `jcc:` | `joint_committees("100")` | Joint committees (commissions paritaires) |
| `nace` | `nace:` | `nace("2008:01110")` | NACE-BEL activity codes (2003 & 2008) |
| `currencies` | `ccy:` | `currencies("EUR")` | Currency codes |
| `countries` | `cty:` | `countries("BE")` | Country codes |
| `data_types` | `met:` | `data_types("am1")` | Data/metric types |
| `address_types` | `atc:` | `address_types("001")` | Address type codes |
| `commercial_courts` | `cct:` | `commercial_courts("31")` | Commercial courts |
| `mandate_functions` | `fct:` | `mandate_functions("10")` | Mandate/function labels |
| `legal_forms` | `lgf:` | `legal_forms("001")` | Legal form codes |
| `identifier_kinds` | `nmt:` | `identifier_kinds("1")` | Identifier kind-of-number labels |
| `sectors` | `sct:` | `sectors("01")` | Sector codes |
| `postal_codes` | `pcd:` | `postal_codes("1000")` | Belgian postal codes |
| `msca` | `msca:` | `msca("10/49")` | MSCA accounting codes |
| `rejection` | `rej:` | `rejection("PDF:11")` | Filing rejection codes |
| `models` | `mod:` | `models("m02-f")` | Annual accounts model types |

## API

### Registry call

```python
registry(query, lang=None)
```

- **query**: full BCE code (`"jcc:m100"`), suffix (`"m100"`), or value (`"100"`)
- **lang** (optional): `"fr"`, `"nl"`, `"de"`, or `"en"` — returns only that language's label
- Returns a `dict` with labels and metadata, a `list` if multiple matches, or `None` if not found

### Global lookup

```python
lookup(query, lang=None)
```

Searches all registries. Returns the match only if exactly one registry produces exactly one result. Returns `None` if ambiguous or not found.

### Utilities

```python
registry.all_keys()       # list all canonical keys
registry.get(query, lang) # alias for registry(query, lang)
```

## NACE codes

NACE codes include a version prefix since both 2003 and 2008 versions are available:

```python
from bce_codes_to_label import nace

nace("2008:01110")           # specific version + code
nace("nace:2008:m01110")     # full BCE code form
```

## Data structure

Each data file uses an efficient keyed format:

```json
{
  "code_prefix": "jcc:",
  "codes": {
    "100": {
      "label_fr": "Commission paritaire auxiliaire pour ouvriers",
      "label_nl": "Aanvullend PC voor de werklieden",
      "label_de": "die paritätische Hilfskommission für Arbeiter"
    }
  }
}
```

## Rebuilding data

Source JSON files live in `codes/`. To regenerate the optimized data files:

```bash
python scripts/build_data.py
```

## License

MIT