rwanda-geo-data 1.0.1__tar.gz

rwanda_geo_data-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LinkFy Connect
+
+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.

rwanda_geo_data-1.0.1/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: rwanda-geo-data
+Version: 1.0.1
+Summary: Rwanda administrative divisions: provinces, districts, sectors, cells and villages.
+Author: LinkFy Connect
+License: MIT
+Project-URL: Homepage, https://github.com/megacodesdev/Rwanda-Geo-Data
+Project-URL: Repository, https://github.com/megacodesdev/Rwanda-Geo-Data
+Project-URL: Issues, https://github.com/megacodesdev/Rwanda-Geo-Data/issues
+Keywords: rwanda,geo,provinces,districts,sectors,cells,villages
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Rwanda Geo Data
+
+Rwanda's administrative divisions for JavaScript/TypeScript and Python:
+**5 provinces → 30 districts → 416 sectors → 2,149 cells → 14,837 villages**.
+
+Zero dependencies. Lookups are case-insensitive. District names are unique, so you only pass the district (no province) when looking up sectors, cells and villages.
+
+## JavaScript / TypeScript
+
+```bash
+npm install @linkfy-connect/rwanda-geo-data
+```
+
+Works in Node, and in any bundler-based framework (React, Next.js, Vue, Nuxt, Angular, Svelte/SvelteKit, Astro, Remix, React Native, Vite, webpack) via ESM, CommonJS and bundled TypeScript types.
+
+```js
+import { getProvinces, getDistricts, getSectors, getCells, getVillages, search } from '@linkfy-connect/rwanda-geo-data';
+
+getProvinces();                                  // ['East', 'Kigali', 'North', 'South', 'West']
+getDistricts('East');                            // ['Bugesera', 'Gatsibo', ...]
+getSectors('Bugesera');                          // ['Gashora', 'Juru', ...]
+getCells('Bugesera', 'Gashora');                 // ['Biryogo', 'Kabuye', ...]
+getVillages('Bugesera', 'Gashora', 'Biryogo');   // ['Bidudu', 'Biryogo', ...]
+```
+
+### React: cascading dropdowns
+
+```jsx
+import { useState } from 'react';
+import { getProvinces, getDistricts, getSectors, getCells, getVillages } from '@linkfy-connect/rwanda-geo-data';
+
+const LEVELS = ['province', 'district', 'sector', 'cell', 'village'];
+
+export default function AddressPicker() {
+  const [a, setA] = useState({});
+
+  // Changing a level clears every level below it.
+  const choose = (level, value) => {
+    const keep = LEVELS.slice(0, LEVELS.indexOf(level));
+    setA({ ...Object.fromEntries(keep.map((k) => [k, a[k]])), [level]: value });
+  };
+
+  const options = {
+    province: getProvinces(),
+    district: a.province ? getDistricts(a.province) : [],
+    sector: a.district ? getSectors(a.district) : [],
+    cell: a.sector ? getCells(a.district, a.sector) : [],
+    village: a.cell ? getVillages(a.district, a.sector, a.cell) : [],
+  };
+
+  return LEVELS.map((level) => (
+    <select key={level} value={a[level] || ''} disabled={!options[level].length}
+            onChange={(e) => choose(level, e.target.value)}>
+      <option value="">Select {level}</option>
+      {options[level].map((o) => <option key={o}>{o}</option>)}
+    </select>
+  ));
+}
+```
+
+### Vue 3
+
+```vue
+<script setup>
+import { ref, computed } from 'vue';
+import { getProvinces, getDistricts } from '@linkfy-connect/rwanda-geo-data';
+const province = ref('');
+const districts = computed(() => getDistricts(province.value));
+</script>
+<template>
+  <select v-model="province"><option v-for="p in getProvinces()" :key="p">{{ p }}</option></select>
+  <select><option v-for="d in districts" :key="d">{{ d }}</option></select>
+</template>
+```
+
+### Angular, Svelte, Next.js, Nuxt
+
+Same import everywhere: `import { getDistricts } from '@linkfy-connect/rwanda-geo-data'`. In Next.js/Nuxt it also works in server code (API routes, server components).
+
+The whole dataset is about 190 kB in the bundle (roughly 40 kB gzipped). To keep it out of the initial bundle, load it lazily:
+
+```js
+const geo = await import('@linkfy-connect/rwanda-geo-data');
+```
+
+### API
+
+| Function | Returns |
+|---|---|
+| `getProvinces()` | `string[]` |
+| `getDistricts(province?)` | districts of a province, or all 30 |
+| `getProvinceOf(district)` | province name or `undefined` |
+| `getSectors(district)` | `string[]` |
+| `getCells(district, sector)` | `string[]` |
+| `getVillages(district, sector, cell)` | `string[]` |
+| `isValidAddress({province, district, sector?, cell?, village?})` | `boolean` |
+| `search(query, {levels?, limit?})` | `[{level, name, province, district?, ...}]` |
+| `getStats()` | counts per level |
+| `data` | the raw nested object |
+
+## Python
+
+```bash
+pip install rwanda-geo-data
+```
+
+Python 3.8+, standard library only.
+
+```python
+import rwanda_geo_data as geo
+
+geo.get_provinces()                                  # ['East', 'Kigali', 'North', 'South', 'West']
+geo.get_districts("East")                            # ['Bugesera', 'Gatsibo', ...]
+geo.get_sectors("Bugesera")                          # ['Gashora', 'Juru', ...]
+geo.get_cells("Bugesera", "Gashora")                 # ['Biryogo', 'Kabuye', ...]
+geo.get_villages("Bugesera", "Gashora", "Biryogo")   # ['Bidudu', 'Biryogo', ...]
+geo.is_valid_address("East", "Bugesera", "Gashora")  # True
+geo.search("gashora", levels=["sector"])
+geo.DATA                                             # raw nested dict
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+import rwanda_geo_data as geo
+
+app = FastAPI()
+
+@app.get("/districts/{province}")
+def districts(province: str):
+    return geo.get_districts(province)
+
+@app.get("/sectors/{district}")
+def sectors(district: str):
+    return geo.get_sectors(district)
+```
+
+### Django / Flask
+
+Call the same functions inside any view, serializer or form validator, for example `geo.is_valid_address(...)` in a form's `clean()`.
+
+## Development
+
+```bash
+npm test            # builds dist/, syncs data to python/, runs JS tests
+cd python && python -m unittest discover -s tests
+```
+
+`data/rwanda-geo-data.json` is the single source of truth. Edit it, then run `npm run build`: this regenerates `dist/` and copies the data into the Python package.
+
+## Publishing
+
+```bash
+# npm
+npm login
+npm publish            # use `npm publish --access public` for a scoped name
+
+# PyPI
+cd python
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Bump the version in both `package.json` and `python/pyproject.toml` for each release.
+
+## License
+
+MIT

rwanda_geo_data-1.0.1/README.md

@@ -0,0 +1,170 @@
+# Rwanda Geo Data
+
+Rwanda's administrative divisions for JavaScript/TypeScript and Python:
+**5 provinces → 30 districts → 416 sectors → 2,149 cells → 14,837 villages**.
+
+Zero dependencies. Lookups are case-insensitive. District names are unique, so you only pass the district (no province) when looking up sectors, cells and villages.
+
+## JavaScript / TypeScript
+
+```bash
+npm install @linkfy-connect/rwanda-geo-data
+```
+
+Works in Node, and in any bundler-based framework (React, Next.js, Vue, Nuxt, Angular, Svelte/SvelteKit, Astro, Remix, React Native, Vite, webpack) via ESM, CommonJS and bundled TypeScript types.
+
+```js
+import { getProvinces, getDistricts, getSectors, getCells, getVillages, search } from '@linkfy-connect/rwanda-geo-data';
+
+getProvinces();                                  // ['East', 'Kigali', 'North', 'South', 'West']
+getDistricts('East');                            // ['Bugesera', 'Gatsibo', ...]
+getSectors('Bugesera');                          // ['Gashora', 'Juru', ...]
+getCells('Bugesera', 'Gashora');                 // ['Biryogo', 'Kabuye', ...]
+getVillages('Bugesera', 'Gashora', 'Biryogo');   // ['Bidudu', 'Biryogo', ...]
+```
+
+### React: cascading dropdowns
+
+```jsx
+import { useState } from 'react';
+import { getProvinces, getDistricts, getSectors, getCells, getVillages } from '@linkfy-connect/rwanda-geo-data';
+
+const LEVELS = ['province', 'district', 'sector', 'cell', 'village'];
+
+export default function AddressPicker() {
+  const [a, setA] = useState({});
+
+  // Changing a level clears every level below it.
+  const choose = (level, value) => {
+    const keep = LEVELS.slice(0, LEVELS.indexOf(level));
+    setA({ ...Object.fromEntries(keep.map((k) => [k, a[k]])), [level]: value });
+  };
+
+  const options = {
+    province: getProvinces(),
+    district: a.province ? getDistricts(a.province) : [],
+    sector: a.district ? getSectors(a.district) : [],
+    cell: a.sector ? getCells(a.district, a.sector) : [],
+    village: a.cell ? getVillages(a.district, a.sector, a.cell) : [],
+  };
+
+  return LEVELS.map((level) => (
+    <select key={level} value={a[level] || ''} disabled={!options[level].length}
+            onChange={(e) => choose(level, e.target.value)}>
+      <option value="">Select {level}</option>
+      {options[level].map((o) => <option key={o}>{o}</option>)}
+    </select>
+  ));
+}
+```
+
+### Vue 3
+
+```vue
+<script setup>
+import { ref, computed } from 'vue';
+import { getProvinces, getDistricts } from '@linkfy-connect/rwanda-geo-data';
+const province = ref('');
+const districts = computed(() => getDistricts(province.value));
+</script>
+<template>
+  <select v-model="province"><option v-for="p in getProvinces()" :key="p">{{ p }}</option></select>
+  <select><option v-for="d in districts" :key="d">{{ d }}</option></select>
+</template>
+```
+
+### Angular, Svelte, Next.js, Nuxt
+
+Same import everywhere: `import { getDistricts } from '@linkfy-connect/rwanda-geo-data'`. In Next.js/Nuxt it also works in server code (API routes, server components).
+
+The whole dataset is about 190 kB in the bundle (roughly 40 kB gzipped). To keep it out of the initial bundle, load it lazily:
+
+```js
+const geo = await import('@linkfy-connect/rwanda-geo-data');
+```
+
+### API
+
+| Function | Returns |
+|---|---|
+| `getProvinces()` | `string[]` |
+| `getDistricts(province?)` | districts of a province, or all 30 |
+| `getProvinceOf(district)` | province name or `undefined` |
+| `getSectors(district)` | `string[]` |
+| `getCells(district, sector)` | `string[]` |
+| `getVillages(district, sector, cell)` | `string[]` |
+| `isValidAddress({province, district, sector?, cell?, village?})` | `boolean` |
+| `search(query, {levels?, limit?})` | `[{level, name, province, district?, ...}]` |
+| `getStats()` | counts per level |
+| `data` | the raw nested object |
+
+## Python
+
+```bash
+pip install rwanda-geo-data
+```
+
+Python 3.8+, standard library only.
+
+```python
+import rwanda_geo_data as geo
+
+geo.get_provinces()                                  # ['East', 'Kigali', 'North', 'South', 'West']
+geo.get_districts("East")                            # ['Bugesera', 'Gatsibo', ...]
+geo.get_sectors("Bugesera")                          # ['Gashora', 'Juru', ...]
+geo.get_cells("Bugesera", "Gashora")                 # ['Biryogo', 'Kabuye', ...]
+geo.get_villages("Bugesera", "Gashora", "Biryogo")   # ['Bidudu', 'Biryogo', ...]
+geo.is_valid_address("East", "Bugesera", "Gashora")  # True
+geo.search("gashora", levels=["sector"])
+geo.DATA                                             # raw nested dict
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+import rwanda_geo_data as geo
+
+app = FastAPI()
+
+@app.get("/districts/{province}")
+def districts(province: str):
+    return geo.get_districts(province)
+
+@app.get("/sectors/{district}")
+def sectors(district: str):
+    return geo.get_sectors(district)
+```
+
+### Django / Flask
+
+Call the same functions inside any view, serializer or form validator, for example `geo.is_valid_address(...)` in a form's `clean()`.
+
+## Development
+
+```bash
+npm test            # builds dist/, syncs data to python/, runs JS tests
+cd python && python -m unittest discover -s tests
+```
+
+`data/rwanda-geo-data.json` is the single source of truth. Edit it, then run `npm run build`: this regenerates `dist/` and copies the data into the Python package.
+
+## Publishing
+
+```bash
+# npm
+npm login
+npm publish            # use `npm publish --access public` for a scoped name
+
+# PyPI
+cd python
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Bump the version in both `package.json` and `python/pyproject.toml` for each release.
+
+## License
+
+MIT

