Merge pull request #30 from Mernus/feature/add-geo-types

Added support for Geometric Types (except Polygon)

Author: chandr-andr

Cargo.lock

@@ -25,9 +25,11 @@ byteorder = "1.5.0"
 chrono = "0.4.33"
 chrono-tz = "0.8.5"
 uuid = { version = "1.7.0", features = ["v4"] }
+serde = { version = "1.0.205", features = ["derive"] }
 serde_json = "1.0.113"
 futures-util = "0.3.30"
 macaddr = "1.0.1"
+geo-types = "0.7.13"
 postgres-types = { git = "https://github.com/chandr-andr/rust-postgres.git", branch = "psqlpy", features = [
     "derive",
 ] }
@@ -36,6 +38,7 @@ tokio-postgres = { git = "https://github.com/chandr-andr/rust-postgres.git", bra
     "array-impls",
     "with-chrono-0_4",
     "with-uuid-1",
+    "with-geo-types-0_7",
 ] }
 postgres-protocol = { git = "https://github.com/chandr-andr/rust-postgres.git", branch = "psqlpy" }
 postgres-openssl = { git = "https://github.com/chandr-andr/rust-postgres.git", branch = "psqlpy" }
@@ -44,3 +47,4 @@ rust_decimal = { git = "https://github.com/chandr-andr/rust-decimal.git", branch
     "db-tokio-postgres",
 ] }
 openssl = { version = "0.10.64", features = ["vendored"] }
+itertools = "0.12.1"

Cargo.toml

@@ -18,6 +18,13 @@ All extra types available from Python with mapping to PostgreSQL type and Rust t
 | PyJSONB | JSONB | serde::Value |
 | PyMacAddr6 | MacAddr | MacAddr6 |
 | PyMacAddr8 | MacAddr8 | MacAddr8 |
+| PyPoint | Point | Point |
+| PyBox | Rect | Box |
+| PyPath | LineString | Path |
+| PyLine | LineSegment | Line |
+| PyLineSegment | LineSegment | Lseg |
+| PyCircle | Circle | Circle |
+
 
 ## BigInt & Integer & SmallInt & Float32 & Float64
 When integer is passed from Python to Rust, it's impossible to understand what type is required on the Database side.
