benin-contacts 0.1.0

Normalize Beninese phone numbers (2024 ten-digit plan, E.164) and emails, with explicit statuses for every real-world anomaly

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 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.

from benin_contacts import normalize, extract_all, PhoneStatus

normalize("97 00 00 01")
# PhoneResult(raw='97 00 00 01', e164='[phone]', status=PhoneStatus.MIGRATED)

normalize(197000001)  # leading zero lost by a numeric cell
# PhoneResult(..., e164='[phone]', 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).

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.