sqlalchemy-postgres-point 0.1.0__tar.gz

sqlalchemy_postgres_point-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.3
+Name: sqlalchemy-postgres-point
+Version: 0.1.0
+Summary: Lightweight SQLAlchemy custom type for PostgreSQL POINT columns with tuple binding and an earth-distance comparator.
+Keywords: sqlalchemy,postgresql,point,geometry,geospatial,gis,database,types,earthdistance
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: sqlalchemy>=2.0
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/iloveitaly/sqlalchemy-postgres-point
+Description-Content-Type: text/markdown
+
+sqlalchemy-postgres-point
+=========================
+
+Lightweight, pure-Python SQLAlchemy custom type for PostgreSQL `POINT` columns.
+
+Why
+----
+
+PostgreSQL has a native `POINT` type (stored internally as a pair of float8 values). SQLAlchemy does not ship a dedicated high-level type wrapper for simple geometric primitives. This package provides a very small `PointType` you can use immediately without pulling in a full spatial stack (e.g. PostGIS + GeoAlchemy2) when all you need is storing and retrieving `(longitude, latitude)` pairs.
+
+Features
+--------
+
+* Simple `(lng, lat)` tuple binding and result conversion.
+* Safe NULL handling.
+* Literal rendering for DDL / SQL emission.
+* Custom comparator exposing the PostgreSQL earth-distance `<@>` operator (returns a `Float`).
+* `cache_ok = True` for SQLAlchemy 2.x compilation caching.
+
+Installation
+------------
+
+Using `uv` (recommended):
+
+```bash
+uv add sqlalchemy-postgres-point
+```
+
+Or with pip:
+
+```bash
+pip install sqlalchemy-postgres-point
+```
+
+Usage
+-----
+
+```python
+from sqlalchemy import Column, Integer
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy_postgres_point import PointType
+
+
+class Base(DeclarativeBase):
+	pass
+
+
+class Place(Base):
+    __tablename__ = "places"
+    id = Column(Integer, primary_key=True)
+    # Store as (longitude, latitude)
+    location = Column(PointType)
+
+# Example query using the custom comparator
+from sqlalchemy import select
+
+origin = (0.0, 0.0)
+stmt = select(Place.id, Place.location.earth_distance(origin).label("dist"))
+```
+
+The comparator translates `Place.location.earth_distance(origin)` into SQL using the `<@>` operator (requires PostgreSQL with the `cube` / `earthdistance` extension for meaningful results; without extensions the operator may not exist—adapt as needed for your environment). This library only *emits* the operator; it does not manage PostgreSQL extensions.
+
+Returned Python Values
+----------------------
+
+Values are loaded as a 2-tuple of floats `(lng, lat)` or `None` when NULL.
+
+Testing
+-------
+
+Run the test suite with:
+
+```bash
+uv run pytest -q
+```
+
+Development
+-----------
+
+After cloning:
+
+```bash
+uv sync  # installs runtime + dev deps
+uv run pytest -q
+```
+
+Project Structure
+-----------------
+
+* `sqlalchemy_postgres_point/point.py` – Implementation of `PointType`.
+* `tests/test_point.py` – Unit tests for processors and comparator.
+
+Limitations / Notes
+-------------------
+
+* No automatic validation of longitude/latitude ranges; add your own if required.
+* Uses simple textual representation `(lng,lat)` accepted by PostgreSQL `POINT` input parser.
+* If you need advanced spatial indexing / SRID support, look at GeoAlchemy2/PostGIS instead.
+
+License
+-------
+
+MIT (see your project's LICENSE file if added later). Contributions welcome.
+

sqlalchemy_postgres_point-0.1.0/README.md

@@ -0,0 +1,104 @@
+sqlalchemy-postgres-point
+=========================
+
+Lightweight, pure-Python SQLAlchemy custom type for PostgreSQL `POINT` columns.
+
+Why
+----
+
+PostgreSQL has a native `POINT` type (stored internally as a pair of float8 values). SQLAlchemy does not ship a dedicated high-level type wrapper for simple geometric primitives. This package provides a very small `PointType` you can use immediately without pulling in a full spatial stack (e.g. PostGIS + GeoAlchemy2) when all you need is storing and retrieving `(longitude, latitude)` pairs.
+
+Features
+--------
+
+* Simple `(lng, lat)` tuple binding and result conversion.
+* Safe NULL handling.
+* Literal rendering for DDL / SQL emission.
+* Custom comparator exposing the PostgreSQL earth-distance `<@>` operator (returns a `Float`).
+* `cache_ok = True` for SQLAlchemy 2.x compilation caching.
+
+Installation
+------------
+
+Using `uv` (recommended):
+
+```bash
+uv add sqlalchemy-postgres-point
+```
+
+Or with pip:
+
+```bash
+pip install sqlalchemy-postgres-point
+```
+
+Usage
+-----
+
+```python
+from sqlalchemy import Column, Integer
+from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy_postgres_point import PointType
+
+
+class Base(DeclarativeBase):
+	pass
+
+
+class Place(Base):
+    __tablename__ = "places"
+    id = Column(Integer, primary_key=True)
+    # Store as (longitude, latitude)
+    location = Column(PointType)
+
+# Example query using the custom comparator
+from sqlalchemy import select
+
+origin = (0.0, 0.0)
+stmt = select(Place.id, Place.location.earth_distance(origin).label("dist"))
+```
+
+The comparator translates `Place.location.earth_distance(origin)` into SQL using the `<@>` operator (requires PostgreSQL with the `cube` / `earthdistance` extension for meaningful results; without extensions the operator may not exist—adapt as needed for your environment). This library only *emits* the operator; it does not manage PostgreSQL extensions.
+
+Returned Python Values
+----------------------
+
+Values are loaded as a 2-tuple of floats `(lng, lat)` or `None` when NULL.
+
+Testing
+-------
+
+Run the test suite with:
+
+```bash
+uv run pytest -q
+```
+
+Development
+-----------
+
+After cloning:
+
+```bash
+uv sync  # installs runtime + dev deps
+uv run pytest -q
+```
+
+Project Structure
+-----------------
+
+* `sqlalchemy_postgres_point/point.py` – Implementation of `PointType`.
+* `tests/test_point.py` – Unit tests for processors and comparator.
+
+Limitations / Notes
+-------------------
+
+* No automatic validation of longitude/latitude ranges; add your own if required.
+* Uses simple textual representation `(lng,lat)` accepted by PostgreSQL `POINT` input parser.
+* If you need advanced spatial indexing / SRID support, look at GeoAlchemy2/PostGIS instead.
+
+License
+-------
+
+MIT (see your project's LICENSE file if added later). Contributions welcome.
+

sqlalchemy_postgres_point-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "sqlalchemy-postgres-point"
+version = "0.1.0"
+description = "Lightweight SQLAlchemy custom type for PostgreSQL POINT columns with tuple binding and an earth-distance comparator."
+keywords = [
+    "sqlalchemy",
+    "postgresql",
+    "point",
+    "geometry",
+    "geospatial",
+    "gis",
+    "database",
+    "types",
+    "earthdistance",
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["sqlalchemy>=2.0"]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/sqlalchemy-postgres-point" }
+
+
+[build-system]
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.3",
+    "sqlmodel>=0.0.21",
+    "psycopg[binary]>=3.2.0",
+    "activemodel",
+]

sqlalchemy_postgres_point-0.1.0/sqlalchemy_postgres_point/__init__.py

@@ -0,0 +1,11 @@
+"""Top-level package for `sqlalchemy-postgres-point`.
+
+Exports:
+    PointType: SQLAlchemy custom type representing a PostgreSQL POINT column.
+"""
+
+from .point import PointType
+
+__all__ = [
+    "PointType",
+]

sqlalchemy_postgres_point-0.1.0/sqlalchemy_postgres_point/point.py

@@ -0,0 +1,90 @@
+"""
+
+- Points should be stored as (longitude, latitude)
+
+References:
+
+- https://stackoverflow.com/questions/37233116/point-type-in-sqlalchemy
+- https://gist.github.com/kwatch/02b1a5a8899b67df2623
+- https://geoalchemy.readthedocs.io/en/0.5/intro.html
+"""
+
+import math
+import re
+from typing import Tuple
+
+from sqlalchemy.types import Float, UserDefinedType
+
+
+class PointType(UserDefinedType):
+    cache_ok = True
+
+    def get_col_spec(self, **kw):
+        return "POINT"
+
+    @staticmethod
+    def _validate_point(value: Tuple[float, float]) -> Tuple[float, float]:
+        """Validate and normalize a (lng, lat) tuple.
+
+        - Ensures it's a 2-length tuple/list
+        - Casts to float and checks finiteness (no NaN/inf)
+        - Checks ranges: lng in [-180, 180], lat in [-90, 90]
+        """
+        try:
+            lng, lat = value  # type: ignore[misc]
+        except Exception as exc:  # pragma: no cover - type/len issues
+            raise ValueError("Point must be a 2-tuple of (lng, lat)") from exc
+
+        try:
+            lng_f = float(lng)
+            lat_f = float(lat)
+        except Exception as exc:
+            raise ValueError("Point coordinates must be numeric") from exc
+
+        if not (math.isfinite(lng_f) and math.isfinite(lat_f)):
+            raise ValueError("Point coordinates must be finite numbers")
+
+        if not (-180.0 <= lng_f <= 180.0):
+            raise ValueError("Longitude must be within [-180, 180]")
+        if not (-90.0 <= lat_f <= 90.0):
+            raise ValueError("Latitude must be within [-90, 90]")
+
+        return (lng_f, lat_f)
+
+    def bind_processor(self, dialect):
+        def process(value):
+            if value is None:
+                return None
+            lng, lat = self._validate_point(value)
+            return f"({lng},{lat})"
+
+        return process
+
+    def literal_processor(self, dialect):
+        def process(value):
+            if value is None:
+                return "NULL"
+            lng, lat = self._validate_point(value)
+            return f"'({lng},{lat})'"
+
+        return process
+
+    def result_processor(self, dialect, coltype):
+        def process(value):
+            if value is None:
+                return None
+            match = re.match(r"\(([^)]+),([^)]+)\)", value)
+            if match:
+                lng = float(match.group(1))
+                lat = float(match.group(2))
+                # Validate loaded values as well to preserve invariants in Python domain
+                lng, lat = self._validate_point((lng, lat))
+                return (lng, lat)
+            raise ValueError(f"Invalid POINT value: {value}")
+
+        return process
+
+    class comparator_factory(UserDefinedType.Comparator):
+        def earth_distance(self, other):
+            """Compute earth distance using the <@> operator, returning a Float."""
+            return self.op("<@>", return_type=Float())(other)

sqlalchemy_postgres_point-0.1.0/sqlalchemy_postgres_point/utils.py

@@ -0,0 +1,31 @@
+import math
+
+
+def haversine_miles(lat1: float, lng1: float, lat2: float, lng2: float) -> float:
+    """
+    Compute the straight-line distance between two locations on Earth, measured in miles.
+
+    This uses the Haversine formula, which treats the Earth as a sphere and returns the
+    great‑circle distance (the shortest path over the planet's surface). It is ideal for
+    proximity checks (e.g., “within 10 miles?”) and for sorting by closeness. The result
+    is “as‑the‑crow‑flies” distance: it does not reflect driving routes, traffic, terrain,
+    or elevation. For most application use cases up to a few hundred miles, the spherical
+    assumption provides a sufficiently accurate answer (typically within well under 1%).
+
+    Inputs are latitude and longitude in degrees for both points, and the output is a
+    floating‑point number in miles. The function is symmetric in its two points and does
+    not require any external services or API calls.
+    """
+    R = 3958.8
+
+    lat1_rad = math.radians(lat1)
+    lat2_rad = math.radians(lat2)
+    dlat = math.radians(lat2 - lat1)
+    dlng = math.radians(lng2 - lng1)
+
+    a = (
+        math.sin(dlat / 2) ** 2
+        + math.cos(lat1_rad) * math.cos(lat2_rad) * math.sin(dlng / 2) ** 2
+    )
+    c = 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+    return R * c