@@ -177,3 +184,43 @@ async def main() -> None:
 
     db_pool.close()
 ```
+
+## Geo Types
+Also in package exists support of PostgreSQL geo types(except Polygon for now).
+To use geo types you need specify them directly.
+
+Let's assume we have table `geo_info` with all PostgreSQL geo types in the database:
+|  database type | database column name |
+| :---: | :---: |
+| POINT | map_point |
+| BOX | point_district |
+| PATH | path_to_point |
+| LINE | points_line |
+| LSEG | lseg_between_points |
+| CIRCLE | point_radius_circle |
+
+```python
+from typing import Final
+
+from psqlpy import ConnectionPool, QueryResult
+from psqlpy.extra_types import PyPoint, PyBox, PyPath, PyLine, PyLineSegment, PyCircle
+
+
+async def main() -> None:
+    # It uses default connection parameters
+    db_pool: Final = ConnectionPool()
+
+    await db_pool.execute(
+        "INSERT INTO geo_info VALUES ($1, $2, $3, $4, $5, $6)",
+        [
+            PyPoint([1.5, 2]),
+            PyBox([(1.7, 2.8), (9, 9)]),
+            PyPath([(3.5, 3), (9, 9), (8, 8)]),
+            PyLine([1, -2, 3]),
+            PyLineSegment([(5.6, 3.1), (4, 5)]),
+            PyCircle([5, 1.8, 10]),
+        ],
+    )
+
+    db_pool.close()
+```

docs/usage/types/extra_types.md

@@ -18,7 +18,7 @@ Here you can find all types supported by `PSQLPy`. If PSQLPy isn't `-`, you can
 | int | INTEGER | INTEGER |
 | int | - | INTEGER |
 | int | BIGINT | BIGINT |
-| float | - | FLOAT4 |
+| float | - | FLOAT8 |
 | float | Float32 | FLOAT4 |
 | float | Float64 | FLOAT8 |
 | datetime.date | - | DATE |

docs/usage/types/supported_types.md

@@ -1,4 +1,4 @@
-from typing import Any, Union
+import typing
 
 from typing_extensions import Self
 
@@ -91,9 +91,9 @@ class PyJSONB:
 
     def __init__(
         self: Self,
-        value: Union[
-            dict[str, Any],
-            list[dict[str, Any]],
+        value: typing.Union[
+            dict[str, typing.Any],
+            list[dict[str, typing.Any]],
         ],
     ) -> None:
         """Create new instance of PyJSON.B.
@@ -109,9 +109,9 @@ class PyJSON:
 
     def __init__(
         self: Self,
-        value: Union[
-            dict[str, Any],
-            list[dict[str, Any]],
+        value: typing.Union[
+            dict[str, typing.Any],
+            list[dict[str, typing.Any]],
         ],
     ) -> None:
         """Create new instance of PyJSON.
@@ -144,3 +144,108 @@ class PyMacAddr8:
 
 class PyCustomType:
     def __init__(self, value: bytes) -> None: ...
+
+Coordinates: typing.TypeAlias = typing.Union[
+    list[int | float],
+    set[int | float],
+    tuple[int | float, int | float],
+]
+PairsOfCoordinates: typing.TypeAlias = typing.Union[
+    list[Coordinates | int | float],
+    set[Coordinates | int | float],
+    tuple[Coordinates | int | float, ...],
+]
+
+class PyPoint:
+    """Represent point field in PostgreSQL and Point in Rust."""
+
+    def __init__(self: Self, value: Coordinates) -> None:
+        """Create new instance of PyPoint.
+
+        It accepts any pair(List, Tuple or Set)
+            of int/float numbers in every combination.
+
+        ### Parameters:
+        - `value`: pair of int/float numbers in every combination.
+        """
+
+class PyBox:
+    """Represent box field in PostgreSQL and Rect in Rust."""
+
+    def __init__(self: Self, value: PairsOfCoordinates) -> None:
+        """Create new instance of PyBox.
+
+        You need to pass any of this structures:
+        - sequence(List, Tuple or Set) of two sequences(List, Tuple or Set),
+            each with pair of int/float numbers in every combination
+        - sequence(List, Tuple or Set) of two pairs of int/float in every combination
+
+        ### Parameters:
+        - `value`: any valid sequence(List, Tuple or Set) with two pairs
+            of int/float numbers in every combination.
+        """
+
+class PyPath:
+    """Represent path field in PostgreSQL and LineString in Rust."""
+
+    def __init__(self: Self, value: PairsOfCoordinates) -> None:
+        """Create new instance of PyPath.
+
+        You need to pass any of this structures:
+        - sequence(List, Tuple or Set) of sequences(List, Tuple or Set),
+            each with pair of int/float numbers in every combination
+        - sequence(List, Tuple or Set) with pairs
+            of int/float numbers in every combination
+
+        ### Parameters:
+        - `value`: any valid structure with int/float numbers in every combination.
+        """
+
+class PyLine:
+    """Represent line field in PostgreSQL and LineSegment in Rust."""
+
+    def __init__(self: Self, value: PairsOfCoordinates) -> None:
+        """Create new instance of PyLine.
+
+        You need to pass any of this structures:
+        - sequence of three int/float numbers(a, b, c)
+
+        ### Parameters:
+        - `value`: any valid structure with int/float numbers.
+        """
+
+class PyLineSegment:
+    """Represent lseg field in PostgreSQL and LineSegment in Rust."""
+
+    def __init__(self: Self, value: PairsOfCoordinates) -> None:
+        """Create new instance of PyLineSegment.
+
+        You need to pass any of this structures:
+        - sequence(List, Tuple or Set) of two sequences(List, Tuple or Set),
+            each with pair of int/float numbers in every combination
+        - sequence(List, Tuple or Set) with two pairs
+            of int/float numbers in every combination
+
+        ### Parameters:
+        - `value`: any valid structure with int/float numbers in every combination.
+        """
+
+class PyCircle:
+    """Represent circle field in PostgreSQL and Circle in Rust."""
+
+    def __init__(
+        self: Self,
+        value: typing.Union[
+            list[int | float],
+            set[int | float],
+            tuple[int | float, int | float, int | float],
+        ],
+    ) -> None:
+        """Create new instance of PyCircle.
+
+        You need to pass any of this structures:
+        - sequence of three int/float numbers(x, y, r)
+
+        ### Parameters:
+        - `value`: any valid structure with int/float numbers.
+        """

python/psqlpy/_internal/extra_types.pyi

@@ -4,11 +4,17 @@
     Float64,
     Integer,
     Money,
+    PyBox,
+    PyCircle,
     PyCustomType,
     PyJSON,
     PyJSONB,
+    PyLine,
+    PyLineSegment,
     PyMacAddr6,
     PyMacAddr8,
+    PyPath,
+    PyPoint,
     PyText,
     PyVarChar,
     SmallInt,
@@ -28,4 +34,10 @@
     "Float32",
     "Float64",
     "Money",
+    "PyPoint",
+    "PyBox",
+    "PyPath",
+    "PyLine",
+    "PyLineSegment",
+    "PyCircle",
 ]