chore: update python support range to 3.10-3.14

Author: jayeshmepani

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4

.github/workflows/quality.yml

@@ -0,0 +1,40 @@
+name: Quality Checks
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  quality:
+    name: Lint, Type Check and Test
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+          
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          
+      - name: Ruff Check (Lint)
+        run: ruff check postalkit/ tests/
+        
+      - name: Ruff Format (Style)
+        run: ruff format --check postalkit/ tests/
+        
+      - name: Pyright (Type Check)
+        run: |
+          pip install pyright
+          pyright postalkit/
+          
+      - name: Pytest (Unit Tests)
+        run: pytest tests/

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff          # Lint
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format   # Format
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: npx pyright
+        language: node
+        types: [python]
+        pass_filenames: false
+        additional_dependencies: ['pyright']

postalkit/core/__init__.py

@@ -1,4 +1,4 @@
+from ..exceptions import DependencyMissingError, InitializationError, PostalKitError
 from .ffi import initialize
-from ..exceptions import PostalKitError, InitializationError, DependencyMissingError
 
-__all__ = ["initialize", "PostalKitError", "InitializationError", "DependencyMissingError"]
+__all__ = ["DependencyMissingError", "InitializationError", "PostalKitError", "initialize"]

postalkit/core/ffi.py

@@ -1,25 +1,26 @@
 import hashlib
 from pathlib import Path
 
+
 def verify_checksum(file_path: Path, expected_hash: str) -> bool:
     """
     Verifies the SHA256 checksum of a file against an expected hash.
-    
+
     Args:
         file_path (Path): Path to the file.
         expected_hash (str): The expected SHA256 hash.
-        
+
     Returns:
         bool: True if the checksum matches, False otherwise.
     """
     if not file_path.exists():
         return False
-        
+
     sha256_hash = hashlib.sha256()
-    
+
     with open(file_path, "rb") as f:
         # Read and update hash in chunks to prevent memory overload for large files
         for byte_block in iter(lambda: f.read(4096), b""):
             sha256_hash.update(byte_block)
-            
+
     return sha256_hash.hexdigest() == expected_hash

postalkit/data/checksum.py

@@ -1,81 +1,97 @@
 import os
 from pathlib import Path
-from ..runtime.paths import get_binary_dir, get_model_dir
-from ..runtime.platform import get_platform_identifier, get_library_name
-from ..runtime.downloader import download_file
+
 from ..exceptions import DependencyMissingError
+from ..runtime.downloader import download_file
+from ..runtime.paths import get_binary_dir, get_model_dir
+from ..runtime.platform import get_library_name, get_platform_identifier
 from .checksum import verify_checksum
 
 POSTALKIT_VERSION = "v1.0.5"
-BINARIES_BASE_URL = os.environ.get("POSTALKIT_BINARIES_URL", f"https://github.com/jayeshmepani/libpostal-ffi-python/releases/download/{POSTALKIT_VERSION}")
-MODEL_DATA_URL = os.environ.get("POSTALKIT_MODEL_URL", "https://s3.amazonaws.com/libpostal/data/libpostal_data.tar.gz")
+BINARIES_BASE_URL = os.environ.get(
+    "POSTALKIT_BINARIES_URL",
+    f"https://github.com/jayeshmepani/libpostal-ffi-python/releases/download/{POSTALKIT_VERSION}",
+)
+MODEL_DATA_URL = os.environ.get(
+    "POSTALKIT_MODEL_URL", "https://s3.amazonaws.com/libpostal/data/libpostal_data.tar.gz"
+)
+
 
 def _download_and_verify(url: str, tar_path: Path, desc: str):
     """Downloads a file and its .sha256 checksum file, then verifies and extracts."""
     # 1. Download the archive
     download_file(url, tar_path, extract=False, desc=desc)
-    
+
     # 2. Download the checksum
     checksum_url = f"{url}.sha256"
     checksum_path = tar_path.with_suffix(".tar.gz.sha256")
     try:
         download_file(checksum_url, checksum_path, extract=False, desc=f"{desc} Checksum")
-        with open(checksum_path, "r") as f:
+        with open(checksum_path) as f:
             # typical format: "hash  filename"
             expected_hash = f.read().strip().split()[0]
-            
+
         if not verify_checksum(tar_path, expected_hash):
             os.remove(tar_path)
-            raise DependencyMissingError(f"Checksum verification failed for {tar_path.name}")
+            raise DependencyMissingError from None(
+                f"Checksum verification failed for {tar_path.name}"
+            )
     except Exception as e:
         # If the checksum file doesn't exist remotely or fails to download,
         # we strictly fail to prevent compromised or corrupt binaries in production.
         if tar_path.exists():
             os.remove(tar_path)
         if checksum_path.exists():
             os.remove(checksum_path)
-        raise DependencyMissingError(f"Failed to fetch or verify checksum for {tar_path.name}: {e}")
+        raise DependencyMissingError from None(
+            f"Failed to fetch or verify checksum for {tar_path.name}: {e}"
+        )
 
     # 3. Extract after verification
     from ..runtime.downloader import _extract_tar_gz
+
     _extract_tar_gz(tar_path, tar_path.parent)
 
+
 def ensure_models() -> Path:
     """Ensures libpostal data models are downloaded and returns their path."""
     model_dir = get_model_dir()
     marker_file = model_dir / "data_version"
-    
+
     if not marker_file.exists():
         tar_path = model_dir / "libpostal_data.tar.gz"
         print("PostalKit models not found. Downloading (~2GB)...")
         _download_and_verify(MODEL_DATA_URL, tar_path, "Model Data")
         marker_file.write_text("1")
