mboka 0.0.1__tar.gz

mboka-0.0.1/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+build/
+.pytest_cache/
+.DS_Store
+.env

mboka-0.0.1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: mboka
+Version: 0.0.1
+Summary: Local data and helpers for Congo-Brazzaville: +242 phone numbers, administrative divisions, FCFA amounts.
+Project-URL: Homepage, https://github.com/mboka-dev/core
+Project-URL: Issues, https://github.com/mboka-dev/core/issues
+Author: Akieni Academy and contributors
+License-Expression: MIT
+Keywords: africa,brazzaville,congo,fcfa,geo,phone,xaf
+Classifier: Natural Language :: French
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mboka
+
+Local data and helpers for Congo-Brazzaville: +242 phone numbers, administrative divisions, FCFA amounts. No dependencies.
+
+```bash
+pip install mboka
+```
+
+```python
+from mboka import phone, money
+
+phone.parse("06 123 45 67")["e164"]   # '+242061234567'
+money.format(125000)                  # '125 000 FCFA'
+```
+
+Documentation (in French): https://github.com/mboka-dev/core

mboka-0.0.1/README.md

@@ -0,0 +1,16 @@
+# mboka
+
+Local data and helpers for Congo-Brazzaville: +242 phone numbers, administrative divisions, FCFA amounts. No dependencies.
+
+```bash
+pip install mboka
+```
+
+```python
+from mboka import phone, money
+
+phone.parse("06 123 45 67")["e164"]   # '+242061234567'
+money.format(125000)                  # '125 000 FCFA'
+```
+
+Documentation (in French): https://github.com/mboka-dev/core

mboka-0.0.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mboka"
+version = "0.0.1"
+description = "Local data and helpers for Congo-Brazzaville: +242 phone numbers, administrative divisions, FCFA amounts."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Akieni Academy and contributors" }]
+keywords = ["congo", "brazzaville", "phone", "fcfa", "xaf", "geo", "africa"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Natural Language :: French",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/mboka-dev/core"
+Issues = "https://github.com/mboka-dev/core/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mboka"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

mboka-0.0.1/src/mboka/__init__.py

@@ -0,0 +1,6 @@
+"""Local data and helpers for Congo-Brazzaville."""
+
+from . import geo, money, phone, text
+
+__version__ = "0.0.1"
+__all__ = ["geo", "money", "phone", "text", "__version__"]

mboka-0.0.1/src/mboka/_data.py

@@ -0,0 +1,14 @@
+"""Loads the JSON files shipped in the package (copied from /data by `npm run sync`)."""
+
+import json
+from functools import cache
+from importlib.resources import files
+from typing import Any
+
+
+@cache
+def load(relative_path: str) -> Any:
+    resource = files("mboka").joinpath("data", *relative_path.split("/"))
+    content = json.loads(resource.read_text(encoding="utf-8"))
+    content.pop("$schema", None)
+    return content

mboka-0.0.1/src/mboka/data/geo/arrondissements.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "../schema/arrondissements.schema.json",
+  "items": []
+}

mboka-0.0.1/src/mboka/data/geo/communes.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "../schema/communes.schema.json",
+  "items": []
+}

mboka-0.0.1/src/mboka/data/geo/departements.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "../schema/departements.schema.json",
+  "items": []
+}

mboka-0.0.1/src/mboka/data/phone/numerotation.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "../schema/numerotation.schema.json",
+  "countryCode": "242",
+  "nationalNumberLength": 9,
+  "nationalGrouping": [2, 3, 2, 2],
+  "verification": {
+    "status": "a_verifier",
+    "note": "Bootstrap value. To be confirmed against the national numbering plan published by the regulator (issue #2)."
+  },
+  "prefixes": [
+    {
+      "prefix": "06",
+      "type": "mobile",
+      "operator": "MTN",
+      "verification": { "status": "a_verifier", "note": "Bootstrap value, see issue #2." }
+    },
+    {
+      "prefix": "05",
+      "type": "mobile",
+      "operator": "Airtel",
+      "verification": { "status": "a_verifier", "note": "Bootstrap value, see issue #2." }
+    }
+  ]
+}

mboka-0.0.1/src/mboka/geo.py

