refactor: lint all, add extra pre-commit hooks, allow env var db initialisation

Author: spwoodcock

.pre-commit-config.yaml

@@ -26,6 +26,15 @@ repos:
       - id: commitizen
         stages: [commit-msg]
 
+  # Autoformat: general file fixes / time savers
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: mixed-line-ending
+
   # Lint / autoformat: Python code
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.

README.md

@@ -72,19 +72,54 @@ and has an acceptable performance penalty (see [benchmarks](#benchmarks)).
 > - Reduced load on free services such as Nominatim (particularly when running
 > in automated tests frequently).
 
-## Priorities
+### Priorities
 
 - Lightweight package size.
 - Minimal memory footprint.
 - Reasonably good performance.
 
-## How This Package Works
+### How This Package Works
 
 - geonames.org data.
 - Voronoi polygons based on geopoints.
 - Gzipped data bundled with package.
 - Query the Voronois.
 
+## Usage
+
+### Install
+
+Distributed as a pip package on PyPi:
+
+```bash
+pip install pg-nearest-city
+# or use your dependency manager of choice
+```
+
+### Run The Code
+
+Async
+
+```python
+
+```
+
+### Optional (Configure With Env Vars)
+
+- If your app upstream already has a psycopg connection, this can be
+  passed through.
+- If you require a new database connection, the connection parameters
+  can be defined as DbConfig object variables, or alternatively
+  as variables from your system environment:
+
+```dotenv
+PGNEAREST_DB_NAME=cities
+PGNEAREST_DB_USER=cities
+PGNEAREST_DB_PASSWORD=somepassword
+PGNEAREST_DB_HOST=localhost
+PGNEAREST_DB_PORT=5432
+```
+
 ## Benchmarks
 
 - todo

pg_nearest_city/async_nearest_city.py

@@ -1,26 +1,32 @@
+"""Main logic."""
+
+import gzip
 import importlib.resources
-from pg_nearest_city import base_nearest_city
+import logging
+from contextlib import asynccontextmanager
+from typing import Optional
+
 import psycopg
-import gzip
 from psycopg import AsyncCursor
 
-from typing import Optional, Union
-from pg_nearest_city.base_nearest_city import BaseNearestCity
-from pg_nearest_city.base_nearest_city import Location
-from pg_nearest_city.base_nearest_city import InitializationStatus
-from contextlib import asynccontextmanager
-
-import logging
-from typing import Optional
+from pg_nearest_city import base_nearest_city
+from pg_nearest_city.base_nearest_city import (
+    BaseNearestCity,
+    InitializationStatus,
+    Location,
+)
 
 logger = logging.getLogger("pg_nearest_city")
 
+
 class AsyncNearestCity:
+    """Reverse geocoding to the nearest city over 1000 population."""
+
     @classmethod
     @asynccontextmanager
     async def connect(cls, db: psycopg.AsyncConnection | base_nearest_city.DbConfig):
-        """Create a managed NearestCity instance with automatic initialization and cleanup.
-        
+        """Managed NearestCity instance with automatic initialization and cleanup.
+
         Args:
             db: Either a DbConfig for a new connection or an existing psycopg Connection
         """
@@ -34,20 +40,24 @@ async def connect(cls, db: psycopg.AsyncConnection | base_nearest_city.DbConfig)
             conn = await psycopg.AsyncConnection.connect(db.get_connection_string())
 
         geocoder = cls(conn)
-        
+
         try:
             await geocoder.initialize()
             yield geocoder
         finally:
             if not is_external_connection:
                 await conn.close()
 
+    def __init__(
+        self,
+        connection: psycopg.AsyncConnection,
+        logger: Optional[logging.Logger] = None,
+    ):
+        """Initialize reverse geocoder with an existing AsyncConnection.
 
-    def __init__(self, connection: psycopg.AsyncConnection, logger: Optional[logging.Logger] = None):
-        """Initialize reverse geocoder with an existing AsyncConnection
-        
         Args:
             db: An existing psycopg AsyncConnection
+            connection: psycopg.AsyncConnection
             logger: Optional custom logger. If not provided, uses package logger
         """
         # Allow users to provide their own logger while having a sensible default
@@ -69,51 +79,52 @@ async def initialize(self) -> None:
             async with self.connection.cursor() as cur:
                 self._logger.info("Starting database initialization check")
                 status = await self._check_initialization_status(cur)
-                
+
                 if status.is_fully_initialized:
                     self._logger.info("Database already properly initialized")
                     return
-                
+
                 if status.has_table and not status.is_fully_initialized:
                     missing = status.get_missing_components()
                     self._logger.warning(
-                        "Database needs repair. Missing components: %s", 
-                        ", ".join(missing)
+                        "Database needs repair. Missing components: %s",
+                        ", ".join(missing),
                     )
                     self._logger.info("Reinitializing from scratch")
                     await cur.execute("DROP TABLE IF EXISTS pg_nearest_city_geocoding;")
-                
+
                 self._logger.info("Creating geocoding table")
                 await self._create_geocoding_table(cur)
-                
+
                 self._logger.info("Importing city data")
                 await self._import_cities(cur)
-                
+
                 self._logger.info("Processing Voronoi polygons")
                 await self._import_voronoi_polygons(cur)
-                
+
                 self._logger.info("Creating spatial index")
                 await self._create_spatial_index(cur)
-                
+
                 await self.connection.commit()
-                
+
                 self._logger.debug("Verifying final initialization state")
                 final_status = await self._check_initialization_status(cur)
                 if not final_status.is_fully_initialized:
                     missing = final_status.get_missing_components()
                     self._logger.error(
                         "Initialization failed final validation. Missing: %s",
-                        ", ".join(missing)
+                        ", ".join(missing),
                     )
                     raise RuntimeError(
-                        f"Initialization failed final validation. Missing components: {', '.join(missing)}"
+                        "Initialization failed final validation. "
+                        f"Missing components: {', '.join(missing)}"
                     )
-                
+
                 self._logger.info("Initialization complete and verified")
-                
+
         except Exception as e:
             self._logger.error("Database initialization failed: %s", str(e))
-            raise RuntimeError(f"Database initialization failed: {str(e)}")
+            raise RuntimeError(f"Database initialization failed: {str(e)}") from e
 
     async def query(self, lat: float, lon: float) -> Optional[Location]:
         """Find the nearest city to the given coordinates using Voronoi regions.
@@ -129,7 +140,6 @@ async def query(self, lat: float, lon: float) -> Optional[Location]:
             ValueError: If coordinates are out of valid ranges
             RuntimeError: If database query fails
         """
-
         # Validate coordinate ranges
         BaseNearestCity.validate_coordinates(lon, lat)
 
@@ -151,26 +161,27 @@ async def query(self, lat: float, lon: float) -> Optional[Location]:
                 )
         except Exception as e:
             self._logger.error(f"Reverse geocoding failed: {str(e)}")
-            raise RuntimeError(f"Reverse geocoding failed: {str(e)}")
+            raise RuntimeError(f"Reverse geocoding failed: {str(e)}") from e
 
-
-    async def _check_initialization_status(self, cur: psycopg.AsyncCursor) -> InitializationStatus:
+    async def _check_initialization_status(
+        self, cur: psycopg.AsyncCursor
+    ) -> InitializationStatus:
         """Check the status and integrity of the geocoding database.
 
-        Performs essential validation checks to ensure the database is properly initialized
-        and contains valid data.
+        Performs essential validation checks to ensure the database is
+        properly initialized and contains valid data.
         """
         status = InitializationStatus()
-        
+
         # Check table existence
-        await cur.execute(BaseNearestCity._get_table_existance_query())
+        await cur.execute(BaseNearestCity._get_tableexistence_query())
         table_exists = await cur.fetchone()
         status.has_table = bool(table_exists and table_exists[0])
-        
+
         # If table doesn't exist, we can't check other properties
         if not status.has_table:
             return status
-            
+
         # Check table structure
         await cur.execute(BaseNearestCity._get_table_structure_query())
         columns = {col: dtype for col, dtype in await cur.fetchall()}
@@ -186,20 +197,20 @@ async def _check_initialization_status(self, cur: psycopg.AsyncCursor) -> Initia
         # If table doesn't have valid structure, we can't check other properties
         if not status.has_valid_structure:
             return status
-        
+
         # Check data completeness
         await cur.execute(BaseNearestCity._get_data_completeness_query())
         counts = await cur.fetchone()
         total_cities, cities_with_voronoi = counts
-        
+
         status.has_data = total_cities > 0
         status.has_complete_voronoi = cities_with_voronoi == total_cities
-        
+
         # Check spatial index
         await cur.execute(BaseNearestCity._get_spatial_index_check_query())
         has_index = await cur.fetchone()
         status.has_spatial_index = bool(has_index and has_index[0])
-        
+
         return status
 
     async def _import_cities(self, cur: AsyncCursor):
@@ -218,21 +229,22 @@ async def _import_cities(self, cur: AsyncCursor):
                 self._logger.info(f"Imported {copied_bytes:,} bytes of city data")
 
     async def _create_geocoding_table(self, cur: AsyncCursor):
-        """Create the main table"""
+        """Create the main table."""
         await cur.execute("""
             CREATE TABLE pg_nearest_city_geocoding (
                 city varchar,
                 country varchar,
                 lat decimal,
                 lon decimal,
-                geom geometry(Point,4326) GENERATED ALWAYS AS (ST_SetSRID(ST_MakePoint(lon, lat), 4326)) STORED,
+                geom geometry(Point,4326)
+                  GENERATED ALWAYS AS (ST_SetSRID(ST_MakePoint(lon, lat), 4326))
+                  STORED,
                 voronoi geometry(Polygon,4326)
             );
         """)
 
     async def _import_voronoi_polygons(self, cur: AsyncCursor):
         """Import and integrate Voronoi polygons into the main table."""
-
         if not self.voronoi_file.exists():
             raise FileNotFoundError(f"Voronoi file not found: {self.voronoi_file}")
 
@@ -268,7 +280,7 @@ async def _import_voronoi_polygons(self, cur: AsyncCursor):
     async def _create_spatial_index(self, cur: AsyncCursor):
         """Create a spatial index on the Voronoi polygons for efficient queries."""
         await cur.execute("""
-            CREATE INDEX geocoding_voronoi_idx 
-            ON pg_nearest_city_geocoding 
+            CREATE INDEX geocoding_voronoi_idx
+            ON pg_nearest_city_geocoding
             USING GIST (voronoi);
         """)