rwanda_geo_data-1.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rwanda-geo-data"
+version = "1.0.1"
+description = "Rwanda administrative divisions: provinces, districts, sectors, cells and villages."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "LinkFy Connect" }]
+keywords = ["rwanda", "geo", "provinces", "districts", "sectors", "cells", "villages"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/megacodesdev/Rwanda-Geo-Data"
+Repository = "https://github.com/megacodesdev/Rwanda-Geo-Data"
+Issues = "https://github.com/megacodesdev/Rwanda-Geo-Data/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+rwanda_geo_data = ["data.json", "py.typed"]

rwanda_geo_data-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rwanda_geo_data-1.0.1/src/rwanda_geo_data/__init__.py

@@ -0,0 +1,165 @@
+"""Rwanda administrative divisions: province > district > sector > cell > villages.
+
+All lookups are case-insensitive. District names are unique nationwide, so
+lookups below province only need the district.
+"""
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+__all__ = [
+    "DATA", "get_provinces", "get_districts", "get_province_of", "get_sectors",
+    "get_cells", "get_villages", "is_valid_address", "search", "get_stats",
+]
+
+with open(Path(__file__).with_name("data.json"), encoding="utf-8") as _f:
+    DATA: Dict[str, Dict[str, Dict[str, Dict[str, List[str]]]]] = json.load(_f)
+
+
+def _norm(s: Any) -> str:
+    return "" if s is None else str(s).strip().lower()
+
+
+def _find_key(obj: Optional[Dict[str, Any]], name: Any) -> Optional[str]:
+    if not obj:
+        return None
+    n = _norm(name)
+    for k in obj:
+        if _norm(k) == n:
+            return k
+    return None
+
+
+_DISTRICT_INDEX: Dict[str, str] = {
+    _norm(d): p for p, ds in DATA.items() for d in ds
+}
+
+
+def get_provinces() -> List[str]:
+    return list(DATA)
+
+
+def get_districts(province: Optional[str] = None) -> List[str]:
+    if province is None:
+        return [d for ds in DATA.values() for d in ds]
+    p = _find_key(DATA, province)
+    return list(DATA[p]) if p else []
+
+
+def get_province_of(district: str) -> Optional[str]:
+    return _DISTRICT_INDEX.get(_norm(district))
+
+
+def get_sectors(district: str) -> List[str]:
+    p = get_province_of(district)
+    if not p:
+        return []
+    d = _find_key(DATA[p], district)
+    return list(DATA[p][d])
+
+
+def get_cells(district: str, sector: str) -> List[str]:
+    p = get_province_of(district)
+    if not p:
+        return []
+    d = _find_key(DATA[p], district)
+    s = _find_key(DATA[p][d], sector)
+    return list(DATA[p][d][s]) if s else []
+
+
+def get_villages(district: str, sector: str, cell: str) -> List[str]:
+    p = get_province_of(district)
+    if not p:
+        return []
+    d = _find_key(DATA[p], district)
+    s = _find_key(DATA[p][d], sector)
+    if not s:
+        return []
+    c = _find_key(DATA[p][d][s], cell)
+    return list(DATA[p][d][s][c]) if c else []
+
+
+def is_valid_address(
+    province: str,
+    district: str,
+    sector: Optional[str] = None,
+    cell: Optional[str] = None,
+    village: Optional[str] = None,
+) -> bool:
+    p = _find_key(DATA, province)
+    if not p:
+        return False
+    d = _find_key(DATA[p], district)
+    if not d:
+        return False
+    if sector is None:
+        return True
+    s = _find_key(DATA[p][d], sector)
+    if not s:
+        return False
+    if cell is None:
+        return True
+    c = _find_key(DATA[p][d][s], cell)
+    if not c:
+        return False
+    if village is None:
+        return True
+    return any(_norm(v) == _norm(village) for v in DATA[p][d][s][c])
+
+
+def search(
+    query: str,
+    levels: Optional[List[str]] = None,
+    limit: int = 50,
+) -> List[Dict[str, str]]:
+    """Case-insensitive substring search. Levels: province, district, sector, cell, village."""
+    q = _norm(query)
+    if not q:
+        return []
+    want = set(levels or ["province", "district", "sector", "cell", "village"])
+    out: List[Dict[str, str]] = []
+
+    def push(r: Dict[str, str]) -> bool:
+        out.append(r)
+        return len(out) >= limit
+
+    for province, districts in DATA.items():
+        if "province" in want and q in _norm(province):
+            if push({"level": "province", "name": province, "province": province}):
+                return out
+        for district, sectors in districts.items():
+            if "district" in want and q in _norm(district):
+                if push({"level": "district", "name": district, "province": province, "district": district}):
+                    return out
+            for sector, cells in sectors.items():
+                if "sector" in want and q in _norm(sector):
+                    if push({"level": "sector", "name": sector, "province": province,
+                             "district": district, "sector": sector}):
+                        return out
+                for cell, villages in cells.items():
+                    if "cell" in want and q in _norm(cell):
+                        if push({"level": "cell", "name": cell, "province": province,
+                                 "district": district, "sector": sector, "cell": cell}):
+                            return out
+                    if "village" in want:
+                        for village in villages:
+                            if q in _norm(village):
+                                if push({"level": "village", "name": village, "province": province,
+                                         "district": district, "sector": sector,
+                                         "cell": cell, "village": village}):
+                                    return out
+    return out
+
+
+def get_stats() -> Dict[str, int]:
+    districts = sectors = cells = villages = 0
+    for ds in DATA.values():
+        for ss in ds.values():
+            districts += 1
+            for cs in ss.values():
+                sectors += 1
+                for vs in cs.values():
+                    cells += 1
+                    villages += len(vs)
+    return {"provinces": len(DATA), "districts": districts, "sectors": sectors,
+            "cells": cells, "villages": villages}