syscli-algeria 0.1.0__tar.gz

syscli_algeria-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+coverage/
+*.tsbuildinfo
+.DS_Store
+.env
+.env.local
+.npmrc
+
+*.tgz
+src/generated/
+geo/.cache/
+public/
+python/tests/parity.json
+python/dist/
+__pycache__/
+*.egg-info/

syscli_algeria-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0 - 2026-10-10
+
+First release, with the data and search of @syscli/algeria 0.2.0:
+`wilayas`, `wilaya`, `communes`, `commune`, `search`, `changes`, `normalize`.

syscli_algeria-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 syscli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

syscli_algeria-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.5
+Name: syscli-algeria
+Version: 0.1.0
+Summary: Algeria's 69 wilayas and 1541 communes from the Journal officiel, with search in French and Arabic.
+Project-URL: Homepage, https://github.com/syscli/algeria
+Project-URL: Source, https://github.com/syscli/algeria/tree/main/python
+Project-URL: Changelog, https://github.com/syscli/algeria/blob/main/python/CHANGELOG.md
+Author-email: Sysserv <me@sysserv.eu.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: algeria,algerie,commune,dz,geography,wilaya
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Arabic
+Classifier: Natural Language :: French
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# syscli-algeria
+
+The 69 wilayas and 1541 communes of Algeria, taken from the Journal officiel,
+with French and Arabic names, ONS codes, and search that understands the many
+ways a place name gets spelled. The Python twin of the npm package
+[@syscli/algeria](https://github.com/syscli/algeria), with the same data and
+the same search.
+
+```sh
+pip install syscli-algeria
+```
+
+```python
+from syscli_algeria import wilaya, communes, commune, search, changes
+
+wilaya(16).name_fr                 # "Alger"
+len(communes(68))                  # 23
+commune("1601").wilaya_code        # "16"
+
+search("bou saada")[0].wilaya.code       # "68"
+search("Bains Romains")[0].commune.name_fr  # "Hammamet", by its old official name
+search("tamanghaset")[0].commune.name_fr    # "Tamenghasset", despite the typo
+
+len(changes(2026))                 # 108 communes moved to another wilaya in 2026
+```
+
+Up to date with loi 26-06 of 4 April 2026 (58 to 69 wilayas) and decret
+presidentiel 26-206. Every wilaya and commune traces back to a text published
+in the Journal officiel; see https://github.com/syscli/algeria.
+
+No dependencies. Python 3.9 or later.
+
+## License
+
+MIT

syscli_algeria-0.1.0/README.md

@@ -0,0 +1,35 @@
+# syscli-algeria
+
+The 69 wilayas and 1541 communes of Algeria, taken from the Journal officiel,
+with French and Arabic names, ONS codes, and search that understands the many
+ways a place name gets spelled. The Python twin of the npm package
+[@syscli/algeria](https://github.com/syscli/algeria), with the same data and
+the same search.
+
+```sh
+pip install syscli-algeria
+```
+
+```python
+from syscli_algeria import wilaya, communes, commune, search, changes
+
+wilaya(16).name_fr                 # "Alger"
+len(communes(68))                  # 23
+commune("1601").wilaya_code        # "16"
+
+search("bou saada")[0].wilaya.code       # "68"
+search("Bains Romains")[0].commune.name_fr  # "Hammamet", by its old official name
+search("tamanghaset")[0].commune.name_fr    # "Tamenghasset", despite the typo
+
+len(changes(2026))                 # 108 communes moved to another wilaya in 2026
+```
+
+Up to date with loi 26-06 of 4 April 2026 (58 to 69 wilayas) and decret
+presidentiel 26-206. Every wilaya and commune traces back to a text published
+in the Journal officiel; see https://github.com/syscli/algeria.
+
+No dependencies. Python 3.9 or later.
+
+## License
+
+MIT

syscli_algeria-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "syscli-algeria"
+version = "0.1.0"
+description = "Algeria's 69 wilayas and 1541 communes from the Journal officiel, with search in French and Arabic."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sysserv", email = "me@sysserv.eu.org" }]
+requires-python = ">=3.9"
+keywords = ["algeria", "algerie", "wilaya", "commune", "dz", "geography"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Natural Language :: French",
+  "Natural Language :: Arabic",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: GIS",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/syscli/algeria"
+Source = "https://github.com/syscli/algeria/tree/main/python"
+Changelog = "https://github.com/syscli/algeria/blob/main/python/CHANGELOG.md"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/syscli_algeria"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

syscli_algeria-0.1.0/src/syscli_algeria/__init__.py

@@ -0,0 +1,199 @@
+"""Algeria's 69 wilayas and 1541 communes, from the Journal officiel.
+
+The same data and search as the npm package @syscli/algeria.
+
+    >>> from syscli_algeria import wilaya, commune, search
+    >>> wilaya(16).name_fr
+    'Alger'
+    >>> search("bou saada")[0].wilaya.code
+    '68'
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import re
+from dataclasses import dataclass
+from importlib import resources
+from typing import Literal, Optional, Union
+
+from ._normalize import distance, normalize
+
+__all__ = [
+    "Commune",
+    "SearchResult",
+    "Wilaya",
+    "WilayaChange",
+    "changes",
+    "commune",
+    "communes",
+    "normalize",
+    "search",
+    "wilaya",
+    "wilayas",
+]
+
+__version__ = "0.1.0"
+
+
+@dataclass(frozen=True)
+class Wilaya:
+    code: str
+    """Two-digit code, "01" to "69". Also the vehicle plate number."""
+    name_fr: str
+    name_ar: str
+    created_by: str
+    """The law that created the wilaya: "loi 84-09", "loi 19-12" or "loi 26-06"."""
+
+
+@dataclass(frozen=True)
+class Commune:
+    code: str
+    """Four-digit ONS code, e.g. "1601"."""
+    wilaya_code: str
+    name_fr: str
+    name_ar: str
+    daira_1991: Optional[str]
+    """Seat of the daira the commune belonged to in decret 91-306 (1991)."""
+    wilaya_code_58: str
+    """Wilaya under the 58-wilaya map (2019 to 2026)."""
+    wilaya_code_48: str
+    """Wilaya under the 48-wilaya map (1984 to 2019)."""
+    aliases: tuple[str, ...]
+    """Older official names and other common spellings."""
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    commune: Commune
+    wilaya: Wilaya
+    score: float
+    """0 is an exact match; higher is a weaker match."""
+
+
+@dataclass(frozen=True)
+class WilayaChange:
+    commune: Commune
+    from_: str
+    to: str
+
+
+def _rows(name: str) -> list[dict[str, str]]:
+    text = resources.files(__package__).joinpath("data", name).read_text(encoding="utf-8-sig")
+    return list(csv.DictReader(io.StringIO(text)))
+
+
+_WILAYAS: tuple[Wilaya, ...] = tuple(
+    Wilaya(r["code"], r["name_fr"], r["name_ar"], r["created_by"]) for r in _rows("wilayas.csv")
+)
+_COMMUNES: tuple[Commune, ...] = tuple(
+    Commune(
+        code=r["code"],
+        wilaya_code=r["wilaya_code"],
+        name_fr=r["name_fr"],
+        name_ar=r["name_ar"],
+        daira_1991=r["daira_1991"] or None,
+        wilaya_code_58=r["wilaya_code_58"],
+        wilaya_code_48=r["wilaya_code_48"],
+        aliases=tuple(r["aliases"].split("|")) if r["aliases"] else (),
+    )
+    for r in _rows("communes.csv")
+)
+
+_BY_WILAYA = {w.code: w for w in _WILAYAS}
+_BY_COMMUNE = {c.code: c for c in _COMMUNES}
+
+
+def _keys(c: Commune) -> list[str]:
+    seen: dict[str, None] = {}
+    for name in (c.name_fr, c.name_ar, *c.aliases):
+        k = normalize(name)
+        if k:
+            seen[k] = None
+    return list(seen)
+
+
+_INDEX = [(c, _keys(c)) for c in _COMMUNES]
+
+
+_TWO_DIGITS = re.compile("[0-9]{1,2}")
+
+
+def _code(value: Union[str, int], width: int) -> str:
+    return str(value).strip().zfill(width)
+
+
+def wilayas() -> tuple[Wilaya, ...]:
+    """All 69 wilayas, ordered by code."""
+    return _WILAYAS
+
+
+def wilaya(query: Union[str, int]) -> Optional[Wilaya]:
+    """A wilaya by code (5, "05") or by name in French or Arabic."""
+    if isinstance(query, int) or _TWO_DIGITS.fullmatch(query.strip()):
+        return _BY_WILAYA.get(_code(query, 2))
+    q = normalize(query)
+    for w in _WILAYAS:
+        if normalize(w.name_fr) == q or normalize(w.name_ar) == q:
+            return w
+    return None
+
+
+def communes(wilaya_code: Union[str, int, None] = None) -> tuple[Commune, ...]:
+    """All communes, or the communes of one wilaya."""
+    if wilaya_code is None:
+        return _COMMUNES
+    w = _code(wilaya_code, 2)
+    return tuple(c for c in _COMMUNES if c.wilaya_code == w)
+
+
+def commune(ons_code: Union[str, int]) -> Optional[Commune]:
+    """A commune by its four-digit ONS code."""
+    return _BY_COMMUNE.get(_code(ons_code, 4))
+
+
+def search(query: str, limit: int = 10, wilaya: Union[str, int, None] = None) -> list[SearchResult]:
+    """Finds communes by name.
+
+    Accepts French, Arabic, old official names and loose spellings ("setif"
+    finds Setif with or without the accent), and tolerates small typos.
+    """
+    q = normalize(query)
+    if not q:
+        return []
+    only = None if wilaya is None else _code(wilaya, 2)
+    results: list[SearchResult] = []
+    for c, keys in _INDEX:
+        if only and c.wilaya_code != only:
+            continue
+        best = float("inf")
+        for k in keys:
+            if k == q:
+                s: float = 0
+            elif k.startswith(q):
+                s = 1 + (len(k) - len(q)) / 100
+            elif q in k:
+                s = 2 + (len(k) - len(q)) / 100
+            else:
+                d = distance(q, k)
+                s = 3 + d if len(q) >= 4 and d <= max(1, len(q) // 4) else float("inf")
+            if s < best:
+                best = s
+        if best != float("inf"):
+            results.append(SearchResult(c, _BY_WILAYA[c.wilaya_code], best))
+    results.sort(key=lambda r: (r.score, r.commune.code))
+    return results[:limit]
+
+
+def changes(reform: Literal[2019, 2026] = 2026) -> list[WilayaChange]:
+    """Communes whose wilaya changed with a reform.
+
+    2026: 58 to 69 wilayas (loi 26-06). 2019: 48 to 58 wilayas (loi 19-12).
+    """
+    out = []
+    for c in _COMMUNES:
+        before, after = (c.wilaya_code_58, c.wilaya_code) if reform == 2026 else (c.wilaya_code_48, c.wilaya_code_58)
+        if before != after:
+            out.append(WilayaChange(c, before, after))
+    return out

syscli_algeria-0.1.0/src/syscli_algeria/_normalize.py

@@ -0,0 +1,69 @@
+"""Folds the many ways a place name gets written into one comparable key.
+
+A port of src/normalize.ts; tests/test_parity.py checks that both give the
+same keys for every commune name.
+"""
+
+import re
+import unicodedata
+
+_LATIN = [
+    (re.compile(r"\b(el|al|les?|la)\b"), " "),
+    (re.compile(r"\bbeni\b|\bbni\b"), "bn"),
+    (re.compile(r"\bain\b"), "an"),
+    (re.compile(r"dj"), "j"),
+    (re.compile(r"ou"), "u"),
+    (re.compile(r"ch|sh"), "c"),
+    (re.compile(r"kh"), "k"),
+    (re.compile(r"gh"), "g"),
+    (re.compile(r"th"), "t"),
+    (re.compile(r"dh"), "d"),
+    (re.compile(r"q"), "k"),
+    (re.compile(r"y"), "i"),
+    (re.compile(r"e"), "a"),
+    (re.compile(r"([a-z])\1+"), r"\1"),
+]
+
+_ARABIC = [
+    (re.compile("[\u064b-\u065f\u0670\u0640]"), ""),
+    (re.compile("[\u0622\u0623\u0625\u0671]"), "\u0627"),
+    (re.compile("\u0649"), "\u064a"),
+    (re.compile("\u0629"), "\u0647"),
+    (re.compile("\u0624"), "\u0648"),
+    (re.compile("\u0626"), "\u064a"),
+    (re.compile("(^|\\s)\u0627\u0644"), "\\1"),
+]
+
+_HAS_ARABIC = re.compile("[\u0600-\u06ff]")
+_NOT_ARABIC = re.compile("[^\u0600-\u06ff]")
+_MARKS = re.compile("[\u0300-\u036f]")
+_NOT_LATIN = re.compile("[^a-z]+")
+_SPACES = re.compile(r"\s+")
+
+
+def normalize(text: str) -> str:
+    """Returns the comparison key of a place name, in French or Arabic."""
+    s = unicodedata.normalize("NFKD", text).lower()
+    if _HAS_ARABIC.search(s):
+        for pattern, repl in _ARABIC:
+            s = pattern.sub(repl, s)
+        return _NOT_ARABIC.sub("", s)
+    s = _NOT_LATIN.sub(" ", _MARKS.sub("", s)).strip()
+    for pattern, repl in _LATIN:
+        s = pattern.sub(repl, s)
+    return _SPACES.sub("", s)
+
+
+def distance(a: str, b: str) -> int:
+    """Levenshtein distance, or 99 when the lengths differ by more than 3."""
+    if abs(len(a) - len(b)) > 3:
+        return 99
+    row = list(range(len(b) + 1))
+    for i in range(1, len(a) + 1):
+        prev = row[0]
+        row[0] = i
+        for j in range(1, len(b) + 1):
+            tmp = row[j]
+            row[j] = min(row[j] + 1, row[j - 1] + 1, prev + (0 if a[i - 1] == b[j - 1] else 1))
+            prev = tmp
+    return row[len(b)]