@@ -0,0 +1,61 @@
+import copy
+from typing import Any, Literal, Optional
+
+from ._data import load
+from .text import normalize
+
+Level = Literal["departement", "commune", "arrondissement"]
+_FILES: dict[str, str] = {
+    "departement": "geo/departements.json",
+    "commune": "geo/communes.json",
+    "arrondissement": "geo/arrondissements.json",
+}
+
+
+def _items(level: str) -> list[dict[str, Any]]:
+    return load(_FILES[level])["items"]
+
+
+def departements() -> list[dict[str, Any]]:
+    return copy.deepcopy(_items("departement"))
+
+
+def communes(departement_id: Optional[str] = None) -> list[dict[str, Any]]:
+    items = _items("commune")
+    if departement_id:
+        items = [c for c in items if c["departement"] == departement_id]
+    return copy.deepcopy(items)
+
+
+def arrondissements(commune_id: Optional[str] = None) -> list[dict[str, Any]]:
+    items = _items("arrondissement")
+    if commune_id:
+        items = [a for a in items if a["commune"] == commune_id]
+    return copy.deepcopy(items)
+
+
+def find_all(name: str, level: Optional[Level] = None) -> list[dict[str, Any]]:
+    """All entries whose official name or alias matches, in order: départements, communes, arrondissements."""
+    needle = normalize(name)
+    if not needle:
+        return []
+    results = []
+    for lvl in _FILES:
+        if level and level != lvl:
+            continue
+        for entry in _items(lvl):
+            if any(normalize(n) == needle for n in [entry["nom"], *entry["aliases"]]):
+                results.append({"level": lvl, **copy.deepcopy(entry)})
+    return results
+
+
+def find(name: str, level: Optional[Level] = None) -> Optional[dict[str, Any]]:
+    """First exact match after normalization, or None. Fuzzy matching is planned for v0.3."""
+    matches = find_all(name, level)
+    return matches[0] if matches else None
+
+
+def normalize_name(name: str) -> Optional[str]:
+    """Official name for a free-text input, or None if unknown. Handy to clean a data column."""
+    match = find(name)
+    return match["nom"] if match else None

mboka-0.0.1/src/mboka/money.py

@@ -0,0 +1,32 @@
+from typing import Literal
+
+NARROW_NBSP = " "
+NBSP = " "
+
+
+def _check_amount(amount: object, fn: str) -> int:
+    if isinstance(amount, bool) or not isinstance(amount, (int, float)):
+        raise TypeError(f"money.{fn} expects a number")
+    if isinstance(amount, float):
+        raise ValueError(f"money.{fn} expects an integer amount: the CFA franc has no subunit")
+    return amount
+
+
+def format(amount: int, label: str = "FCFA", separator: str = NARROW_NBSP) -> str:  # noqa: A001
+    """format(125000) == '125 000 FCFA' (non-breaking spaces)."""
+    value = _check_amount(amount, "format")
+    sign = "-" if value < 0 else ""
+    grouped = f"{abs(value):,}".replace(",", separator)
+    return f"{sign}{grouped}{NBSP}{label}" if label else f"{sign}{grouped}"
+
+
+def to_words(amount: int, currency: bool = True,
+             orthographe: Literal["traditionnelle", "1990"] = "traditionnelle") -> str:
+    """Amount in words: to_words(125000) == 'cent vingt-cinq mille francs CFA'.
+
+    Specified by fixtures/money/to-words.json. Not implemented yet: see the open issue.
+    """
+    _check_amount(amount, "to_words")
+    raise NotImplementedError(
+        "money.to_words is not implemented yet. Contributions welcome: see fixtures/money/to-words.json"
+    )

mboka-0.0.1/src/mboka/phone.py

@@ -0,0 +1,98 @@
+import re
+from typing import Any, Literal, Optional, TypedDict
+
+from ._data import load
+
+InvalidReason = Literal["empty", "invalid_characters", "foreign_number", "length", "unknown_prefix"]
+FormatStyle = Literal["national", "international", "e164"]
+
+_SEPARATORS = re.compile(r"[\s().\-/]")
+_DIGITS = re.compile(r"^\+?[0-9]+$")
+
+
+class ParsedPhone(TypedDict):
+    input: str
+    valid: bool
+    e164: Optional[str]
+    national: Optional[str]
+    international: Optional[str]
+    operator: Optional[str]
+    type: Optional[str]
+    reason: Optional[InvalidReason]
+
+
+def _plan() -> Any:
+    return load("phone/numerotation.json")
+
+
+def _group(digits: str) -> str:
+    sizes = _plan().get("nationalGrouping") or [len(digits)]
+    parts, i = [], 0
+    for size in sizes:
+        if i >= len(digits):
+            break
+        parts.append(digits[i : i + size])
+        i += size
+    if i < len(digits):
+        parts.append(digits[i:])
+    return " ".join(parts)
+
+
+def _invalid(value: str, reason: InvalidReason) -> ParsedPhone:
+    return ParsedPhone(input=value, valid=False, e164=None, national=None, international=None,
+                       operator=None, type=None, reason=reason)
+
+
+def parse(value: str) -> ParsedPhone:
+    """Parse any common way of writing a Congo-Brazzaville number. Only raises on non-strings."""
+    if not isinstance(value, str):
+        raise TypeError("phone.parse expects a string")
+
+    plan = _plan()
+    cc, length = plan["countryCode"], plan["nationalNumberLength"]
+
+    compact = _SEPARATORS.sub("", value)
+    if compact == "":
+        return _invalid(value, "empty")
+    if not _DIGITS.match(compact):
+        return _invalid(value, "invalid_characters")
+
+    if compact.startswith("+") or compact.startswith("00"):
+        rest = compact[1:] if compact.startswith("+") else compact[2:]
+        if not rest.startswith(cc):
+            return _invalid(value, "foreign_number")
+        national = rest[len(cc):]
+    elif compact.startswith(cc) and len(compact) == len(cc) + length:
+        national = compact[len(cc):]
+    else:
+        national = compact
+
+    if len(national) != length:
+        return _invalid(value, "length")
+
+    prefix = next((p for p in plan["prefixes"] if national.startswith(p["prefix"])), None)
+    if prefix is None:
+        return _invalid(value, "unknown_prefix")
+
+    grouped = _group(national)
+    return ParsedPhone(input=value, valid=True, e164=f"+{cc}{national}", national=grouped,
+                       international=f"+{cc} {grouped}", operator=prefix.get("operator"),
+                       type=prefix["type"], reason=None)
+
+
+def is_valid(value: str) -> bool:
+    return isinstance(value, str) and parse(value)["valid"]
+
+
+def format(value: str, style: FormatStyle = "national") -> str:  # noqa: A001 - mirrors the JS API
+    """Format a number in the requested style. Raises ValueError if the number is invalid."""
+    parsed = parse(value)
+    if not parsed["valid"]:
+        raise ValueError(f'Invalid +242 number ({parsed["reason"]}): "{value}"')
+    if style == "national":
+        return parsed["national"]  # type: ignore[return-value]
+    if style == "international":
+        return parsed["international"]  # type: ignore[return-value]
+    if style == "e164":
+        return parsed["e164"]  # type: ignore[return-value]
+    raise ValueError(f'Unknown format style "{style}". Use national, international or e164.')