-             
+
     return model_dir
 
+
 def ensure_binary() -> Path:
     """Ensures the correct shared library for the platform is downloaded."""
     from ..runtime.paths import get_bundled_binary_dir
+
     bin_dir = get_binary_dir()
     lib_name = get_library_name()
     platform_id = get_platform_identifier()
-    
+
     # 1. Check bundled library
     bundled_lib_path = get_bundled_binary_dir() / lib_name
     if bundled_lib_path.exists():
         return bundled_lib_path
-        
+
     # 2. Check auto-downloaded library
     lib_path = bin_dir / lib_name
-    
+
     if not lib_path.exists():
         download_url = f"{BINARIES_BASE_URL}/libpostal-{platform_id}.tar.gz"
         tar_path = bin_dir / f"libpostal-{platform_id}.tar.gz"
         print(f"PostalKit binary not found. Downloading for {platform_id}...")
         _download_and_verify(download_url, tar_path, "Binary")
-            
+
     return lib_path
 
+
 def ensure_all_assets():
     """Download models and binaries if missing."""
     ensure_models()

postalkit/data/manager.py

@@ -1,15 +1,22 @@
 class PostalKitError(Exception):
     """Base exception for all PostalKit errors."""
+
     pass
 
+
 class InitializationError(PostalKitError):
     """Raised when libpostal fails to initialize (e.g., memory issues, bad data dir)."""
+
     pass
 
+
 class DependencyMissingError(PostalKitError):
     """Raised when required binaries or data models cannot be downloaded or found."""
+
     pass
 
+
 class ParsingError(PostalKitError):
     """Raised when the C library encounters an error parsing an address."""
+
     pass

postalkit/exceptions.py

@@ -1,24 +1,26 @@
 import os
 import tarfile
-import urllib.request
 from pathlib import Path
+
 import httpx
 from tqdm import tqdm
+
 from ..exceptions import DependencyMissingError
 
+
 def download_file(url: str, dest_path: Path, extract: bool = False, desc: str = "Downloading"):
     """Downloads a file from a URL to a destination path, optionally extracting it."""
     dest_path.parent.mkdir(parents=True, exist_ok=True)
-    
+
     # Simple check if it's already there (for the archive itself, or skipped if extraction is managed externally)
     if dest_path.exists():
         return
-        
+
     try:
         with httpx.stream("GET", url, follow_redirects=True) as response:
             response.raise_for_status()
             total_size = int(response.headers.get("content-length", 0))
-            
+
             with open(dest_path, "wb") as f, tqdm(
                 desc=desc,
                 total=total_size,
@@ -32,16 +34,17 @@ def download_file(url: str, dest_path: Path, extract: bool = False, desc: str =
     except Exception as e:
         if dest_path.exists():
             os.remove(dest_path)
-        raise DependencyMissingError(f"Failed to download {url}: {e}")
+        raise DependencyMissingError from None(f"Failed to download {url}: {e}")
 
     if extract and str(dest_path).endswith(".tar.gz"):
         _extract_tar_gz(dest_path, dest_path.parent)
 
+
 def _extract_tar_gz(tar_path: Path, extract_path: Path):
     print(f"Extracting {tar_path.name}...")
     try:
         with tarfile.open(tar_path, "r:gz") as tar:
             tar.extractall(path=extract_path)
         os.remove(tar_path)
     except Exception as e:
-        raise DependencyMissingError(f"Failed to extract {tar_path}: {e}")
+        raise DependencyMissingError from None(f"Failed to extract {tar_path}: {e}")

postalkit/runtime/downloader.py

@@ -1,34 +1,40 @@
 import ctypes
+
+from ..exceptions import DependencyMissingError
 from ..runtime.paths import get_binary_dir, get_bundled_binary_dir
 from ..runtime.platform import get_library_name
-from ..exceptions import DependencyMissingError
+
 
 def load_libpostal() -> ctypes.CDLL:
     """Loads the libpostal shared library into ctypes."""
     lib_name = get_library_name()
-    
+
     # 1. Check bundled library first
     bundled_lib_path = get_bundled_binary_dir() / lib_name
     if bundled_lib_path.exists():
         try:
             return ctypes.cdll.LoadLibrary(str(bundled_lib_path))
         except OSError as e:
-            raise DependencyMissingError(f"Failed to load bundled library {bundled_lib_path}: {e}")
-    
+            raise DependencyMissingError from None(
+                f"Failed to load bundled library {bundled_lib_path}: {e}"
+            )
+
     # 2. Check auto-downloaded library
     bin_dir = get_binary_dir()
     lib_path = bin_dir / lib_name
-    
+
     if not lib_path.exists():
         # Maybe it's installed system-wide?
         try:
             return ctypes.cdll.LoadLibrary(lib_name)
         except OSError:
             pass
-        raise DependencyMissingError(f"Could not find {lib_name} in {bin_dir}, bundled {bundled_lib_path}, or system paths. Run initialization first.")
-        
+        raise DependencyMissingError from None(
+            f"Could not find {lib_name} in {bin_dir}, bundled {bundled_lib_path}, or system paths. Run initialization first."
+        )
+
     try:
         # Load the library using ctypes
         return ctypes.cdll.LoadLibrary(str(lib_path))
     except OSError as e:
-        raise DependencyMissingError(f"Failed to load shared library {lib_path}: {e}")
+        raise DependencyMissingError from None(f"Failed to load shared library {lib_path}: {e}")