ddsql 0.2.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddsql
-Version: 0.2.0
+Version: 0.3.1
 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.0,<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:
 
@@ -141,7 +146,7 @@ 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.
+  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.
@@ -177,7 +182,7 @@ async with clickhouse() as client:
 atomic = ConnectionManagerFactory(session_registries, default=PostgresDB.PRIMARY, connection_manager_class=Atomic)
 
 
-async with atomic(using=PostgresDB.REPLICA) as session:
+async with atomic(alias=PostgresDB.REPLICA) as session:
     ...
 ```
 
@@ -202,7 +207,7 @@ class PostgresAdapter(Adapter):
     serializer = PostgresSerializer()
 
     async def _execute(self) -> Sequence[dict[str, Any]]:
-        async with atomic(using=self.db) as session:
+        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()]
@@ -213,8 +218,8 @@ 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:
+`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

{ddsql-0.2.0 → ddsql-0.3.1}/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:
 
@@ -121,7 +126,7 @@ 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.
+  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.
@@ -157,7 +162,7 @@ async with clickhouse() as client:
 atomic = ConnectionManagerFactory(session_registries, default=PostgresDB.PRIMARY, connection_manager_class=Atomic)
 
 
-async with atomic(using=PostgresDB.REPLICA) as session:
+async with atomic(alias=PostgresDB.REPLICA) as session:
     ...
 ```
 
@@ -182,7 +187,7 @@ class PostgresAdapter(Adapter):
     serializer = PostgresSerializer()
 
     async def _execute(self) -> Sequence[dict[str, Any]]:
-        async with atomic(using=self.db) as session:
+        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()]
@@ -193,8 +198,8 @@ 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:
+`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

{ddsql-0.2.0 → ddsql-0.3.1}/ddsql/adapter.py

@@ -31,17 +31,17 @@ class Adapter(ABC):
 
     def __init__(self, sql: SQLBase) -> None:
         self.sql = sql
-        self.db: Hashable | None = None
+        self.alias: Hashable | None = None
 
-    def using(self, db: Hashable) -> Self:
+    def using(self, alias: Hashable) -> Self:
         """
-        Picks the database for this execution, like Django's `using`; `_execute` reads `self.db`
+        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.db = db
+        self.alias = alias
         return self
 
     async def get_query(self) -> str:

{ddsql-0.2.0 → ddsql-0.3.1}/ddsql/connections.py

@@ -41,7 +41,7 @@ class ConnectionManagerFactory(Generic[ConnectionAliasT, ConnectionT, Connection
         atomic = ConnectionManagerFactory(session_registries, default=PostgresDB.PRIMARY, connection_manager_class=Atomic)
 
         async with clickhouse() as client: ...
-        async with atomic(using=PostgresDB.REPLICA) as session: ...
+        async with atomic(alias=PostgresDB.REPLICA) as session: ...
     """
 
     def __init__(
@@ -56,15 +56,15 @@ class ConnectionManagerFactory(Generic[ConnectionAliasT, ConnectionT, Connection
         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
+    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, using: Hashable | None = None) -> ConnectionManagerT:
-        return self.connection_manager_class(self.registry(using))
+    def __call__(self, alias: Hashable | None = None) -> ConnectionManagerT:
+        return self.connection_manager_class(self.registry(alias))
 
 
 __all__ = ('ConnectionManager', 'ConnectionManagerFactory')

{ddsql-0.2.0 → ddsql-0.3.1}/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.2.0 → ddsql-0.3.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "ddsql"
 description = "SQL Query Library"
-version = "0.2.0"
+version = "0.3.1"
 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.0,<0.4.0",
     "jinja2>=3.0.0,<4.0.0",
 ]
 

{ddsql-0.2.0 → ddsql-0.3.1}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "ddsql"
 description = "SQL Query Library"
-version = "0.2.0"
+version = "0.3.1"
 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.0,<0.4.0",
     "jinja2>=3.0.0,<4.0.0",
 ]