Merge pull request #138 from psqlpy-python/support_dbapi

Changes to connection, transaction and cursor management

Author: chandr-andr

docs/components/connection.md

@@ -200,7 +200,7 @@ async def main() -> None:
     )
 ```
 
-### Back To Pool
+### Close
 Returns connection to the pool.
 It's crucial to commit all transactions and close all cursor which are made from the connection.
 Otherwise, this method won't do anything useful.
@@ -213,5 +213,5 @@ There is no need in this method if you use async context manager.
 async def main() -> None:
     ...
     connection = await db_pool.connection()
-    connection.back_to_pool()
+    connection.close()
 ```

pyproject.toml

@@ -106,3 +106,6 @@ ignore = [
 [tool.ruff.pydocstyle]
 convention = "pep257"
 ignore-decorators = ["typing.overload"]
+
+[project.entry-points."sqlalchemy.dialects"]
+psqlpy = "psqlpy_sqlalchemy.dialect:PSQLPyAsyncDialect"

python/psqlpy/__init__.py

@@ -18,13 +18,17 @@
     connect,
     connect_pool,
 )
+from psqlpy.exceptions import (
+    Error,
+)
 
 __all__ = [
     "ConnRecyclingMethod",
     "Connection",
     "ConnectionPool",
     "ConnectionPoolBuilder",
     "Cursor",
+    "Error",
     "IsolationLevel",
     "KeepaliveConfig",
     "Listener",

python/psqlpy/_internal/__init__.pyi

@@ -253,11 +253,12 @@ class KeepaliveConfig:
         """Initialize new config."""
 
 class Cursor:
-    """Represent opened cursor in a transaction.
+    """Represent binary cursor in a transaction.
 
     It can be used as an asynchronous iterator.
     """
 
+    array_size: int
     cursor_name: str
     querystring: str
     parameters: ParamsT = None
@@ -282,118 +283,27 @@ class Cursor:
 
         Execute DECLARE command for the cursor.
         """
-    async def close(self: Self) -> None:
+    def close(self: Self) -> None:
         """Close the cursor.
 
         Execute CLOSE command for the cursor.
         """
-    async def fetch(
-        self: Self,
-        fetch_number: int | None = None,
-    ) -> QueryResult:
-        """Fetch next <fetch_number> rows.
-
-        By default fetches 10 next rows.
-
-        ### Parameters:
-        - `fetch_number`: how many rows need to fetch.
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_next(
-        self: Self,
-    ) -> QueryResult:
-        """Fetch next row.
-
-        Execute FETCH NEXT
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_prior(
-        self: Self,
-    ) -> QueryResult:
-        """Fetch previous row.
-
-        Execute FETCH PRIOR
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_first(
-        self: Self,
-    ) -> QueryResult:
-        """Fetch first row.
-
-        Execute FETCH FIRST
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_last(
-        self: Self,
-    ) -> QueryResult:
-        """Fetch last row.
-
-        Execute FETCH LAST
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_absolute(
-        self: Self,
-        absolute_number: int,
-    ) -> QueryResult:
-        """Fetch absolute rows.
-
-        Execute FETCH ABSOLUTE <absolute_number>.
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_relative(
-        self: Self,
-        relative_number: int,
-    ) -> QueryResult:
-        """Fetch absolute rows.
-
-        Execute FETCH RELATIVE <relative_number>.
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_forward_all(
-        self: Self,
-    ) -> QueryResult:
-        """Fetch forward all rows.
-
-        Execute FETCH FORWARD ALL.
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_backward(
-        self: Self,
-        backward_count: int,
-    ) -> QueryResult:
-        """Fetch backward rows.
-
-        Execute FETCH BACKWARD <backward_count>.
-
-        ### Returns:
-        result as `QueryResult`.
-        """
-    async def fetch_backward_all(
+    async def execute(
         self: Self,
+        querystring: str,
+        parameters: ParamsT = None,
     ) -> QueryResult:
-        """Fetch backward all rows.
-
-        Execute FETCH BACKWARD ALL.
+        """Start cursor with querystring and parameters.
 
-        ### Returns:
-        result as `QueryResult`.
+        Method should be used instead of context manager
+        and `start` method.
         """
+    async def fetchone(self: Self) -> QueryResult:
+        """Return next one row from the cursor."""
+    async def fetchmany(self: Self, size: int | None = None) -> QueryResult:
+        """Return <size> rows from the cursor."""
+    async def fetchall(self: Self, size: int | None = None) -> QueryResult:
+        """Return all remaining rows from the cursor."""
 
 class Transaction:
     """Single connection for executing queries.
@@ -1098,8 +1008,6 @@ class Connection:
         querystring: str,
         parameters: ParamsT = None,
         fetch_number: int | None = None,
-        scroll: bool | None = None,
-        prepared: bool = True,
     ) -> Cursor:
         """Create new cursor object.
 
@@ -1136,7 +1044,7 @@ class Connection:
                         ...  # do something with this result.
         ```
         """
-    def back_to_pool(self: Self) -> None:
+    def close(self: Self) -> None:
         """Return connection back to the pool.
 
         It necessary to commit all transactions and close all cursor

python/tests/test_connection.py

@@ -145,7 +145,7 @@ async def test_connection_cursor(
     await transaction.begin()
     cursor = connection.cursor(querystring=f"SELECT * FROM {table_name}")
     await cursor.start()
-    await cursor.close()
+    cursor.close()
     await transaction.commit()
 
 
@@ -172,7 +172,7 @@ async def test_closed_connection_error(
 ) -> None:
     """Test exception when connection is closed."""
     connection = await psql_pool.connection()
-    connection.back_to_pool()
+    connection.close()
 
     with pytest.raises(expected_exception=ConnectionClosedError):
         await connection.execute("SELECT 1")