ddsql 0.1.0__tar.gz → 0.3.0__tar.gz

ddsql-0.1.0/README.md → ddsql-0.3.0/PKG-INFO

@@ -1,3 +1,23 @@
+Metadata-Version: 2.4
+Name: ddsql
+Version: 0.3.0
+Summary: SQL Query Library
+Keywords: python,ddsql
+Author: davyddd
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: ddutils>=0.2.0,<0.3.0
+Requires-Dist: jinja2>=3.0.0,<4.0.0
+Requires-Python: >=3.11, <3.15
+Project-URL: Repository, https://github.com/davyddd/ddsql
+Description-Content-Type: text/markdown
+
 # DDSQL
 
 [![pypi](https://img.shields.io/pypi/v/ddsql.svg)](https://pypi.python.org/pypi/ddsql)
@@ -113,14 +133,67 @@ class CustomSerializer(BaseSerializer):
         }
 ```
 
+## Connections
+
+`ddsql.connections` sits between a `ScopedRegistry` (from [ddutils](https://github.com/davyddd/ddutils)) and
+the code that runs queries. A registry holds one connection per scope: a pooled client per process, a session
+per task. The connections module adds two things on top:
+
+- `ConnectionManagerFactory(registries, default, connection_manager_class=ConnectionManager)` resolves a
+  connection alias to its registry, like Django's `using`. Calling it opens a connection manager on the
+  chosen registry; `registry(alias)` returns the registry itself.
+- `ConnectionManager(registry)` is the default connection manager: an async context manager that hands out
+  the connection of the registry's current scope and releases nothing on exit. Enough for clients that are
+  pools themselves, such as ClickHouse.
+
+Databases with transactions pass their own `connection_manager_class`: a unit of work that begins, commits
+or rolls back and closes the session on exit. It depends on the driver, so it lives in the project.
+
+```python
+import os
+from enum import Enum
+
+from ddutils.scoped_registry import ScopedRegistry
+
+from ddsql.connections import ConnectionManagerFactory
+
+
+class ClickhouseDB(str, Enum):
+    PRIMARY = 'primary'
+
+
+client_registries = {
+    db: ScopedRegistry(create_func=make_client_for(db), scope_func=os.getpid, destructor_method_name='close')
+    for db in ClickhouseDB
+}
+clickhouse = ConnectionManagerFactory(client_registries, default=ClickhouseDB.PRIMARY)
+
+
+async with clickhouse() as client:
+    result = await client.query(sql)
+
+
+# a transactional database: `Atomic` is your unit of work over `registry.scope()`
+atomic = ConnectionManagerFactory(session_registries, default=PostgresDB.PRIMARY, connection_manager_class=Atomic)
+
+
+async with atomic(alias=PostgresDB.REPLICA) as session:
+    ...
+```
+
 ## Adapter
 
-`Adapter` encapsulates database interactions. To create an adapter, inherit from the `Adapter` base class 
+`Adapter` encapsulates database interactions. To create an adapter, inherit from the `Adapter` base class
 and define two required elements:
 - **serializer** – an instance of a serializer for converting Python types to SQL representations;
 - **_execute** method – the database-specific query execution logic.
 
 ```python
+from collections.abc import Sequence
+from typing import Any
+
+from sqlalchemy import text
+
 from ddsql.adapter import Adapter
 from ddsql.serializers import PostgresSerializer
 
@@ -128,13 +201,26 @@ from ddsql.serializers import PostgresSerializer
 class PostgresAdapter(Adapter):
     serializer = PostgresSerializer()
 
-    async def _execute(self) -> Sequence[Dict[str, Any]]:
-        query = await self.get_query()  # get the rendered SQL query
-        async with Atomic() as postgres_session:
-            result = await postgres_session.execute(text(query))
+    async def _execute(self) -> Sequence[dict[str, Any]]:
+        async with atomic(alias=self.alias) as session:
+            query = await self.get_query()  # the rendered SQL query
+            result = await session.execute(text(query))
             return [dict(zip(result.keys(), row)) for row in result.fetchall()]
 ```
 
+Intermediate adapter classes without `_execute` are abstract and need no `serializer`; only concrete
+adapters are validated.
+
+### Choosing the database
+
+`Adapter.using(alias)` picks the connection alias right before executing, like Django's `using`. `_execute`
+reads `self.alias` (`None` means the default) and passes it to whatever opens the connection, as in the example above:
+
+```python
+await SQL(query).postgres.execute()                               # default connection
+await SQL(query).postgres.using(PostgresDB.REPLICA).execute()
+```
+
 ## SQLBase
 
 `SQLBase` is configured once per project and defines which adapters are available for query execution. 
@@ -216,12 +302,11 @@ The result of query execution is a `Result` object that wraps the data into the
 ```python
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Optional
 
-from ddsql.query import Query
-from ddsql.sqlbase import SQLBase
 from ddsql.adapter import Adapter, AdapterDescriptor
+from ddsql.query import Query
 from ddsql.serializers import PostgresSerializer
+from ddsql.sqlbase import SQLBase
 
 
 class PostgresAdapter(Adapter):
@@ -239,7 +324,7 @@ class SQL(SQLBase):
 class User:
     user_id: int
     name: str
-    email: Optional[str]
+    email: str | None
     created_at: datetime
     is_deleted: bool
 

ddsql-0.1.0/PKG-INFO → ddsql-0.3.0/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.4
-Name: ddsql
-Version: 0.1.0
-Summary: SQL Query Library
-Keywords: python,ddsql
-Author: davyddd
-License-Expression: MIT
-License-File: LICENSE
-Requires-Dist: ddutils>=0.2.0,<0.3.0
-Requires-Dist: jinja2>=3.0.0,<4.0.0
-Requires-Python: >=3.11, <3.15
-Project-URL: Repository, https://github.com/davyddd/ddsql
-Description-Content-Type: text/markdown
-
 # DDSQL
 
 [![pypi](https://img.shields.io/pypi/v/ddsql.svg)](https://pypi.python.org/pypi/ddsql)
@@ -127,14 +113,67 @@ class CustomSerializer(BaseSerializer):
         }
 ```
 
+## Connections
+
+`ddsql.connections` sits between a `ScopedRegistry` (from [ddutils](https://github.com/davyddd/ddutils)) and
+the code that runs queries. A registry holds one connection per scope: a pooled client per process, a session
+per task. The connections module adds two things on top:
+
+- `ConnectionManagerFactory(registries, default, connection_manager_class=ConnectionManager)` resolves a
+  connection alias to its registry, like Django's `using`. Calling it opens a connection manager on the
+  chosen registry; `registry(alias)` returns the registry itself.
+- `ConnectionManager(registry)` is the default connection manager: an async context manager that hands out
+  the connection of the registry's current scope and releases nothing on exit. Enough for clients that are
+  pools themselves, such as ClickHouse.
+
+Databases with transactions pass their own `connection_manager_class`: a unit of work that begins, commits
+or rolls back and closes the session on exit. It depends on the driver, so it lives in the project.
+
+```python
+import os
+from enum import Enum
+
+from ddutils.scoped_registry import ScopedRegistry
+
+from ddsql.connections import ConnectionManagerFactory
+
+
+class ClickhouseDB(str, Enum):
+    PRIMARY = 'primary'
+
+
+client_registries = {
+    db: ScopedRegistry(create_func=make_client_for(db), scope_func=os.getpid, destructor_method_name='close')
+    for db in ClickhouseDB
+}
+clickhouse = ConnectionManagerFactory(client_registries, default=ClickhouseDB.PRIMARY)
+
+
+async with clickhouse() as client:
+    result = await client.query(sql)
+
+
+# a transactional database: `Atomic` is your unit of work over `registry.scope()`
+atomic = ConnectionManagerFactory(session_registries, default=PostgresDB.PRIMARY, connection_manager_class=Atomic)
+
+
+async with atomic(alias=PostgresDB.REPLICA) as session:
+    ...
+```
+
 ## Adapter
 
-`Adapter` encapsulates database interactions. To create an adapter, inherit from the `Adapter` base class 
+`Adapter` encapsulates database interactions. To create an adapter, inherit from the `Adapter` base class
 and define two required elements:
 - **serializer** – an instance of a serializer for converting Python types to SQL representations;
 - **_execute** method – the database-specific query execution logic.
 
 ```python
+from collections.abc import Sequence
+from typing import Any
+
+from sqlalchemy import text
+
 from ddsql.adapter import Adapter
 from ddsql.serializers import PostgresSerializer
 
@@ -142,13 +181,26 @@ from ddsql.serializers import PostgresSerializer
 class PostgresAdapter(Adapter):
     serializer = PostgresSerializer()
 
-    async def _execute(self) -> Sequence[Dict[str, Any]]:
-        query = await self.get_query()  # get the rendered SQL query
-        async with Atomic() as postgres_session:
-            result = await postgres_session.execute(text(query))
+    async def _execute(self) -> Sequence[dict[str, Any]]:
+        async with atomic(alias=self.alias) as session:
+            query = await self.get_query()  # the rendered SQL query
+            result = await session.execute(text(query))
             return [dict(zip(result.keys(), row)) for row in result.fetchall()]
 ```
 
+Intermediate adapter classes without `_execute` are abstract and need no `serializer`; only concrete
+adapters are validated.
+
+### Choosing the database
+
+`Adapter.using(alias)` picks the connection alias right before executing, like Django's `using`. `_execute`
+reads `self.alias` (`None` means the default) and passes it to whatever opens the connection, as in the example above:
+
+```python
+await SQL(query).postgres.execute()                               # default connection
+await SQL(query).postgres.using(PostgresDB.REPLICA).execute()
+```
+
 ## SQLBase
 
 `SQLBase` is configured once per project and defines which adapters are available for query execution. 
@@ -230,12 +282,11 @@ The result of query execution is a `Result` object that wraps the data into the
 ```python
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Optional
 
-from ddsql.query import Query
-from ddsql.sqlbase import SQLBase
 from ddsql.adapter import Adapter, AdapterDescriptor
+from ddsql.query import Query
 from ddsql.serializers import PostgresSerializer
+from ddsql.sqlbase import SQLBase
 
 
 class PostgresAdapter(Adapter):
@@ -253,7 +304,7 @@ class SQL(SQLBase):
 class User:
     user_id: int
     name: str
-    email: Optional[str]
+    email: str | None
     created_at: datetime
     is_deleted: bool
 

ddsql-0.3.0/ddsql/__init__.py

@@ -0,0 +1,3 @@
+from . import adapter, connections, query, serializers, sqlbase
+
+__all__ = ('adapter', 'connections', 'query', 'sqlbase', 'serializers')

{ddsql-0.1.0 → ddsql-0.3.0}/ddsql/adapter.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
 
+import inspect
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Generic, TypeVar, overload
+from typing import TYPE_CHECKING, Any, Generic, Self, TypeVar, overload
 
 from ddutils.annotation_helpers import is_subclass
 
 from ddsql.serializers import BaseSerializer
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Hashable, Sequence
 
     from ddsql.query import Result
     from ddsql.sqlbase import SQLBase
@@ -18,6 +19,9 @@ class Adapter(ABC):
     serializer: BaseSerializer
 
     def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)  # keeps Generic / mixins in the MRO working
+        if inspect.isabstract(cls):  # intermediate base classes declare no serializer
+            return
         serializer = getattr(cls, 'serializer', None)
         serializer_class = getattr(serializer, '__class__', None)
         if not is_subclass(serializer_class, BaseSerializer):
@@ -27,6 +31,18 @@ class Adapter(ABC):
 
     def __init__(self, sql: SQLBase) -> None:
         self.sql = sql
+        self.alias: Hashable | None = None
+
+    def using(self, alias: Hashable) -> Self:
+        """
+        Picks the connection alias for this execution, like Django's `using`; `_execute` reads `self.alias`
+        (`None` = default) and passes it to whatever opens the connection:
+
+            await SQL(query).postgres.execute()                               # default connection
+            await SQL(query).postgres.using(PostgresDB.REPLICA).execute()
+        """
+        self.alias = alias
+        return self
 
     async def get_query(self) -> str:
         return await self.sql.query.render_template(

ddsql-0.3.0/ddsql/connections.py

@@ -0,0 +1,70 @@
+from collections.abc import Callable, Hashable, Mapping
+from typing import Any, Generic, TypeVar
+
+from ddutils.scoped_registry import ScopedRegistry
+
+# The name a connection is registered under and selected by, like Django's `using` alias
+ConnectionAliasT = TypeVar('ConnectionAliasT', bound=Hashable)
+# The object a registry holds for a connection: a pooled client, a session
+ConnectionT = TypeVar('ConnectionT')
+# The context manager the factory opens on the chosen registry
+ConnectionManagerT = TypeVar('ConnectionManagerT')
+
+
+class ConnectionManager(Generic[ConnectionT]):
+    """
+    Default connection manager: hands out the connection of the registry's current scope and releases nothing on exit.
+
+    The connection is created on first use via `registry.set()` and kept for the life of its scope,
+    typically a process, since a client is itself a connection pool. Databases with transactions need their
+    own connection manager on top of the registry, e.g. a unit of work that begins, commits and closes a session on exit.
+    """
+
+    def __init__(self, registry: ScopedRegistry[ConnectionT]) -> None:
+        self._registry = registry
+
+    async def __aenter__(self) -> ConnectionT:
+        return await self._registry.set()
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: Any) -> None:
+        return None
+
+
+class ConnectionManagerFactory(Generic[ConnectionAliasT, ConnectionT, ConnectionManagerT]):
+    """
+    Resolves a connection alias to its registry and opens a connection manager on it, like Django's `using`.
+
+    `connection_manager_class` is the context manager opened on the chosen registry: `ConnectionManager` by
+    default, a project class for anything that needs setup and teardown around the connection (transactions):
+
+        clickhouse = ConnectionManagerFactory(client_registries, default=ClickhouseDB.PRIMARY)
+        atomic = ConnectionManagerFactory(session_registries, default=PostgresDB.PRIMARY, connection_manager_class=Atomic)
+
+        async with clickhouse() as client: ...
+        async with atomic(alias=PostgresDB.REPLICA) as session: ...
+    """
+
+    def __init__(
+        self,
+        registries: Mapping[ConnectionAliasT, ScopedRegistry[ConnectionT]],
+        default: ConnectionAliasT,
+        connection_manager_class: Callable[[ScopedRegistry[ConnectionT]], ConnectionManagerT] = ConnectionManager,  # type: ignore[assignment]
+    ) -> None:
+        if default not in registries:
+            raise ValueError(f'Default connection {default!r} is not among the registries')
+        self.registries = registries
+        self.default = default
+        self.connection_manager_class = connection_manager_class
+
+    def registry(self, alias: Hashable | None = None) -> ScopedRegistry[ConnectionT]:
+        """The registry of `alias`, or of the default connection; `Hashable` because `Adapter.alias` is untyped."""
+        alias = self.default if alias is None else alias
+        if alias not in self.registries:
+            raise KeyError(f'Unknown connection {alias!r}; expected one of {list(self.registries)!r}')
+        return self.registries[alias]  # type: ignore[index]
+
+    def __call__(self, alias: Hashable | None = None) -> ConnectionManagerT:
+        return self.connection_manager_class(self.registry(alias))
+
+
+__all__ = ('ConnectionManager', 'ConnectionManagerFactory')

{ddsql-0.1.0 → ddsql-0.3.0}/ddsql/sqlbase.py

@@ -31,6 +31,7 @@ class SQLBase(ABC):
     params: dict[str, Any]
 
     def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)  # keeps Generic / mixins in the MRO working
         if not cls.has_adapters:
             raise NotImplementedError('Subclasses must define at least one adapter')
 

{ddsql-0.1.0 → ddsql-0.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "ddsql"
 description = "SQL Query Library"
-version = "0.1.0"
+version = "0.3.0"
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"
@@ -10,6 +10,14 @@ keywords = [
     "python",
     "ddsql",
 ]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
 dependencies = [
     "ddutils>=0.2.0,<0.3.0",
     "jinja2>=3.0.0,<4.0.0",

{ddsql-0.1.0 → ddsql-0.3.0}/pyproject.toml.orig

@@ -1,13 +1,22 @@
 [project]
 name = "ddsql"
 description = "SQL Query Library"
-version = "0.1.0"
+version = "0.3.0"
 authors = [{ name = "davyddd" }]
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
 keywords = ["python", "ddsql"]
+# uv_build does not derive these from requires-python (poetry did); PyPI and the pyversions badge read them
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
 dependencies = [
     "ddutils>=0.2.0,<0.3.0",
     "jinja2>=3.0.0,<4.0.0",

ddsql-0.1.0/ddsql/__init__.py

@@ -1,3 +0,0 @@
-from . import adapter, query, serializers, sqlbase
-
-__all__ = ('adapter', 'query', 'sqlbase', 'serializers')