ddsql 0.3.0__tar.gz → 0.4.0__tar.gz

{ddsql-0.3.0 → ddsql-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddsql
-Version: 0.3.0
+Version: 0.4.0
 Summary: SQL Query Library
 Keywords: python,ddsql
 Author: davyddd
@@ -12,7 +12,7 @@ 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: ddutils>=0.3.1,<0.4.0
 Requires-Dist: jinja2>=3.0.0,<4.0.0
 Requires-Python: >=3.11, <3.15
 Project-URL: Repository, https://github.com/davyddd/ddsql
@@ -71,6 +71,11 @@ or create your own by inheriting from `BaseSerializer`.
 | `date`               | `'2025-01-01'`          | `'2025-01-01'::date`               | `toDate('2025-01-01')`                                |
 | `list`/`tuple`/`set` | `(item1, item2, ...)`   | `(item1, item2, ...)`              | `(item1, item2, ...)`                                 |
 
+An `Enum` member is serialized by its value: `Kind.ADMIN` of a `class Kind(str, Enum)` renders as `'admin'`,
+a plain `Enum` holding a `datetime` as that `datetime`. A subclass is matched as its base type
+(a `ProfileId(UUID)` as a `UUID`, a `pendulum.DateTime` as a `datetime`). `bytes` and `bytearray` are not
+serialized: like any other type missing from the table they go to `serialize_other_object`.
+
 String values are escaped according to the dialect rules, so quotes, backslashes 
 and control characters cannot break the query:
 
@@ -135,51 +140,10 @@ 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:
-    ...
-```
+Connection routing (`ConnectionManagerFactory`, `ConnectionManager`) lives in
+[ddutils](https://github.com/davyddd/ddutils#connections) since it is not specific to SQL: a `ScopedRegistry` per
+alias, a factory that opens a connection manager on the chosen registry, like Django's `using`. An adapter runs its
+query inside `factory(alias=self.alias)`; see "Choosing the database" below.
 
 ## Adapter
 

{ddsql-0.3.0 → ddsql-0.4.0}/README.md

@@ -51,6 +51,11 @@ or create your own by inheriting from `BaseSerializer`.
 | `date`               | `'2025-01-01'`          | `'2025-01-01'::date`               | `toDate('2025-01-01')`                                |
 | `list`/`tuple`/`set` | `(item1, item2, ...)`   | `(item1, item2, ...)`              | `(item1, item2, ...)`                                 |
 
+An `Enum` member is serialized by its value: `Kind.ADMIN` of a `class Kind(str, Enum)` renders as `'admin'`,
+a plain `Enum` holding a `datetime` as that `datetime`. A subclass is matched as its base type
+(a `ProfileId(UUID)` as a `UUID`, a `pendulum.DateTime` as a `datetime`). `bytes` and `bytearray` are not
+serialized: like any other type missing from the table they go to `serialize_other_object`.
+
 String values are escaped according to the dialect rules, so quotes, backslashes 
 and control characters cannot break the query:
 
@@ -115,51 +120,10 @@ 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:
-    ...
-```
+Connection routing (`ConnectionManagerFactory`, `ConnectionManager`) lives in
+[ddutils](https://github.com/davyddd/ddutils#connections) since it is not specific to SQL: a `ScopedRegistry` per
+alias, a factory that opens a connection manager on the chosen registry, like Django's `using`. An adapter runs its
+query inside `factory(alias=self.alias)`; see "Choosing the database" below.
 
 ## Adapter
 

ddsql-0.4.0/ddsql/__init__.py

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

{ddsql-0.3.0 → ddsql-0.4.0}/ddsql/serializers/base.py

@@ -4,6 +4,9 @@ from decimal import Decimal
 from typing import Any
 from uuid import UUID
 
+from ddutils.annotation_helpers import NON_COMPLEX_SEQUENCE_TYPES
+from ddutils.value_helpers import unwrap_enum
+
 
 class BaseSerializer:
     @property
@@ -11,6 +14,9 @@ class BaseSerializer:
         return {'serialize_value': self.serialize_value}
 
     def serialize_value(self, value: Any) -> str:
+        # an `Enum` member is serialized by its value: `f'{Kind.A}'` of a `class Kind(int, Enum)` is 'Kind.A', not '1'
+        value = unwrap_enum(value)
+
         if value is None:
             return self.serialize_none(value)
         elif isinstance(value, bool):
@@ -27,7 +33,8 @@ class BaseSerializer:
             # the check for date must come after datetime,
             # because a datetime instance can also be identified as a date
             return self.serialize_date(value)
-        elif isinstance(value, Collection) and not isinstance(value, Mapping):
+        elif isinstance(value, Collection) and not isinstance(value, (Mapping, *NON_COMPLEX_SEQUENCE_TYPES)):
+            # `bytes` is a collection of ints, but has no SQL representation here
             return self.serialize_collection(value)
         else:
             return self.serialize_other_object(value)

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

@@ -1,7 +1,7 @@
 [project]
 name = "ddsql"
 description = "SQL Query Library"
-version = "0.3.0"
+version = "0.4.0"
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"
@@ -19,7 +19,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "ddutils>=0.2.0,<0.3.0",
+    "ddutils>=0.3.1,<0.4.0",
     "jinja2>=3.0.0,<4.0.0",
 ]
 

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

@@ -1,7 +1,7 @@
 [project]
 name = "ddsql"
 description = "SQL Query Library"
-version = "0.3.0"
+version = "0.4.0"
 authors = [{ name = "davyddd" }]
 license = "MIT"
 license-files = ["LICENSE"]
@@ -18,7 +18,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "ddutils>=0.2.0,<0.3.0",
+    "ddutils>=0.3.1,<0.4.0",
     "jinja2>=3.0.0,<4.0.0",
 ]
 

ddsql-0.3.0/ddsql/__init__.py

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

ddsql-0.3.0/ddsql/connections.py

@@ -1,70 +0,0 @@
-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')