afrogeo 0.1.0__py3-none-any.whl

afrogeo/__init__.py

@@ -0,0 +1,20 @@
+"""
+Afrogeo: Offline-first African location verification for Python.
+
+This package provides tools to validate and normalize location data
+(Country, State, LGA, City) across Africa using local JSON datasets.
+It is designed to work without an internet connection.
+
+Main function:
+    verify: Validates location data and returns a Result object.
+
+Usage:
+    >>> from afrogeo import verify
+    >>> result = verify({"country": "Nigeria", "state": "Lagos", "lga": "Agege"})
+    >>> if result:
+    ...     print("Location is valid!")
+"""
+
+from .verify import verify
+
+__all__ = ["verify"]

afrogeo/result.py

@@ -0,0 +1,33 @@
+class Result:
+    """
+    Represents the outcome of a location verification.
+
+    This object is returned by the `verify()` function and contains
+    information about whether the validation succeeded, any errors
+    encountered, and the normalized location data.
+
+    Attributes:
+        valid (bool): True if the location was successfully verified.
+        errors (list[str]): A list of error messages if validation failed.
+        normalized (dict): A dictionary containing standardized location names
+            (country, state, lga, city) and codes if successful.
+    """
+    def __init__(self, valid: bool, errors=None, normalized=None):
+        """
+        Initialize a Result object.
+
+        Args:
+            valid: Boolean indicating success.
+            errors: Optional list of error strings.
+            normalized: Optional dictionary of normalized data.
+        """
+        self.valid = valid
+        self.errors = errors or []
+        self.normalized = normalized or {}
+
+    def __bool__(self):
+        """Allows using the result directly in an 'if' statement."""
+        return self.valid
+
+    def __repr__(self):
+        return f"<AfrogeoResult valid={self.valid} errors={self.errors}>"

afrogeo/verify.py

@@ -0,0 +1,152 @@
+import json
+import functools
+from pathlib import Path
+from afrogeo.result import Result
+
+# Constants
+BASE_DIR = Path(__file__).parent
+DATA_DIR = BASE_DIR / "data"
+
+@functools.lru_cache(maxsize=10)
+def load_country_data(country_code: str):
+    """
+    Load country data from a JSON file in the data directory.
+
+    Args:
+        country_code: The ISO country code (e.g., 'ng').
+
+    Returns:
+        A dictionary containing the country data, or None if not found.
+    """
+    file_path = DATA_DIR / f"{country_code.lower()}.json"
+    if not file_path.exists():
+        return None
+    
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return None
+
+def verify(user_input: dict):
+    """
+    Verify African location data against local datasets.
+
+    This function validates if a given state, LGA, and optional city exist
+    within the specified country. It handles case-insensitivity and 
+    normalizes the output.
+
+    Args:
+        user_input (dict): A dictionary containing:
+            - 'country' (str): Full name or ISO code (e.g., 'Nigeria' or 'NG').
+            - 'state' (str): Full name or code (e.g., 'Lagos' or 'LA').
+            - 'lga' (str): Local Government Area name.
+            - 'city' (str, optional): City name for validation.
+
+    Returns:
+        afrogeo.result.Result: An object containing validation status,
+            errors (if any), and normalized data.
+
+    Example:
+        >>> from afrogeo import verify
+        >>> res = verify({"country": "NG", "state": "LA", "lga": "Agege"})
+        >>> if res:
+        ...     print(res.normalized['state'])
+        Lagos
+    """
+    country_input = str(user_input.get("country", "")).strip().lower()
+    state_input = str(user_input.get("state", "")).strip().lower()
+    lga_input = str(user_input.get("lga", "")).strip().lower()
+    city_input = str(user_input.get("city", "")).strip().lower() or None
+
+    if not country_input:
+        return Result(False, ["country is required"])
+    if not state_input or not lga_input:
+        return Result(False, ["state and lga are required"])
+
+    # -------------------------
+    # DATA LOADING (Dynamic)
+    # -------------------------
+    # Map country names to codes if necessary (Basic mapping for now)
+    country_map = {"nigeria": "ng", "ghana": "gh", "kenya": "ke"}
+    country_code = country_map.get(country_input, country_input)
+    
+    data = load_country_data(country_code)
+    if not data:
+        return Result(False, [f"Data for country '{country_input}' not found or unsupported"])
+
+    # -------------------------
+    # COUNTRY MATCH
+    # -------------------------
+    found_country_key = None
+    for key in data.keys():
+        if key.lower() == country_code:
+            found_country_key = key
+            break
+    
+    if not found_country_key:
+        return Result(False, [f"Invalid country code in data for '{country_input}'"])
+
+    country_data = data[found_country_key]
+    states = country_data.get("states", {})
+
+    # -------------------------
+    # STATE MATCH (code OR name)
+    # -------------------------
+    found_state_code = None
+    found_state_data = None
+
+    for code, state in states.items():
+        if (
+            code.lower() == state_input
+            or state["name"].lower() == state_input
+        ):
+            found_state_code = code
+            found_state_data = state
+            break
+
+    if not found_state_code:
+        return Result(False, ["Invalid state"])
+
+    # -------------------------
+    # LGA MATCH
+    # -------------------------
+    lgas = found_state_data.get("lgas", {})
+
+    found_lga_name = None
+    found_lga_info = None
+
+    for lga_name, lga_info in lgas.items():
+        if lga_name.lower() == lga_input:
+            found_lga_name = lga_name
+            found_lga_info = lga_info
+            break
+
+    if not found_lga_name:
+        return Result(False, ["Invalid LGA for selected state"])
+
+    # -------------------------
+    # OPTIONAL CITY CHECK
+    # -------------------------
+    found_city_name = found_lga_info.get("city")
+    if city_input:
+        if not found_city_name:
+            return Result(False, ["LGA does not belong to a city"])
+
+        if found_city_name.lower() != city_input:
+            return Result(False, ["City does not match LGA"])
+
+    # -------------------------
+    # SUCCESS
+    # -------------------------
+    normalized = {
+        "country_code": found_country_key,
+        "country": country_data["name"],
+        "state_code": found_state_code,
+        "state": found_state_data["name"],
+        "capital": found_state_data.get("capital"),
+        "lga": found_lga_name,
+        "city": found_city_name,
+    }
+
+    return Result(True, [], normalized)