mboka-0.0.1/src/mboka/text.py

@@ -0,0 +1,18 @@
+import re
+import unicodedata
+
+_LIGATURES = str.maketrans({"œ": "oe", "Œ": "OE", "æ": "ae", "Æ": "AE"})
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+
+def normalize(value: str) -> str:
+    """Lowercase, no accents, any run of non-alphanumeric characters becomes one space.
+
+    >>> normalize("Pointe-Noire")
+    'pointe noire'
+    """
+    if not isinstance(value, str):
+        raise TypeError("text.normalize expects a string")
+    decomposed = unicodedata.normalize("NFD", value.translate(_LIGATURES))
+    stripped = "".join(c for c in decomposed if not unicodedata.combining(c))
+    return _NON_ALNUM.sub(" ", stripped.lower()).strip()

mboka-0.0.1/tests/test_fixtures.py

@@ -0,0 +1,55 @@
+"""Runs every active file in /fixtures against the Python package."""
+
+import importlib
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+FIXTURES = Path(__file__).resolve().parents[3] / "fixtures"
+
+
+def snake(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+
+def collect():
+    for path in sorted(FIXTURES.rglob("*.json")):
+        fixture = json.loads(path.read_text(encoding="utf-8"))
+        module_name, fn_name = fixture["function"].split(".")
+        marks = [pytest.mark.skip(reason="pending fixture")] if fixture["status"] == "pending" else []
+        for case in fixture["cases"]:
+            yield pytest.param(module_name, snake(fn_name), case,
+                               id=f'{path.relative_to(FIXTURES)}::{case["name"]}', marks=marks)
+
+
+def assert_partial(actual, expected, path="result"):
+    if isinstance(expected, dict):
+        assert isinstance(actual, dict), f"{path}: expected an object, got {actual!r}"
+        for key, value in expected.items():
+            assert_partial(actual.get(key), value, f"{path}.{key}")
+    else:
+        assert actual == expected, f"{path}: {actual!r} != {expected!r}"
+        assert type(actual) is type(expected) or expected is None, f"{path}: type {type(actual)} != {type(expected)}"
+
+
+@pytest.mark.parametrize("module_name, fn_name, case", list(collect()))
+def test_fixture(module_name, fn_name, case):
+    module = importlib.import_module(f"mboka.{module_name}")
+    fn = getattr(module, fn_name, None)
+    assert callable(fn), f"mboka.{module_name}.{fn_name} is missing"
+
+    def call():
+        if "options" not in case:
+            return fn(case["input"])
+        options = case["options"]
+        if isinstance(options, dict):
+            return fn(case["input"], **{snake(k): v for k, v in options.items()})
+        return fn(case["input"], options)
+
+    if case.get("expectedError"):
+        with pytest.raises(Exception):
+            call()
+    else:
+        assert_partial(call(), case["expected"])

mboka-0.0.1/tests/test_geo.py

@@ -0,0 +1,19 @@
+from mboka import geo
+
+
+def test_lists_are_lists():
+    assert isinstance(geo.departements(), list)
+    assert isinstance(geo.communes(), list)
+    assert isinstance(geo.arrondissements(), list)
+
+
+def test_returned_data_cannot_mutate_shipped_data():
+    first = geo.departements()
+    first.append({"id": "fake"})
+    assert len(geo.departements()) != len(first)
+
+
+def test_unknown_or_empty_names_return_none():
+    assert geo.find("Atlantis") is None
+    assert geo.find("   ") is None
+    assert geo.normalize_name("Atlantis") is None