ddsql 0.0.4__tar.gz → 0.2.0__tar.gz

{ddsql-0.0.4 → ddsql-0.2.0}/PKG-INFO

@@ -1,22 +1,20 @@
 Metadata-Version: 2.4
 Name: ddsql
-Version: 0.0.4
+Version: 0.2.0
 Summary: SQL Query Library
-License: MIT
-License-File: LICENSE
 Keywords: python,ddsql
 Author: davyddd
-Requires-Python: >=3.9,<3.15
-Classifier: License :: OSI Approved :: MIT License
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: ddutils (<0.2.0)
-Requires-Dist: jinja2 (>=3.0.0,<4.0.0)
+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
 
@@ -38,6 +36,21 @@ Install the library using pip:
 pip install ddsql
 ```
 
+## Development
+
+The project runs entirely in Docker. Requires Docker and [Fabric](https://www.fabfile.org/) on the host:
+
+```bash
+fab build      # build the dev image
+fab tests      # run pytest
+fab linters    # run ruff (with --fix), ty and complexipy
+fab shell      # IPython inside the container
+fab bash       # bash inside the container
+```
+
+This project was generated from [dd-lib-stub](https://github.com/davyddd/dd-lib-stub);
+run `copier update` to pull in template updates.
+
 ## Serializer
 
 The serializer converts Python types to their SQL representations. 
@@ -120,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(using)` 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(using=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
 
@@ -135,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(using=self.db) 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(db)` picks the database right before executing, like Django's `using`. `_execute` reads
+`self.db` (`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. 
@@ -177,7 +256,7 @@ which wraps raw database rows into the specified model (called internally by `Ad
 
 Required parameters:
 - **model** – a declarative class (e.g., dataclass) describing the output result structure;
-- **text** or **path** – the SQL template source.
+- **text** or **path** – the SQL template source (inline string or path to a file).
 
 ### Inline Template (text)
 
@@ -193,25 +272,24 @@ query = Query(
 
 ### File Template (path)
 
-For file-based templates, set the `SQL_TEMPLATES_DIR` environment variable to the directory containing your SQL files:
-
-```bash
-export SQL_TEMPLATES_DIR=/app/src/templates/sql/
-```
-
-Then use a relative path:
+Pass the path to the SQL file as `Path`. The file is checked at construction time, so a wrong path fails
+on import rather than on the first query:
 
 ```python
+from pathlib import Path
+
 from ddsql.query import Query
 
+SQL_TEMPLATES_DIR = Path(__file__).parent / 'templates' / 'sql'
 
-# Loads template from /app/src/templates/sql/users/get_by_id.sql
 query = Query(
-    model=User, 
-    path='users/get_by_id.sql'
+    model=User,
+    path=SQL_TEMPLATES_DIR / 'users' / 'get_by_id.sql',
 )
 ```
 
+`{% include %}` and `{% import %}` inside the template resolve relative to the template's directory.
+
 ### Result
 
 The result of query execution is a `Result` object that wraps the data into the specified model:
@@ -224,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):
@@ -247,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
 
@@ -273,4 +350,4 @@ async def get_users():
         .execute()
     )
     return result.get_list()
-```
+```

{ddsql-0.0.4 → ddsql-0.2.0}/README.md

@@ -16,6 +16,21 @@ Install the library using pip:
 pip install ddsql
 ```
 
+## Development
+
+The project runs entirely in Docker. Requires Docker and [Fabric](https://www.fabfile.org/) on the host:
+
+```bash
+fab build      # build the dev image
+fab tests      # run pytest
+fab linters    # run ruff (with --fix), ty and complexipy
+fab shell      # IPython inside the container
+fab bash       # bash inside the container
+```
+
+This project was generated from [dd-lib-stub](https://github.com/davyddd/dd-lib-stub);
+run `copier update` to pull in template updates.
+
 ## Serializer
 
 The serializer converts Python types to their SQL representations. 
@@ -98,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(using)` 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(using=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
 
@@ -113,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(using=self.db) 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(db)` picks the database right before executing, like Django's `using`. `_execute` reads
+`self.db` (`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. 
@@ -155,7 +236,7 @@ which wraps raw database rows into the specified model (called internally by `Ad
 
 Required parameters:
 - **model** – a declarative class (e.g., dataclass) describing the output result structure;
-- **text** or **path** – the SQL template source.
+- **text** or **path** – the SQL template source (inline string or path to a file).
 
 ### Inline Template (text)
 
@@ -171,25 +252,24 @@ query = Query(
 
 ### File Template (path)
 
-For file-based templates, set the `SQL_TEMPLATES_DIR` environment variable to the directory containing your SQL files:
-
-```bash
-export SQL_TEMPLATES_DIR=/app/src/templates/sql/
-```
-
-Then use a relative path:
+Pass the path to the SQL file as `Path`. The file is checked at construction time, so a wrong path fails
+on import rather than on the first query:
 
 ```python
+from pathlib import Path
+
 from ddsql.query import Query
 
+SQL_TEMPLATES_DIR = Path(__file__).parent / 'templates' / 'sql'
 
-# Loads template from /app/src/templates/sql/users/get_by_id.sql
 query = Query(
-    model=User, 
-    path='users/get_by_id.sql'
+    model=User,
+    path=SQL_TEMPLATES_DIR / 'users' / 'get_by_id.sql',
 )
 ```
 
+`{% include %}` and `{% import %}` inside the template resolve relative to the template's directory.
+
 ### Result
 
 The result of query execution is a `Result` object that wraps the data into the specified model:
@@ -202,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):
@@ -225,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.2.0/ddsql/__init__.py

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

ddsql-0.2.0/ddsql/adapter.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+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 Hashable, Sequence
+
+    from ddsql.query import Result
+    from ddsql.sqlbase import SQLBase
+
+
+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):
+            raise NotImplementedError(
+                'Subclass of Adapter must define a valid serializer attribute that is a subclass of Serializer'
+            )
+
+    def __init__(self, sql: SQLBase) -> None:
+        self.sql = sql
+        self.db: Hashable | None = None
+
+    def using(self, db: Hashable) -> Self:
+        """
+        Picks the database for this execution, like Django's `using`; `_execute` reads `self.db`
+        (`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.db = db
+        return self
+
+    async def get_query(self) -> str:
+        return await self.sql.query.render_template(
+            params=self.sql.params, template_functions=self.serializer.template_functions
+        )
+
+    async def execute(self) -> Result:
+        return self.sql.query.build_result(await self._execute())
+
+    @abstractmethod
+    async def _execute(self) -> Sequence[dict[str, Any]]: ...
+
+
+AdapterT = TypeVar('AdapterT', bound=Adapter)
+
+
+class AdapterDescriptor(Generic[AdapterT]):
+    adapter_class: type[AdapterT]
+
+    def __init__(self, adapter_class: type[AdapterT]):
+        self.adapter_class = adapter_class
+
+    @overload
+    def __get__(self, sql: None, sql_class: type[SQLBase]) -> AdapterDescriptor[AdapterT]: ...
+
+    @overload
+    def __get__(self, sql: SQLBase, sql_class: type[SQLBase] | None = None) -> AdapterT: ...
+
+    def __get__(self, sql: SQLBase | None, sql_class: type[SQLBase] | None = None) -> AdapterT | AdapterDescriptor[AdapterT]:
+        # accessed on the class, like `SQL.postgres`: return the descriptor itself, as `property` does
+        if sql is None:
+            return self
+        return self.adapter_class(sql)
+
+
+__all__ = ('Adapter', 'AdapterDescriptor')

ddsql-0.2.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(using=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, using: Hashable | None = None) -> ScopedRegistry[ConnectionT]:
+        """The registry of `using`, or of the default connection; `Hashable` because `Adapter.db` is untyped."""
+        alias = self.default if using is None else using
+        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, using: Hashable | None = None) -> ConnectionManagerT:
+        return self.connection_manager_class(self.registry(using))
+
+
+__all__ = ('ConnectionManager', 'ConnectionManagerFactory')

{ddsql-0.0.4 → ddsql-0.2.0}/ddsql/query.py

@@ -1,55 +1,51 @@
-import os
+from collections.abc import Sequence
 from pathlib import Path
-from typing import Any, Dict, Generic, Optional, Sequence, Tuple, Type, TypeVar
+from typing import Any, Generic, TypeVar
 
 from jinja2 import Environment, FileSystemLoader, Template
 
-SQL_TEMPLATES_DIR = os.getenv('SQL_TEMPLATES_DIR')
-
-
 DataT = TypeVar('DataT')
 
 
 class Result(Generic[DataT]):
     rows: Sequence[dict[str, Any]]
-    model: Type[DataT]
+    model: type[DataT]
 
-    def __init__(self, rows: Sequence[dict[str, Any]], model: Type[DataT]):
+    def __init__(self, rows: Sequence[dict[str, Any]], model: type[DataT]):
         self.rows = rows
         self.model = model
 
-    def get(self) -> Optional[DataT]:
+    def get(self) -> DataT | None:
         if not self.rows:
             return None
         return self.model(**self.rows[0])
 
-    def get_list(self) -> Tuple[DataT, ...]:
+    def get_list(self) -> tuple[DataT, ...]:
         return tuple(self.model(**row) for row in self.rows)
 
 
 class Query(Generic[DataT]):
-    model: Type[DataT]
+    model: type[DataT]
     template: Template
 
-    def __init__(self, model: Type[DataT], text: Optional[str] = None, path: Optional[str] = None):
+    def __init__(self, model: type[DataT], text: str | None = None, path: Path | None = None):
         self.model = model
 
         self.template = self.get_template(text, path)
 
     @staticmethod
-    def get_template(text: Optional[str] = None, path: Optional[str] = None) -> Template:
+    def get_template(text: str | None = None, path: Path | None = None) -> Template:
         if text:
-            file_system_loader = FileSystemLoader(Path('.'))
+            file_system_loader = None
             method = 'from_string'
             query = text
         elif path:
-            if SQL_TEMPLATES_DIR is None:
-                raise ValueError(
-                    'SQL Templates dir is not defined. Make sure the SQL_TEMPLATES_DIR environment variable is set correctly.'
-                )
-            file_system_loader = FileSystemLoader(Path(SQL_TEMPLATES_DIR))
+            if not path.is_file():
+                raise FileNotFoundError(f'SQL template not found: {path.resolve()}')
+            # the loader is rooted at the template directory, so `{% include %}` resolves relative to the file
+            file_system_loader = FileSystemLoader(path.parent)
             method = 'get_template'
-            query = path
+            query = path.name
         else:
             raise ValueError('One of `text` or `path` must be specified')
 
@@ -59,7 +55,7 @@ class Query(Generic[DataT]):
 
         return getattr(environment, method)(query)
 
-    def update_globals(self, envs: Optional[Dict[str, Any]] = None):
+    def update_globals(self, envs: dict[str, Any] | None = None):
         if envs:
             self.template.environment.globals.update(envs)
 
@@ -68,7 +64,7 @@ class Query(Generic[DataT]):
         strings = sql.split('\n')
         return '\n'.join([string.strip() for string in strings])
 
-    async def render_template(self, params: Dict[str, Any], template_functions: Optional[Dict[str, Any]] = None) -> str:
+    async def render_template(self, params: dict[str, Any], template_functions: dict[str, Any] | None = None) -> str:
         self.update_globals(template_functions)
 
         rendered_template = await self.template.render_async(**params)

{ddsql-0.0.4 → ddsql-0.2.0}/ddsql/serializers/base.py

@@ -1,13 +1,13 @@
 from collections.abc import Callable, Collection, Mapping
 from datetime import date, datetime
 from decimal import Decimal
-from typing import Any, Dict, Union
+from typing import Any
 from uuid import UUID
 
 
 class BaseSerializer:
     @property
-    def template_functions(self) -> Dict[str, Callable[[Any], str]]:
+    def template_functions(self) -> dict[str, Callable[[Any], str]]:
         return {'serialize_value': self.serialize_value}
 
     def serialize_value(self, value: Any) -> str:
@@ -41,7 +41,7 @@ class BaseSerializer:
         return f'{value}'.lower()
 
     @staticmethod
-    def serialize_number(value: Union[int, float, Decimal]) -> str:
+    def serialize_number(value: int | float | Decimal) -> str:
         return f'{value}'
 
     @staticmethod

{ddsql-0.0.4 → ddsql-0.2.0}/ddsql/serializers/clickhouse.py

@@ -1,11 +1,10 @@
 from datetime import date, datetime
-from typing import Dict
 from uuid import UUID
 
 from ddsql.serializers import BaseSerializer
 
 
-def _build_escape_translation() -> Dict[int, str]:
+def _build_escape_translation() -> dict[int, str]:
     # https://clickhouse.com/docs/en/sql-reference/syntax#string
     translation = {
         ord('\\'): '\\\\',

{ddsql-0.0.4 → ddsql-0.2.0}/ddsql/serializers/postgres.py

@@ -1,6 +1,5 @@
 import re
 from datetime import date, datetime
-from typing import Dict
 from uuid import UUID
 
 from ddsql.serializers import BaseSerializer
@@ -11,7 +10,7 @@ from ddsql.serializers import BaseSerializer
 _ESCAPE_SYNTAX_REQUIRED = re.compile(r'[\\\x00-\x1F\x7F]')
 
 
-def _build_escape_translation() -> Dict[int, str]:
+def _build_escape_translation() -> dict[int, str]:
     # https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-STRINGS-ESCAPE
     translation = {
         ord('\\'): '\\\\',

{ddsql-0.0.4 → ddsql-0.2.0}/ddsql/sqlbase.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
 from abc import ABC
-from typing import TYPE_CHECKING, Any, Dict, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar
 
-from ddutils.annotation_helpers import is_subclass
 from ddutils.class_helpers import classproperty
 
-from ddsql.adapter import Adapter
+from ddsql.adapter import AdapterDescriptor
 
 if TYPE_CHECKING:
     from ddsql.query import Query
@@ -29,22 +28,18 @@ class SQLBase(ABC):
     """
 
     query: Query
-    params: Dict[str, Any]
+    params: dict[str, Any]
 
-    @classmethod
     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')
 
     @classproperty
-    def has_adapters(cls) -> bool:
-        for field in cls.__annotations__:
-            adapter = getattr(cls, field, None)
-            adapter_class = getattr(adapter, '__class__', None)
-            if adapter_class and is_subclass(adapter_class, Adapter):
-                return True
-
-        return False
+    def has_adapters(cls: type[SQLBase]) -> bool:
+        # Descriptors are looked up in the class dictionaries along the MRO, so inherited adapters count
+        # and no adapter gets instantiated just for the check
+        return any(isinstance(value, AdapterDescriptor) for klass in cls.__mro__ for value in vars(klass).values())
 
     def __init__(self, query: Query) -> None:
         self.query = query

ddsql-0.2.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "ddsql"
+description = "SQL Query Library"
+version = "0.2.0"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+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",
+]
+
+[[project.authors]]
+name = "davyddd"
+
+[project.urls]
+Repository = "https://github.com/davyddd/ddsql"
+
+[dependency-groups]
+dev = [
+    "ipdb==0.13.13",
+    "ipython==9.16.1",
+]
+test = [
+    "pytest==9.0.3",
+    "pytest-cov==5.0.0",
+    "parameterized==0.9.0",
+]
+linter = [
+    "ruff==0.15.10",
+    "ty==0.0.15",
+    "complexipy==8.0.1",
+]
+
+[tool.uv.build-backend]
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"

ddsql-0.2.0/pyproject.toml.orig

@@ -0,0 +1,49 @@
+[project]
+name = "ddsql"
+description = "SQL Query Library"
+version = "0.2.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",
+]
+
+[project.urls]
+Repository = "https://github.com/davyddd/ddsql"
+
+[dependency-groups]
+dev = [
+    "ipdb==0.13.13",
+    "ipython==9.16.1",
+]
+test = [
+    "pytest==9.0.3",
+    "pytest-cov==5.0.0",
+    "parameterized==0.9.0",
+]
+linter = [
+    "ruff==0.15.10",
+    "ty==0.0.15",
+    "complexipy==8.0.1",
+]
+
+[tool.uv.build-backend]
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"

ddsql-0.0.4/ddsql/__init__.py

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

ddsql-0.0.4/ddsql/adapter.py

@@ -1,56 +0,0 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Any, Dict, Generic, Optional, Sequence, Type, TypeVar
-
-from ddutils.annotation_helpers import is_subclass
-
-from ddsql.serializers import BaseSerializer
-
-if TYPE_CHECKING:
-    from ddsql.query import Result
-    from ddsql.sqlbase import SQLBase
-
-
-class Adapter(ABC):
-    serializer: BaseSerializer
-
-    @classmethod
-    def __init_subclass__(cls, **kwargs):
-        serializer = getattr(cls, 'serializer', None)
-        serializer_class = getattr(serializer, '__class__', None)
-        if not is_subclass(serializer_class, BaseSerializer):
-            raise NotImplementedError(
-                'Subclass of Adapter must define a valid serializer attribute that is a subclass of Serializer'
-            )
-
-    def __init__(self, sql: SQLBase) -> None:
-        self.sql = sql
-
-    async def get_query(self) -> str:
-        return await self.sql.query.render_template(
-            params=self.sql.params, template_functions=self.serializer.template_functions
-        )
-
-    async def execute(self) -> Result:
-        return self.sql.query.build_result(await self._execute())
-
-    @abstractmethod
-    async def _execute(self) -> Sequence[Dict[str, Any]]:  # noqa: UP006
-        ...
-
-
-AdapterT = TypeVar('AdapterT', bound=Adapter)
-
-
-class AdapterDescriptor(Generic[AdapterT]):
-    adapter_class: Type[AdapterT]  # noqa: UP006
-
-    def __init__(self, adapter_class: Type[AdapterT]):  # noqa: UP006
-        self.adapter_class = adapter_class
-
-    def __get__(self, sql: SQLBase, sql_class: Optional[Type[SQLBase]] = None) -> AdapterT:  # noqa: UP006, UP007
-        return self.adapter_class(sql)
-
-
-__all__ = ('Adapter', 'AdapterDescriptor')

ddsql-0.0.4/pyproject.toml

@@ -1,33 +0,0 @@
-[tool.poetry]
-name = "ddsql"
-description = "SQL Query Library"
-version = "0.0.4"
-authors = ["davyddd"]
-license = "MIT"
-repository = "https://github.com/davyddd/ddsql"
-readme = "README.md"
-keywords = ["python", "ddsql"]
-packages = [{include = "ddsql"}]
-
-[tool.poetry.dependencies]
-python = ">=3.9,<3.15"
-ddutils = "<0.2.0"
-jinja2 = ">=3.0.0,<4.0.0"
-
-[tool.poetry.group.dev.dependencies]
-ipdb = "0.13.9"
-ipython = "8.12.3"
-
-[tool.poetry.group.test.dependencies]
-pytest = "8.1.1"
-pytest-cov = "5.0.0"
-parameterized = "0.9.0"
-typing-extensions = "^4.12.2"
-
-[tool.poetry.group.linter.dependencies]
-mypy = "1.18.2"
-ruff = "0.14.4"
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"