afrogeo-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: afrogeo
+Version: 0.1.0
+Summary: Offline-first African location verification for Python.
+Author: 404Codes
+License: MIT License
+        
+        Copyright (c) 2026 404 Codes
+        
+        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.
+        
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# Afrogeo
+
+Offline-first African location verification for Python.
+
+Validate country, state, city, and district (LGA) without an internet connection.
+
+## Installation
+
+```bash
+pip install afrogeo
+```
+
+## Usage
+
+Afrogeo provides a simple `verify` function that takes a dictionary and returns a `Result` object.
+
+### Basic Example
+
+```python
+from afrogeo import verify
+
+data = {
+    "country": "Nigeria",
+    "state": "Lagos",
+    "lga": "Agege"
+}
+
+result = verify(data)
+
+if result.valid:
+    print(f"Validated: {result.normalized['state']} - {result.normalized['lga']}")
+else:
+    print(f"Errors: {result.errors}")
+```
+
+### Full Validation (including City)
+
+```python
+data = {
+    "country": "NG",        # Supports codes or full names
+    "state": "LA",          # Supports state codes
+    "lga": "Agege",
+    "city": "Agege"         # Optional
+}
+
+result = verify(data)
+```
+
+## Features
+
+- **Offline-First**: Uses local JSON data for instant verification.
+- **Data Normalization**: Automatically converts codes to full names and vice-versa.
+- **Case Insensitive**: Accepts "LAGOS", "lagos", or "Lagos".
+- **Dynamic Loading**: Loads only the data for the country you are verifying.
+
+## API Reference
+
+### `verify(user_input: dict) -> Result`
+
+The `user_input` dictionary accepts:
+- `country` (Required): Full name or ISO code.
+- `state` (Required): Full name or code.
+- `lga` (Required): Local Government Area name.
+- `city` (Optional): City name.
+
+Returns a `Result` object with:
+- `valid`: Boolean.
+- `errors`: List of strings (empty if valid).
+- `normalized`: Dictionary of standard location names and codes.
+
+## Contributing
+
+Data is stored in `afrogeo/data/`. To add a new country, create a `<country_code>.json` file following the existing structure.

afrogeo-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+afrogeo/__init__.py,sha256=fGY3zLOCrx7kJvgBSoXMSAuGXeuSMDqycEvGLTgO65Y,581
+afrogeo/result.py,sha256=YYH_j1C3aH2hmcbIuAlQTM3ZWUIY8bigla-vLnCq5Ho,1207
+afrogeo/verify.py,sha256=dU-Ns7mwpFGyxUr3lkRj7iAoOycomGFiI58ir36e9Gs,4790
+afrogeo/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+afrogeo-0.1.0.dist-info/licenses/LICENSE,sha256=20RPtG0rhQ1nPS_d7o7HSu44_iWiyqrDZw6CEHTiHy0,1066
+afrogeo-0.1.0.dist-info/METADATA,sha256=jhqcr_-PiL5TAaxcAA8-jnB1opkF8v1Qol2BjXQITCY,3341
+afrogeo-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+afrogeo-0.1.0.dist-info/top_level.txt,sha256=Q6vlL7NjHvWikpOzYd4kmUVxrHge6PeKzxiybN3xL4U,8
+afrogeo-0.1.0.dist-info/RECORD,,

afrogeo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

afrogeo-0.1.0.dist-info/licenses/LICENSE

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

afrogeo-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+afrogeo