Metadata-Version: 2.4
Name: benin-contacts
Version: 0.1.0
Summary: Normalize Beninese phone numbers (2024 ten-digit plan, E.164) and emails, with explicit statuses for every real-world anomaly
Author: Abiotov
License: MIT
Project-URL: Homepage, https://github.com/abiotov/benin-contacts
Project-URL: Issues, https://github.com/abiotov/benin-contacts/issues
Project-URL: Origin, https://github.com/abiotov/annuaire-benin
Keywords: benin,phone,e164,normalization,data-cleaning,msisdn
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: French
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Filters
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# benin-contacts

Normalize Beninese phone numbers and emails, with an explicit status for every
real-world anomaly. Battle-tested on 496,729 rows of Benin's national business
directory in the [annuaire-benin](https://github.com/abiotov/annuaire-benin)
pipeline.

On 30 November 2024, Benin migrated from an 8-digit to a 10-digit numbering
plan (every number gained the "01" prefix). Real datasets mix both eras, plus
lost leading zeros from numeric spreadsheet cells, country-code prefixes, and
numbers truncated by exports. This library converts everything convertible to
canonical E.164 (`+22901XXXXXXXX`) and **names** what it cannot convert instead
of guessing digits.

```python
from benin_contacts import normalize, extract_all, PhoneStatus

normalize("97 00 00 01")
# PhoneResult(raw='97 00 00 01', e164='+2290197000001', status=PhoneStatus.MIGRATED)

normalize(197000001)  # leading zero lost by a numeric cell
# PhoneResult(..., e164='+2290197000001', status=PhoneStatus.LEADING_ZERO_RESTORED)

normalize("01970001")  # 8 chars starting with 01: truncated by the export
# PhoneResult(..., e164=None, status=PhoneStatus.SUSPICIOUS_SHORT_01)

extract_all("97 00 00 01 / 96 00 00 02")  # multi-number cells
# [PhoneResult(...MIGRATED), PhoneResult(...MIGRATED)]
```

Statuses: `ALREADY_MIGRATED`, `MIGRATED`, `LEADING_ZERO_RESTORED`,
`SUSPICIOUS_SHORT_01`, `INVALID`, `EMPTY`. Each carries `status.is_valid`.
Email side: `benin_contacts.emails.normalize` (lowercasing, whitespace,
pragmatic syntax check).

```bash
pip install benin-contacts
```

## En français

Normalisation des numéros béninois vers le plan à 10 chiffres de novembre 2024
(format E.164), avec un statut explicite pour chaque anomalie : zéros de tête
perdus, indicatifs pays, cellules multi-numéros, et surtout les numéros
tronqués par un export (8 chiffres commençant par « 01 »), marqués plutôt que
« réparés » en inventant des chiffres. Validation syntaxique des emails.
Éprouvé sur les 496 729 lignes de l'annuaire national des entreprises du Bénin.

## License

MIT.
