sqlalchemy-postgres-point 0.2.0__tar.gz → 0.2.2__tar.gz

{sqlalchemy_postgres_point-0.2.0 → sqlalchemy_postgres_point-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sqlalchemy-postgres-point
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -15,18 +15,15 @@ Description-Content-Type: text/markdown
 ![GitHub CI Status](https://github.com/iloveitaly/sqlalchemy-postgres-point/actions/workflows/build_and_publish.yml/badge.svg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-sqlalchemy-postgres-point
-=========================
+# sqlalchemy-postgres-point
 
 Lightweight, pure-Python SQLAlchemy custom type for PostgreSQL `POINT` columns.
 
-Why
-----
+## 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
---------
+## Features
 
 * Simple `(lng, lat)` tuple binding and result conversion.
 * Safe NULL handling.
@@ -34,23 +31,13 @@ Features
 * Custom comparator exposing the PostgreSQL earth-distance `<@>` operator (returns a `Float`).
 * `cache_ok = True` for SQLAlchemy 2.x compilation caching.
 
-Installation
-------------
-
-Using `uv` (recommended):
+## Installation
 
 ```bash
 uv add sqlalchemy-postgres-point
 ```
 
-Or with pip:
-
-```bash
-pip install sqlalchemy-postgres-point
-```
-
-Usage
------
+## Usage
 
 ```python
 from sqlalchemy import Column, Integer
@@ -59,7 +46,7 @@ from sqlalchemy_postgres_point import PointType
 
 
 class Base(DeclarativeBase):
-	pass
+    pass
 
 
 class Place(Base):
@@ -68,6 +55,7 @@ class Place(Base):
     # Store as (longitude, latitude)
     location = Column(PointType)
 
+
 # Example query using the custom comparator
 from sqlalchemy import select
 
@@ -93,14 +81,15 @@ Revises: your_previous_revision
 Create Date: 2025-01-XX XX:XX:XX.XXXXXX
 
 """
+
 from typing import Sequence, Union
 
 from alembic import op
 import sqlalchemy as sa
 
 # revision identifiers, used by Alembic.
-revision: str = 'your_revision_id'
-down_revision: Union[str, None] = 'your_previous_revision'
+revision: str = "your_revision_id"
+down_revision: Union[str, None] = "your_previous_revision"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 
@@ -119,81 +108,65 @@ DROP EXTENSION IF EXISTS cube;
 """)
 ```
 
-**Integration Steps:**
+#### Integration Steps
 
 1. Generate a new migration: `alembic revision -m "add_postgres_extensions"`
 2. Copy the `upgrade()` and `downgrade()` functions above into your new migration file
 3. Run the migration: `alembic upgrade head`
 
-Returned Python Values
-----------------------
+## Returned Python Values
 
 Values are loaded as a 2-tuple of floats `(lng, lat)` or `None` when NULL.
 
-Testing
--------
+## Alembic Integration
 
-Run the test suite with:
+To ensure generated migration files include the correct `PointType` import, pass the provided `render_item` hook to `context.configure()` in your `alembic/env.py`. This must be added to **both** `run_migrations_online` and `run_migrations_offline`:
 
-```bash
-uv run pytest -q
+```python
+from sqlalchemy_postgres_point.alembic_integration import (
+    render_item as render_point_item,
+)
+
+context.configure(
+    # ... other options ...
+    render_item=render_point_item,
+)
 ```
 
-## Alembic Integration
+Once wired up, `from sqlalchemy_postgres_point import PointType` will be automatically included in generated migration files whenever a `PointType` column is detected.
 
-When using `PointType` in your models, you can automatically include the necessary imports in migration files by updating your `alembic/env.py` file.
+### Chaining `render_item`
 
-First, import the integration module:
+If you need to combine this with other packages that also provide a `render_item`, chain them:
 
 ```python
-import sqlalchemy_postgres_point.alembic_integration
-```
+from sqlalchemy_postgres_point.alembic_integration import (
+    render_item as render_point_item,
+)
 
-Then, ensure your `context.configure` call includes a `render_item` hook to handle the `PointType`:
 
-```python
 def render_item(type_, obj, autogen_context):
-    if type_ == "type" and type(obj).__name__ == "PointType":
-        return sqlalchemy_postgres_point.alembic_integration.render_point_type(obj, obj, autogen_context)
-    return False
+    return (
+        render_point_item(type_, obj, autogen_context)
+        or other_package.render_item(type_, obj, autogen_context)
+        or False
+    )
+
 
-# ... in run_migrations_online and run_migrations_offline ...
 context.configure(
     # ... other options ...
     render_item=render_item,
 )
 ```
 
-Once added, `from sqlalchemy_postgres_point import PointType` will be automatically included in generated migration files whenever a `PointType` column is detected.
-
-Development
------------
-
-After cloning:
-
-```bash
-uv sync  # installs runtime + dev deps
-uv run pytest -q
-```
-
-Project Structure
------------------
+Or you could use something like [`some_fn`](https://funcy.readthedocs.io/en/stable/funcs.html#some_fn) to make this even cleaner.
 
-* `sqlalchemy_postgres_point/point.py` – Implementation of `PointType`.
-* `tests/test_point.py` – Unit tests for processors and comparator.
+## Limitations / Notes
 
-Limitations / Notes
--------------------
-
-* No automatic validation of longitude/latitude ranges; add your own if required.
+* Coordinates are validated on both write and read: longitude must be within `[-180, 180]`, latitude within `[-90, 90]`, and non-finite values (`NaN`, `inf`) are rejected with a `ValueError`.
 * 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.
-
 ---
 
 *This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*

{sqlalchemy_postgres_point-0.2.0 → sqlalchemy_postgres_point-0.2.2}/README.md

@@ -3,18 +3,15 @@
 ![GitHub CI Status](https://github.com/iloveitaly/sqlalchemy-postgres-point/actions/workflows/build_and_publish.yml/badge.svg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-sqlalchemy-postgres-point
-=========================
+# sqlalchemy-postgres-point
 
 Lightweight, pure-Python SQLAlchemy custom type for PostgreSQL `POINT` columns.
 
-Why
-----
+## 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
---------
+## Features
 
 * Simple `(lng, lat)` tuple binding and result conversion.
 * Safe NULL handling.
@@ -22,23 +19,13 @@ Features
 * Custom comparator exposing the PostgreSQL earth-distance `<@>` operator (returns a `Float`).
 * `cache_ok = True` for SQLAlchemy 2.x compilation caching.
 
-Installation
-------------
-
-Using `uv` (recommended):
+## Installation
 
 ```bash
 uv add sqlalchemy-postgres-point
 ```
 
-Or with pip:
-
-```bash
-pip install sqlalchemy-postgres-point
-```
-
-Usage
------
+## Usage
 
 ```python
 from sqlalchemy import Column, Integer
@@ -47,7 +34,7 @@ from sqlalchemy_postgres_point import PointType
 
 
 class Base(DeclarativeBase):
-	pass
+    pass
 
 
 class Place(Base):
@@ -56,6 +43,7 @@ class Place(Base):
     # Store as (longitude, latitude)
     location = Column(PointType)
 
+
 # Example query using the custom comparator
 from sqlalchemy import select
 
@@ -81,14 +69,15 @@ Revises: your_previous_revision
 Create Date: 2025-01-XX XX:XX:XX.XXXXXX
 
 """
+
 from typing import Sequence, Union
 
 from alembic import op
 import sqlalchemy as sa
 
 # revision identifiers, used by Alembic.
-revision: str = 'your_revision_id'
-down_revision: Union[str, None] = 'your_previous_revision'
+revision: str = "your_revision_id"
+down_revision: Union[str, None] = "your_previous_revision"
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 
@@ -107,81 +96,65 @@ DROP EXTENSION IF EXISTS cube;
 """)
 ```
 
-**Integration Steps:**
+#### Integration Steps
 
 1. Generate a new migration: `alembic revision -m "add_postgres_extensions"`
 2. Copy the `upgrade()` and `downgrade()` functions above into your new migration file
 3. Run the migration: `alembic upgrade head`
 
-Returned Python Values
-----------------------
+## Returned Python Values
 
 Values are loaded as a 2-tuple of floats `(lng, lat)` or `None` when NULL.
 
-Testing
--------
+## Alembic Integration
 
-Run the test suite with:
+To ensure generated migration files include the correct `PointType` import, pass the provided `render_item` hook to `context.configure()` in your `alembic/env.py`. This must be added to **both** `run_migrations_online` and `run_migrations_offline`:
 
-```bash
-uv run pytest -q
+```python
+from sqlalchemy_postgres_point.alembic_integration import (
+    render_item as render_point_item,
+)
+
+context.configure(
+    # ... other options ...
+    render_item=render_point_item,
+)
 ```
 
-## Alembic Integration
+Once wired up, `from sqlalchemy_postgres_point import PointType` will be automatically included in generated migration files whenever a `PointType` column is detected.
 
-When using `PointType` in your models, you can automatically include the necessary imports in migration files by updating your `alembic/env.py` file.
+### Chaining `render_item`
 
-First, import the integration module:
+If you need to combine this with other packages that also provide a `render_item`, chain them:
 
 ```python
-import sqlalchemy_postgres_point.alembic_integration
-```
+from sqlalchemy_postgres_point.alembic_integration import (
+    render_item as render_point_item,
+)
 
-Then, ensure your `context.configure` call includes a `render_item` hook to handle the `PointType`:
 
-```python
 def render_item(type_, obj, autogen_context):
-    if type_ == "type" and type(obj).__name__ == "PointType":
-        return sqlalchemy_postgres_point.alembic_integration.render_point_type(obj, obj, autogen_context)
-    return False
+    return (
+        render_point_item(type_, obj, autogen_context)
+        or other_package.render_item(type_, obj, autogen_context)
+        or False
+    )
+
 
-# ... in run_migrations_online and run_migrations_offline ...
 context.configure(
     # ... other options ...
     render_item=render_item,
 )
 ```
 
-Once added, `from sqlalchemy_postgres_point import PointType` will be automatically included in generated migration files whenever a `PointType` column is detected.
-
-Development
------------
-
-After cloning:
-
-```bash
-uv sync  # installs runtime + dev deps
-uv run pytest -q
-```
-
-Project Structure
------------------
+Or you could use something like [`some_fn`](https://funcy.readthedocs.io/en/stable/funcs.html#some_fn) to make this even cleaner.
 
-* `sqlalchemy_postgres_point/point.py` – Implementation of `PointType`.
-* `tests/test_point.py` – Unit tests for processors and comparator.
+## Limitations / Notes
 
-Limitations / Notes
--------------------
-
-* No automatic validation of longitude/latitude ranges; add your own if required.
+* Coordinates are validated on both write and read: longitude must be within `[-180, 180]`, latitude within `[-90, 90]`, and non-finite values (`NaN`, `inf`) are rejected with a `ValueError`.
 * 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.
-
 ---
 
 *This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*

{sqlalchemy_postgres_point-0.2.0 → sqlalchemy_postgres_point-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlalchemy-postgres-point"
-version = "0.2.0"
+version = "0.2.2"
 description = "Lightweight SQLAlchemy custom type for PostgreSQL POINT columns with tuple binding and an earth-distance comparator."
 keywords = [
     "sqlalchemy",
@@ -21,7 +21,7 @@ urls = { "Repository" = "https://github.com/iloveitaly/sqlalchemy-postgres-point
 
 
 [build-system]
-requires = ["uv_build>=0.10.0"]
+requires = ["uv_build>=0.11.0,<0.13"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

sqlalchemy_postgres_point-0.2.2/sqlalchemy_postgres_point/alembic_integration.py

@@ -0,0 +1,32 @@
+"""
+Alembic integration for rendering PointType in generated migration files.
+
+Usage — add two lines to your alembic/env.py:
+
+    from sqlalchemy_postgres_point.alembic_integration import render_item
+
+Then pass it to both context.configure() calls:
+
+    context.configure(
+        ...,
+        render_item=render_item,
+    )
+
+Once wired up, ``from sqlalchemy_postgres_point import PointType`` will be
+automatically included in generated migration files whenever PointType is used.
+"""
+
+from .point import PointType
+
+
+def render_item(type_, obj, autogen_context):
+    """Alembic render_item hook that handles PointType columns.
+
+    Returns "PointType()" and registers the import when the rendered item is a
+    PointType instance. Returns False for everything else so Alembic falls back
+    to its default rendering.
+    """
+    if type_ == "type" and isinstance(obj, PointType):
+        autogen_context.imports.add("from sqlalchemy_postgres_point import PointType")
+        return "PointType()"
+    return False

{sqlalchemy_postgres_point-0.2.0 → sqlalchemy_postgres_point-0.2.2}/sqlalchemy_postgres_point/point.py

@@ -11,7 +11,6 @@ References:
 
 import math
 import re
-from typing import Tuple
 
 from sqlalchemy.types import Float, UserDefinedType
 
@@ -23,7 +22,7 @@ class PointType(UserDefinedType):
         return "POINT"
 
     @staticmethod
-    def _validate_point(value: Tuple[float, float]) -> Tuple[float, float]:
+    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

sqlalchemy_postgres_point-0.2.0/sqlalchemy_postgres_point/alembic_integration.py

@@ -1,56 +0,0 @@
-"""
-Alembic integration to automatically add imports for PointType in migration files.
-
-This module hooks into Alembic's autogenerate system to automatically include
-the necessary import statement when PointType is detected in models.
-
-Usage:
-    Add this import to your alembic/env.py file:
-
-    import sqlalchemy_postgres_point.alembic_integration
-
-Once added, `from sqlalchemy_postgres_point import PointType` will be automatically
-included in generated migration files.
-"""
-
-import alembic.autogenerate
-import alembic.operations.ops
-from sqlalchemy.types import UserDefinedType
-
-from .point import PointType
-
-
-def render_point_type(type_, object_, autogen_context):
-    """Render PointType in migration files with proper import."""
-    # Add the import to the migration file
-    autogen_context.imports.add("from sqlalchemy_postgres_point import PointType")
-    return "PointType()"
-
-
-# Register the renderer for PointType
-alembic.autogenerate.render.renderers.dispatch_for(PointType, replace=True)(
-    render_point_type
-)
-
-
-# Also register for UserDefinedType as a fallback if the class doesn't match exactly
-@alembic.autogenerate.render.renderers.dispatch_for(UserDefinedType, replace=True)
-def render_user_defined_type(type_, object_, autogen_context):
-    if type(object_).__name__ == "PointType":
-        return render_point_type(type_, object_, autogen_context)
-    return False
-
-
-@alembic.autogenerate.comparators.dispatch_for("schema")
-def compare_point_types(
-    autogen_context: alembic.autogenerate.api.AutogenContext,
-    upgrade_ops: alembic.operations.ops.UpgradeOps,
-    schema_names,
-):
-    """
-    Hook into Alembic's schema comparison to detect PointType usage.
-
-    This ensures the import is added even if PointType is used in existing
-    columns that might not trigger the render hook directly.
-    """
-    pass