asyncpg-typed 0.1.0__tar.gz → 0.1.2__tar.gz

asyncpg_typed-0.1.2/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include tests *.py

{asyncpg_typed-0.1.0 → asyncpg_typed-0.1.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: asyncpg_typed
-Version: 0.1.0
+Version: 0.1.2
 Summary: Type-safe queries for asyncpg
 Author-email: Levente Hunyadi <hunyadi@gmail.com>
 Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/hunyadi/asyncpg_typed
 Project-URL: Source, https://github.com/hunyadi/asyncpg_typed
-Keywords: asyncpg,typed,database-client
+Keywords: asyncpg,typed,database-client,postgres
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -74,6 +74,25 @@ try:
 
 finally:
     await conn.close()
+
+# create a list of data-class instances from a list of typed tuples
+@dataclass
+class DataObject:
+    boolean_value: bool
+    integer_value: int
+    string_value: str | None
+
+# ✅ Valid initializer call
+items = [DataObject(*row) for row in rows]
+
+@dataclass
+class MismatchedObject:
+    boolean_value: bool
+    integer_value: int
+    string_value: str
+
+# ⚠️ Argument of type "int | None" cannot be assigned to parameter "integer_value" of type "int" in function "__init__"; "None" is not assignable to "int"
+items = [MismatchedObject(*row) for row in rows]
 ```
 
 
@@ -85,19 +104,21 @@ Instantiate a SQL object with the `sql` function:
 
 ```python
 def sql(
-    stmt: str | string.templatelib.Template,
+    stmt: LiteralString | string.templatelib.Template,
     *,
-    args: None | type[P1] | type[tuple[P1, P2]] | type[tuple[P1, P2, P3]] | ... = None,
-    resultset: None | type[R1] | type[tuple[R1, R2]] | type[tuple[R1, R2, R3]] | ... = None
+    args: None | type[tuple[P1, P2]] | type[tuple[P1, P2, P3]] | ... = None,
+    resultset: None | type[tuple[R1, R2]] | type[tuple[R1, R2, R3]] | ... = None,
+    arg: None | type[P] = None,
+    result: None | type[R] = None,
 ) -> _SQL: ...
 ```
 
-The parameter `stmt` represents a SQL expression, either as a string (including an *f-string*) or a template (i.e. a *t-string*).
+The parameter `stmt` represents a SQL expression, either as a literal string or a template (i.e. a *t-string*).
 
 If the expression is a string, it can have PostgreSQL parameter placeholders such as `$1`, `$2` or `$3`:
 
 ```python
-f"INSERT INTO table_name (col_1, col_2, col_3) VALUES ($1, $2, $3);"
+"INSERT INTO table_name (col_1, col_2, col_3) VALUES ($1, $2, $3);"
 ```
 
 If the expression is a *t-string*, it can have replacement fields that evaluate to integers:
@@ -106,11 +127,10 @@ If the expression is a *t-string*, it can have replacement fields that evaluate
 t"INSERT INTO table_name (col_1, col_2, col_3) VALUES ({1}, {2}, {3});"
 ```
 
-The parameters `args` and `resultset` take a series type `P` or `R`, which may be any of the following:
+The parameters `args` and `resultset` take a `tuple` of several types `Px` or `Rx`, each of which may be any of the following:
 
 * (required) simple type
 * optional simple type (`T | None`)
-* `tuple` of several (required or optional) simple types.
 
 Simple types include:
 
@@ -124,6 +144,7 @@ Simple types include:
 * `str`
 * `bytes`
 * `uuid.UUID`
+* a user-defined class that derives from `StrEnum`
 
 Types are grouped together with `tuple`:
 
@@ -131,11 +152,11 @@ Types are grouped together with `tuple`:
 tuple[bool, int, str | None]
 ```
 
-Passing a simple type directly (e.g. `type[T]`) is for convenience, and is equivalent to passing a one-element tuple of the same simple type (i.e. `type[tuple[T]]`).
+The parameters `arg` and `result` take a single type `P` or `R`. Passing a simple type (e.g. `type[T]`) directly via `arg` and `result` is for convenience, and is equivalent to passing a one-element tuple of the same simple type (i.e. `type[tuple[T]]`) via `args` and `resultset`.
 
 The number of types in `args` must correspond to the number of query parameters. (This is validated on calling `sql(...)` for the *t-string* syntax.) The number of types in `resultset` must correspond to the number of columns returned by the query.
 
-Both `args` and `resultset` types must be compatible with their corresponding PostgreSQL query parameter types and resultset column types, respectively. The following table shows the mapping between PostgreSQL and Python types.
+Both `args` and `resultset` types must be compatible with their corresponding PostgreSQL query parameter types and resultset column types, respectively. The following table shows the mapping between PostgreSQL and Python types. When there are multiple options separated by a slash, either of the types can be specified as a source or target type.
 
 | PostgreSQL type   | Python type        |
 | ----------------- | ------------------ |
@@ -152,13 +173,18 @@ Both `args` and `resultset` types must be compatible with their corresponding Po
 | `timetz`          | `time` (tz)        |
 | `timestamp`       | `datetime` (naive) |
 | `timestamptz`     | `datetime` (tz)    |
+| `interval`        | `timedelta`        |
 | `char(N)`         | `str`              |
 | `varchar(N)`      | `str`              |
 | `text`            | `str`              |
 | `bytea`           | `bytes`            |
-| `json`            | `str`              |
-| `jsonb`           | `str`              |
+| `json`            | `str`/`JsonType`   |
+| `jsonb`           | `str`/`JsonType`   |
+| `xml`             | `str`              |
 | `uuid`            | `UUID`             |
+| enumeration       | `E: StrEnum`       |
+
+PostgreSQL types `json` and `jsonb` are [returned by asyncpg](https://magicstack.github.io/asyncpg/current/usage.html#type-conversion) as Python type `str`. However, if we specify the union type `JsonType` in `args` or `resultset`, the JSON string is parsed as if by calling `json.loads()`. (`JsonType` is defined in the module `asyncpg_typed`.) If the library `orjson` is present, its faster routines are invoked instead of the slower standard library implementation in the module `json`.
 
 ### Using a SQL object
 

{asyncpg_typed-0.1.0 → asyncpg_typed-0.1.2}/README.md

@@ -36,6 +36,25 @@ try:
 
 finally:
     await conn.close()
+
+# create a list of data-class instances from a list of typed tuples
+@dataclass
+class DataObject:
+    boolean_value: bool
+    integer_value: int
+    string_value: str | None
+
+# ✅ Valid initializer call
+items = [DataObject(*row) for row in rows]
+
+@dataclass
+class MismatchedObject:
+    boolean_value: bool
+    integer_value: int
+    string_value: str
+
+# ⚠️ Argument of type "int | None" cannot be assigned to parameter "integer_value" of type "int" in function "__init__"; "None" is not assignable to "int"
+items = [MismatchedObject(*row) for row in rows]
 ```
 
 
@@ -47,19 +66,21 @@ Instantiate a SQL object with the `sql` function:
 
 ```python
 def sql(
-    stmt: str | string.templatelib.Template,
+    stmt: LiteralString | string.templatelib.Template,
     *,
-    args: None | type[P1] | type[tuple[P1, P2]] | type[tuple[P1, P2, P3]] | ... = None,
-    resultset: None | type[R1] | type[tuple[R1, R2]] | type[tuple[R1, R2, R3]] | ... = None
+    args: None | type[tuple[P1, P2]] | type[tuple[P1, P2, P3]] | ... = None,
+    resultset: None | type[tuple[R1, R2]] | type[tuple[R1, R2, R3]] | ... = None,
+    arg: None | type[P] = None,
+    result: None | type[R] = None,
 ) -> _SQL: ...
 ```
 
-The parameter `stmt` represents a SQL expression, either as a string (including an *f-string*) or a template (i.e. a *t-string*).
+The parameter `stmt` represents a SQL expression, either as a literal string or a template (i.e. a *t-string*).
 
 If the expression is a string, it can have PostgreSQL parameter placeholders such as `$1`, `$2` or `$3`:
 
 ```python
-f"INSERT INTO table_name (col_1, col_2, col_3) VALUES ($1, $2, $3);"
+"INSERT INTO table_name (col_1, col_2, col_3) VALUES ($1, $2, $3);"
 ```
 
 If the expression is a *t-string*, it can have replacement fields that evaluate to integers:
@@ -68,11 +89,10 @@ If the expression is a *t-string*, it can have replacement fields that evaluate
 t"INSERT INTO table_name (col_1, col_2, col_3) VALUES ({1}, {2}, {3});"
 ```
 
-The parameters `args` and `resultset` take a series type `P` or `R`, which may be any of the following:
+The parameters `args` and `resultset` take a `tuple` of several types `Px` or `Rx`, each of which may be any of the following:
 
 * (required) simple type
 * optional simple type (`T | None`)
-* `tuple` of several (required or optional) simple types.
 
 Simple types include:
 
@@ -86,6 +106,7 @@ Simple types include:
 * `str`
 * `bytes`
 * `uuid.UUID`
+* a user-defined class that derives from `StrEnum`
 
 Types are grouped together with `tuple`:
 
@@ -93,11 +114,11 @@ Types are grouped together with `tuple`:
 tuple[bool, int, str | None]
 ```
 
-Passing a simple type directly (e.g. `type[T]`) is for convenience, and is equivalent to passing a one-element tuple of the same simple type (i.e. `type[tuple[T]]`).
+The parameters `arg` and `result` take a single type `P` or `R`. Passing a simple type (e.g. `type[T]`) directly via `arg` and `result` is for convenience, and is equivalent to passing a one-element tuple of the same simple type (i.e. `type[tuple[T]]`) via `args` and `resultset`.
 
 The number of types in `args` must correspond to the number of query parameters. (This is validated on calling `sql(...)` for the *t-string* syntax.) The number of types in `resultset` must correspond to the number of columns returned by the query.
 
-Both `args` and `resultset` types must be compatible with their corresponding PostgreSQL query parameter types and resultset column types, respectively. The following table shows the mapping between PostgreSQL and Python types.
+Both `args` and `resultset` types must be compatible with their corresponding PostgreSQL query parameter types and resultset column types, respectively. The following table shows the mapping between PostgreSQL and Python types. When there are multiple options separated by a slash, either of the types can be specified as a source or target type.
 
 | PostgreSQL type   | Python type        |
 | ----------------- | ------------------ |
@@ -114,13 +135,18 @@ Both `args` and `resultset` types must be compatible with their corresponding Po
 | `timetz`          | `time` (tz)        |
 | `timestamp`       | `datetime` (naive) |
 | `timestamptz`     | `datetime` (tz)    |
+| `interval`        | `timedelta`        |
 | `char(N)`         | `str`              |
 | `varchar(N)`      | `str`              |
 | `text`            | `str`              |
 | `bytea`           | `bytes`            |
-| `json`            | `str`              |
-| `jsonb`           | `str`              |
+| `json`            | `str`/`JsonType`   |
+| `jsonb`           | `str`/`JsonType`   |
+| `xml`             | `str`              |
 | `uuid`            | `UUID`             |
+| enumeration       | `E: StrEnum`       |
+
+PostgreSQL types `json` and `jsonb` are [returned by asyncpg](https://magicstack.github.io/asyncpg/current/usage.html#type-conversion) as Python type `str`. However, if we specify the union type `JsonType` in `args` or `resultset`, the JSON string is parsed as if by calling `json.loads()`. (`JsonType` is defined in the module `asyncpg_typed`.) If the library `orjson` is present, its faster routines are invoked instead of the slower standard library implementation in the module `json`.
 
 ### Using a SQL object