asyncpg-typed 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,293 @@
1
+ Metadata-Version: 2.4
2
+ Name: asyncpg_typed
3
+ Version: 0.1.3
4
+ Summary: Type-safe queries for asyncpg
5
+ Author-email: Levente Hunyadi <hunyadi@gmail.com>
6
+ Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
7
+ License-Expression: MIT
8
+ Project-URL: Homepage, https://github.com/hunyadi/asyncpg_typed
9
+ Project-URL: Source, https://github.com/hunyadi/asyncpg_typed
10
+ Keywords: asyncpg,typed,database-client,postgres
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3 :: Only
21
+ Classifier: Programming Language :: SQL
22
+ Classifier: Topic :: Database
23
+ Classifier: Topic :: Utilities
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.10
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Requires-Dist: asyncpg>=0.31
29
+ Requires-Dist: typing-extensions>=4.15; python_version < "3.11"
30
+ Provides-Extra: vector
31
+ Requires-Dist: asyncpg-vector>=0.1; extra == "vector"
32
+ Provides-Extra: dev
33
+ Requires-Dist: asyncpg-stubs>=0.31; extra == "dev"
34
+ Requires-Dist: build>=1.3; extra == "dev"
35
+ Requires-Dist: mypy>=1.19; extra == "dev"
36
+ Requires-Dist: ruff>=0.14; extra == "dev"
37
+ Dynamic: license-file
38
+
39
+ # Type-safe queries for asyncpg
40
+
41
+ [asyncpg](https://magicstack.github.io/asyncpg/current/) is a high-performance database client to connect to a PostgreSQL server, and execute SQL statements using the async/await paradigm in Python. The library exposes a `Connection` object, which has methods like `execute` and `fetch` that run SQL queries against the database. Unfortunately, these methods take the query as a plain `str`, arguments as `object`, and the resultset is exposed as a `Record`, which is a `tuple`/`dict` hybrid whose `get` and indexer have a return type of `Any`. There is no mechanism to check compatibility of input or output arguments, even if their types are preliminarily known.
42
+
43
+ This Python library provides "compile-time" validation for SQL queries that linters and type checkers can enforce. By creating a generic `SQL` object and associating input and output type information with the query, the signatures of `execute` and `fetch` reveal the exact expected and returned types.
44
+
45
+
46
+ ## Motivating example
47
+
48
+ ```python
49
+ # create a typed object, setting expected and returned types
50
+ select_where_sql = sql(
51
+ """--sql
52
+ SELECT boolean_value, integer_value, string_value
53
+ FROM sample_data
54
+ WHERE boolean_value = $1 AND integer_value > $2
55
+ ORDER BY integer_value;
56
+ """,
57
+ args=tuple[bool, int],
58
+ resultset=tuple[bool, int, str | None],
59
+ )
60
+
61
+ conn = await asyncpg.connect(host="localhost", port=5432, user="postgres", password="postgres")
62
+ try:
63
+ # ✅ Valid signature
64
+ rows = await select_where_sql.fetch(conn, False, 2)
65
+
66
+ # ✅ Type of "rows" is "list[tuple[bool, int, str | None]]"
67
+ reveal_type(rows)
68
+
69
+ # ⚠️ Argument missing for parameter "arg2"
70
+ rows = await select_where_sql.fetch(conn, False)
71
+
72
+ # ⚠️ Argument of type "float" cannot be assigned to parameter "arg2" of type "int" in function "fetch"; "float" is not assignable to "int"
73
+ rows = await select_where_sql.fetch(conn, False, 3.14)
74
+
75
+ finally:
76
+ await conn.close()
77
+
78
+ # create a list of data-class instances from a list of typed tuples
79
+ @dataclass
80
+ class DataObject:
81
+ boolean_value: bool
82
+ integer_value: int
83
+ string_value: str | None
84
+
85
+ # ✅ Valid initializer call
86
+ items = [DataObject(*row) for row in rows]
87
+
88
+ @dataclass
89
+ class MismatchedObject:
90
+ boolean_value: bool
91
+ integer_value: int
92
+ string_value: str
93
+
94
+ # ⚠️ Argument of type "int | None" cannot be assigned to parameter "integer_value" of type "int" in function "__init__"; "None" is not assignable to "int"
95
+ items = [MismatchedObject(*row) for row in rows]
96
+ ```
97
+
98
+
99
+ ## Syntax
100
+
101
+ ### Creating a SQL object
102
+
103
+ Instantiate a SQL object with the `sql` function:
104
+
105
+ ```python
106
+ def sql(
107
+ stmt: LiteralString | string.templatelib.Template,
108
+ *,
109
+ args: None | type[tuple[P1, P2]] | type[tuple[P1, P2, P3]] | ... = None,
110
+ resultset: None | type[tuple[R1, R2]] | type[tuple[R1, R2, R3]] | ... = None,
111
+ arg: None | type[P] = None,
112
+ result: None | type[R] = None,
113
+ ) -> _SQL: ...
114
+ ```
115
+
116
+ #### Parameters to factory function
117
+
118
+ The parameter `stmt` represents a SQL expression, either as a literal string or a template (i.e. a *t-string*).
119
+
120
+ If the expression is a string, it can have PostgreSQL parameter placeholders such as `$1`, `$2` or `$3`:
121
+
122
+ ```python
123
+ "INSERT INTO table_name (col_1, col_2, col_3) VALUES ($1, $2, $3);"
124
+ ```
125
+
126
+ If the expression is a *t-string*, it can have replacement fields that evaluate to integers:
127
+
128
+ ```python
129
+ t"INSERT INTO table_name (col_1, col_2, col_3) VALUES ({1}, {2}, {3});"
130
+ ```
131
+
132
+ The parameters `args` and `resultset` take a `tuple` of several types `Px` or `Rx`.
133
+
134
+ 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`.
135
+
136
+ 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.
137
+
138
+ #### Argument and resultset types
139
+
140
+ When passing Python types via the parameters `args` and `resultset`, each type may be any of the following:
141
+
142
+ * (required) simple type
143
+ * optional simple type (`T | None`)
144
+ * special union type
145
+
146
+ Simple types include:
147
+
148
+ * `bool`
149
+ * numeric types:
150
+ * `int`
151
+ * `float`
152
+ * `decimal.Decimal`
153
+ * date and time types:
154
+ * `datetime.date`
155
+ * `datetime.time`
156
+ * `datetime.datetime`
157
+ * `datetime.timedelta`
158
+ * `str`
159
+ * `bytes`
160
+ * `uuid.UUID`
161
+ * types defined in the module [ipaddress](https://docs.python.org/3/library/ipaddress.html):
162
+ * `ipaddress.IPv4Address`
163
+ * `ipaddress.IPv6Address`
164
+ * `ipaddress.IPv4Network`
165
+ * `ipaddress.IPv6Network`
166
+ * [asyncpg representations](https://magicstack.github.io/asyncpg/current/api/index.html#module-asyncpg.types) of PostgreSQL geometric types:
167
+ * `asyncpg.Point`
168
+ * `asyncpg.Line`
169
+ * `asyncpg.LineSegment`
170
+ * `asyncpg.Box`
171
+ * `asyncpg.Path`
172
+ * `asyncpg.Polygon`
173
+ * `asyncpg.Circle`
174
+ * concrete types of [asyncpg.Range](https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.types.Range):
175
+ * `asyncpg.Range[int]`
176
+ * `asyncpg.Range[Decimal]`
177
+ * `asyncpg.Range[date]`
178
+ * `asyncpg.Range[datetime]`
179
+ * a user-defined enumeration class that derives from `StrEnum`
180
+
181
+ Custom Python types corresponding to PostgreSQL scalar or [composite types](https://www.postgresql.org/docs/current/rowtypes.html) are permitted. These types need to be pre-registered with [set_type_codec](https://magicstack.github.io/asyncpg/current/api/index.html#asyncpg.connection.Connection.set_type_codec) passing an encoder, a decoder and typically `format="tuple"`.
182
+
183
+ In general, union types are not allowed. However, there are notable exceptions. Special union types are as follows:
184
+
185
+ * `JsonType` to represent an object reconstructed from a JSON string
186
+ * `IPv4Address | IPv6Address` to denote either an IPv4 or IPv6 address
187
+ * `IPv4Network | IPv6Network` to denote either an IPv4 or IPv6 network definition
188
+
189
+ Types are grouped together with `tuple`:
190
+
191
+ ```python
192
+ tuple[bool, int, str | None]
193
+ ```
194
+
195
+ 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.
196
+
197
+ | PostgreSQL type | Python type |
198
+ | ---------------------------- | ---------------------------------- |
199
+ | `bool` | `bool` |
200
+ | `smallint` | `int` |
201
+ | `integer` | `int` |
202
+ | `bigint` | `int` |
203
+ | `real`/`float4` | `float` |
204
+ | `double`/`float8` | `float` |
205
+ | `decimal`/`numeric` | `Decimal` |
206
+ | `date` | `date` |
207
+ | `time` | `time` (naive) |
208
+ | `timetz` | `time` (tz) |
209
+ | `timestamp` | `datetime` (naive) |
210
+ | `timestamptz` | `datetime` (tz) |
211
+ | `interval` | `timedelta` |
212
+ | `char(N)` | `str` |
213
+ | `varchar(N)` | `str` |
214
+ | `text` | `str` |
215
+ | `bytea` | `bytes` |
216
+ | `uuid` | `UUID` |
217
+ | `cidr` | `IPvXNetwork` |
218
+ | `inet` | `IPvXNetwork`/`IPvXAddress` |
219
+ | `macaddr` | `str` |
220
+ | `macaddr8` | `str` |
221
+ | `json` | `str`/`JsonType` |
222
+ | `jsonb` | `str`/`JsonType` |
223
+ | `xml` | `str` |
224
+ | any enumeration type | `E: StrEnum` |
225
+ | `point` | `asyncpg.Point` |
226
+ | `line` | `asyncpg.Line` |
227
+ | `lseg` | `asyncpg.LineSegment` |
228
+ | `box` | `asyncpg.Box` |
229
+ | `path` | `asyncpg.Path` |
230
+ | `polygon` | `asyncpg.Polygon` |
231
+ | `circle` | `asyncpg.Circle` |
232
+ | `int4range` | `asyncpg.Range[int]` |
233
+ | `int8range` | `asyncpg.Range[int]` |
234
+ | `numrange` | `asyncpg.Range[Decimal]` |
235
+ | `tsrange` | `asyncpg.Range[datetime]` (naive) |
236
+ | `tstzrange` | `asyncpg.Range[datetime]` (tz) |
237
+ | `daterange` | `asyncpg.Range[date]` |
238
+
239
+
240
+ 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()`. If the library `orjson` is present, its faster routines are invoked instead of the slower standard library implementation in the module `json`.
241
+
242
+ `JsonType` is defined in the module `asyncpg_typed` as follows:
243
+
244
+ ```python
245
+ JsonType = None | bool | int | float | str | dict[str, "JsonType"] | list["JsonType"]
246
+ ```
247
+
248
+ `IPvXNetwork` is a shorthand for either of the following:
249
+
250
+ * `IPv4Network`
251
+ * `IPv6Network`
252
+ * their union type `IPv4Network | IPv6Network`
253
+
254
+ `IPvXAddress` stands for either of the following:
255
+
256
+ * `IPv4Address`
257
+ * `IPv6Address`
258
+ * their union type `IPv4Address | IPv6Address`
259
+
260
+ #### SQL statement as an f-string
261
+
262
+ In addition to the `sql` function, SQL objects can be created with the functionally identical `unsafe_sql` function. As opposed to its safer alternative, the first parameter of `unsafe_sql` has the plain type `str`, allowing us to pass an f-string. This can prove useful if we want to inject the value of a Python variable at location where binding parameters are not permitted by PostgreSQL syntax, e.g. substitute the name of a database table to dynamically create a SQL statement.
263
+
264
+ ### Using a SQL object
265
+
266
+ The function `sql` returns an object that derives from the base class `_SQL` and is specific to the number and types of parameters passed in `args` and `resultset`.
267
+
268
+ The following functions are available on SQL objects:
269
+
270
+ ```python
271
+ async def execute(self, connection: Connection, *args: *P) -> None: ...
272
+ async def executemany(self, connection: Connection, args: Iterable[tuple[*P]]) -> None: ...
273
+ async def fetch(self, connection: Connection, *args: *P) -> list[tuple[*R]]: ...
274
+ async def fetchmany(self, connection: Connection, args: Iterable[tuple[*P]]) -> list[tuple[*R]]: ...
275
+ async def fetchrow(self, connection: Connection, *args: *P) -> tuple[*R] | None: ...
276
+ async def fetchval(self, connection: Connection, *args: *P) -> R1: ...
277
+ ```
278
+
279
+ `Connection` may be an `asyncpg.Connection` or an `asyncpg.pool.PoolConnectionProxy` acquired from a connection pool.
280
+
281
+ `*P` and `*R` denote several types (a type pack) corresponding to those listed in `args` and `resultset`, respectively.
282
+
283
+ Only those functions are prompted on code completion that make sense in the context of the given number of input and output arguments. Specifically, `fetchval` is available only for a single type passed to `resultset`, and `executemany` and `fetchmany` are available only if the query takes (one or more) parameters.
284
+
285
+ #### Run-time behavior
286
+
287
+ When a call such as `sql.executemany(conn, records)` or `sql.fetch(conn, param1, param2)` is made on a `SQL` object at run time, the library invokes `connection.prepare(sql)` to create a `PreparedStatement` and compares the actual statement signature against the expected Python types. If the expected and actual signatures don't match, an exception `TypeMismatchError` (subclass of `TypeError`) is raised.
288
+
289
+ The set of values for an enumeration type is validated when a prepared statement is created. The string values declared in a Python `StrEnum` are compared against the values listed in PostgreSQL `CREATE TYPE ... AS ENUM` by querying the system table `pg_enum`. If there are missing or extra values on either side, an exception `EnumMismatchError` (subclass of `TypeError`) is raised.
290
+
291
+ Unfortunately, PostgreSQL doesn't propagate nullability via prepared statements: resultset types that are declared as required (e.g. `T` as opposed to `T | None`) are validated at run time. When a `None` value is encountered for a required type, an exception `NoneTypeError` (subclass of `TypeError`) is raised.
292
+
293
+ PostgreSQL doesn't differentiate between IPv4 and IPv6 network definitions, or IPv4 and IPv6 addresses in the types `cidr` and `inet`. This means that semantically a union type is returned. If you specify a more restrictive type, the resultset data is validated dynamically at run time.
@@ -0,0 +1,8 @@
1
+ asyncpg_typed/__init__.py,sha256=pDwWTWeNqXtw0Z0YrHRu_kneHu20X2SggFWK6aczbY8,38766
2
+ asyncpg_typed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
3
+ asyncpg_typed-0.1.3.dist-info/licenses/LICENSE,sha256=rx4jD36wX8TyLZaR2HEOJ6TphFPjKUqoCSSYWzwWNRk,1093
4
+ asyncpg_typed-0.1.3.dist-info/METADATA,sha256=LTGsagnYy0YHn33DUpIEfkRh63mNyH1rdRxCnpyTNZk,15353
5
+ asyncpg_typed-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
6
+ asyncpg_typed-0.1.3.dist-info/top_level.txt,sha256=T0X1nWnXRTi5a5oTErGy572ORDbM9UV9wfhRXWLsaoY,14
7
+ asyncpg_typed-0.1.3.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
8
+ asyncpg_typed-0.1.3.dist-info/RECORD,,
@@ -1,190 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: asyncpg_typed
3
- Version: 0.1.1
4
- Summary: Type-safe queries for asyncpg
5
- Author-email: Levente Hunyadi <hunyadi@gmail.com>
6
- Maintainer-email: Levente Hunyadi <hunyadi@gmail.com>
7
- License-Expression: MIT
8
- Project-URL: Homepage, https://github.com/hunyadi/asyncpg_typed
9
- Project-URL: Source, https://github.com/hunyadi/asyncpg_typed
10
- Keywords: asyncpg,typed,database-client,postgres
11
- Classifier: Development Status :: 5 - Production/Stable
12
- Classifier: Intended Audience :: Developers
13
- Classifier: Operating System :: OS Independent
14
- Classifier: Programming Language :: Python :: 3
15
- Classifier: Programming Language :: Python :: 3.10
16
- Classifier: Programming Language :: Python :: 3.11
17
- Classifier: Programming Language :: Python :: 3.12
18
- Classifier: Programming Language :: Python :: 3.13
19
- Classifier: Programming Language :: Python :: 3.14
20
- Classifier: Programming Language :: Python :: 3 :: Only
21
- Classifier: Programming Language :: SQL
22
- Classifier: Topic :: Database
23
- Classifier: Topic :: Utilities
24
- Classifier: Typing :: Typed
25
- Requires-Python: >=3.10
26
- Description-Content-Type: text/markdown
27
- License-File: LICENSE
28
- Requires-Dist: asyncpg>=0.31
29
- Requires-Dist: typing-extensions>=4.15; python_version < "3.11"
30
- Provides-Extra: vector
31
- Requires-Dist: asyncpg-vector>=0.1; extra == "vector"
32
- Provides-Extra: dev
33
- Requires-Dist: asyncpg-stubs>=0.31; extra == "dev"
34
- Requires-Dist: build>=1.3; extra == "dev"
35
- Requires-Dist: mypy>=1.19; extra == "dev"
36
- Requires-Dist: ruff>=0.14; extra == "dev"
37
- Dynamic: license-file
38
-
39
- # Type-safe queries for asyncpg
40
-
41
- [asyncpg](https://magicstack.github.io/asyncpg/current/) is a high-performance database client to connect to a PostgreSQL server, and execute SQL statements using the async/await paradigm in Python. The library exposes a `Connection` object, which has methods like `execute` and `fetch` that run SQL queries against the database. Unfortunately, these methods take the query as a plain `str`, arguments as `object`, and the resultset is exposed as a `Record`, which is a `tuple`/`dict` hybrid whose `get` and indexer have a return type of `Any`. There is no mechanism to check compatibility of input or output arguments, even if their types are preliminarily known.
42
-
43
- This Python library provides "compile-time" validation for SQL queries that linters and type checkers can enforce. By creating a generic `SQL` object and associating input and output type information with the query, the signatures of `execute` and `fetch` reveal the exact expected and returned types.
44
-
45
-
46
- ## Motivating example
47
-
48
- ```python
49
- # create a typed object, setting expected and returned types
50
- select_where_sql = sql(
51
- """--sql
52
- SELECT boolean_value, integer_value, string_value
53
- FROM sample_data
54
- WHERE boolean_value = $1 AND integer_value > $2
55
- ORDER BY integer_value;
56
- """,
57
- args=tuple[bool, int],
58
- resultset=tuple[bool, int, str | None],
59
- )
60
-
61
- conn = await asyncpg.connect(host="localhost", port=5432, user="postgres", password="postgres")
62
- try:
63
- # ✅ Valid signature
64
- rows = await select_where_sql.fetch(conn, False, 2)
65
-
66
- # ✅ Type of "rows" is "list[tuple[bool, int, str | None]]"
67
- reveal_type(rows)
68
-
69
- # ⚠️ Argument missing for parameter "arg2"
70
- rows = await select_where_sql.fetch(conn, False)
71
-
72
- # ⚠️ Argument of type "float" cannot be assigned to parameter "arg2" of type "int" in function "fetch"; "float" is not assignable to "int"
73
- rows = await select_where_sql.fetch(conn, False, 3.14)
74
-
75
- finally:
76
- await conn.close()
77
- ```
78
-
79
-
80
- ## Syntax
81
-
82
- ### Creating a SQL object
83
-
84
- Instantiate a SQL object with the `sql` function:
85
-
86
- ```python
87
- def sql(
88
- stmt: LiteralString | string.templatelib.Template,
89
- *,
90
- args: None | type[tuple[P1, P2]] | type[tuple[P1, P2, P3]] | ... = None,
91
- resultset: None | type[tuple[R1, R2]] | type[tuple[R1, R2, R3]] | ... = None,
92
- arg: None | type[P] = None,
93
- result: None | type[R] = None,
94
- ) -> _SQL: ...
95
- ```
96
-
97
- The parameter `stmt` represents a SQL expression, either as a literal string or a template (i.e. a *t-string*).
98
-
99
- If the expression is a string, it can have PostgreSQL parameter placeholders such as `$1`, `$2` or `$3`:
100
-
101
- ```python
102
- "INSERT INTO table_name (col_1, col_2, col_3) VALUES ($1, $2, $3);"
103
- ```
104
-
105
- If the expression is a *t-string*, it can have replacement fields that evaluate to integers:
106
-
107
- ```python
108
- t"INSERT INTO table_name (col_1, col_2, col_3) VALUES ({1}, {2}, {3});"
109
- ```
110
-
111
- The parameters `args` and `resultset` take a `tuple` of several types `Px` or `Rx`, each of which may be any of the following:
112
-
113
- * (required) simple type
114
- * optional simple type (`T | None`)
115
-
116
- Simple types include:
117
-
118
- * `bool`
119
- * `int`
120
- * `float`
121
- * `decimal.Decimal`
122
- * `datetime.date`
123
- * `datetime.time`
124
- * `datetime.datetime`
125
- * `str`
126
- * `bytes`
127
- * `uuid.UUID`
128
- * a user-defined class that derives from `StrEnum`
129
-
130
- Types are grouped together with `tuple`:
131
-
132
- ```python
133
- tuple[bool, int, str | None]
134
- ```
135
-
136
- 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`.
137
-
138
- 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.
139
-
140
- 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.
141
-
142
- | PostgreSQL type | Python type |
143
- | ----------------- | ------------------ |
144
- | `bool` | `bool` |
145
- | `smallint` | `int` |
146
- | `integer` | `int` |
147
- | `bigint` | `int` |
148
- | `real`/`float4` | `float` |
149
- | `double`/`float8` | `float` |
150
- | `decimal` | `Decimal` |
151
- | `numeric` | `Decimal` |
152
- | `date` | `date` |
153
- | `time` | `time` (naive) |
154
- | `timetz` | `time` (tz) |
155
- | `timestamp` | `datetime` (naive) |
156
- | `timestamptz` | `datetime` (tz) |
157
- | `char(N)` | `str` |
158
- | `varchar(N)` | `str` |
159
- | `text` | `str` |
160
- | `bytea` | `bytes` |
161
- | `json` | `str` |
162
- | `jsonb` | `str` |
163
- | `uuid` | `UUID` |
164
- | enumeration | `E: StrEnum` |
165
-
166
- ### Using a SQL object
167
-
168
- The function `sql` returns an object that derives from the base class `_SQL` and is specific to the number and types of parameters passed in `args` and `resultset`.
169
-
170
- The following functions are available on SQL objects:
171
-
172
- ```python
173
- async def execute(self, connection: Connection, *args: *P) -> None: ...
174
- async def executemany(self, connection: Connection, args: Iterable[tuple[*P]]) -> None: ...
175
- async def fetch(self, connection: Connection, *args: *P) -> list[tuple[*R]]: ...
176
- async def fetchmany(self, connection: Connection, args: Iterable[tuple[*P]]) -> list[tuple[*R]]: ...
177
- async def fetchrow(self, connection: Connection, *args: *P) -> tuple[*R] | None: ...
178
- async def fetchval(self, connection: Connection, *args: *P) -> R1: ...
179
- ```
180
-
181
- `Connection` may be an `asyncpg.Connection` or an `asyncpg.pool.PoolConnectionProxy` acquired from a connection pool.
182
-
183
- `*P` and `*R` denote several types (a type pack) corresponding to those listed in `args` and `resultset`, respectively.
184
-
185
- Only those functions are prompted on code completion that make sense in the context of the given number of input and output arguments. Specifically, `fetchval` is available only for a single type passed to `resultset`, and `executemany` and `fetchmany` are available only if the query takes (one or more) parameters.
186
-
187
-
188
- ## Run-time behavior
189
-
190
- When a call such as `sql.executemany(conn, records)` or `sql.fetch(conn, param1, param2)` is made on a `SQL` object at run time, the library invokes `connection.prepare(sql)` to create a `PreparedStatement` and compares the actual statement signature against the expected Python types. Unfortunately, PostgreSQL doesn't propagate nullability via prepared statements: resultset types that are declared as required (e.g. `T` as opposed to `T | None`) are validated at run time.
@@ -1,8 +0,0 @@
1
- asyncpg_typed/__init__.py,sha256=2c4xyDjjR-yVrIlcgL-rqLJlWB7_JJR76eRxPDTqAPY,38154
2
- asyncpg_typed/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
3
- asyncpg_typed-0.1.1.dist-info/licenses/LICENSE,sha256=rx4jD36wX8TyLZaR2HEOJ6TphFPjKUqoCSSYWzwWNRk,1093
4
- asyncpg_typed-0.1.1.dist-info/METADATA,sha256=6RqDzYtI9FnIbKAjHHQdhnOQhBfM3pK1IHUOYXNf9yU,8652
5
- asyncpg_typed-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
6
- asyncpg_typed-0.1.1.dist-info/top_level.txt,sha256=T0X1nWnXRTi5a5oTErGy572ORDbM9UV9wfhRXWLsaoY,14
7
- asyncpg_typed-0.1.1.dist-info/zip-safe,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
8
- asyncpg_typed-0.1.1.dist-info/RECORD,,