Pyzzel 0.1.1__tar.gz
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.
- pyzzel-0.1.1/LICENSE +21 -0
- pyzzel-0.1.1/PKG-INFO +9 -0
- pyzzel-0.1.1/README.md +605 -0
- pyzzel-0.1.1/pyproject.toml +22 -0
- pyzzel-0.1.1/setup.cfg +4 -0
- pyzzel-0.1.1/src/Pyzzel.egg-info/PKG-INFO +9 -0
- pyzzel-0.1.1/src/Pyzzel.egg-info/SOURCES.txt +53 -0
- pyzzel-0.1.1/src/Pyzzel.egg-info/dependency_links.txt +1 -0
- pyzzel-0.1.1/src/Pyzzel.egg-info/requires.txt +4 -0
- pyzzel-0.1.1/src/Pyzzel.egg-info/top_level.txt +1 -0
- pyzzel-0.1.1/src/pyzzel/__init__.py +46 -0
- pyzzel-0.1.1/src/pyzzel/core/__init__.py +26 -0
- pyzzel-0.1.1/src/pyzzel/core/base.py +465 -0
- pyzzel-0.1.1/src/pyzzel/core/column.py +222 -0
- pyzzel-0.1.1/src/pyzzel/core/query.py +365 -0
- pyzzel-0.1.1/src/pyzzel/core/types.py +95 -0
- pyzzel-0.1.1/src/pyzzel/errors.py +49 -0
- pyzzel-0.1.1/src/pyzzel/migrate/__init__.py +61 -0
- pyzzel-0.1.1/src/pyzzel/migrate/__main__.py +118 -0
- pyzzel-0.1.1/src/pyzzel/migrate/apply.py +158 -0
- pyzzel-0.1.1/src/pyzzel/migrate/compare.py +58 -0
- pyzzel-0.1.1/src/pyzzel/migrate/diff.py +180 -0
- pyzzel-0.1.1/src/pyzzel/migrate/introspect.py +133 -0
- pyzzel-0.1.1/src/pyzzel/migrate/schema.py +137 -0
- pyzzel-0.1.1/src/pyzzel/migrate/sqlgen.py +79 -0
- pyzzel-0.1.1/src/pyzzel/pool.py +108 -0
- pyzzel-0.1.1/src/pyzzel/sql/__init__.py +50 -0
- pyzzel-0.1.1/src/pyzzel/sql/builder.py +357 -0
- pyzzel-0.1.1/src/pyzzel/sql/conditions.py +195 -0
- pyzzel-0.1.1/tests/test_conditions.py +127 -0
- pyzzel-0.1.1/tests/test_connection.py +114 -0
- pyzzel-0.1.1/tests/test_crud.py +210 -0
- pyzzel-0.1.1/tests/test_database.py +145 -0
- pyzzel-0.1.1/tests/test_import.py +35 -0
- pyzzel-0.1.1/tests/test_joins.py +134 -0
- pyzzel-0.1.1/tests/test_joins_nodb.py +290 -0
- pyzzel-0.1.1/tests/test_migrate_apply.py +184 -0
- pyzzel-0.1.1/tests/test_migrate_cli.py +114 -0
- pyzzel-0.1.1/tests/test_migrate_compare.py +517 -0
- pyzzel-0.1.1/tests/test_migrate_compare_cli.py +152 -0
- pyzzel-0.1.1/tests/test_migrate_diff.py +76 -0
- pyzzel-0.1.1/tests/test_migrate_generate.py +158 -0
- pyzzel-0.1.1/tests/test_migrate_introspect.py +140 -0
- pyzzel-0.1.1/tests/test_migrate_schema.py +81 -0
- pyzzel-0.1.1/tests/test_models.py +205 -0
- pyzzel-0.1.1/tests/test_query.py +275 -0
- pyzzel-0.1.1/tests/test_relations.py +180 -0
- pyzzel-0.1.1/tests/test_relations_nodb.py +346 -0
- pyzzel-0.1.1/tests/test_select.py +178 -0
- pyzzel-0.1.1/tests/test_sql_builder.py +151 -0
- pyzzel-0.1.1/tests/test_transactions.py +229 -0
- pyzzel-0.1.1/tests/test_types.py +276 -0
- pyzzel-0.1.1/tests/test_types_db.py +216 -0
- pyzzel-0.1.1/tests/test_write.py +205 -0
- pyzzel-0.1.1/tests/test_write_nodb.py +183 -0
pyzzel-0.1.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Himanshu Bokde
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
pyzzel-0.1.1/PKG-INFO
ADDED
pyzzel-0.1.1/README.md
ADDED
|
@@ -0,0 +1,605 @@
|
|
|
1
|
+
# Pyzzel
|
|
2
|
+
|
|
3
|
+
Pyzzel is a lightweight Python ORM for PostgreSQL. It combines an Active Record model interface with explicit queries, short-lived pooled connections, and visible transaction boundaries.
|
|
4
|
+
|
|
5
|
+
The package is under development (version 0.0.1). Its scope is PostgreSQL; it does not support other database systems.
|
|
6
|
+
|
|
7
|
+
## Contents
|
|
8
|
+
|
|
9
|
+
- [Design](#design)
|
|
10
|
+
- [Features](#features)
|
|
11
|
+
- [Installation](#installation)
|
|
12
|
+
- [Quick start](#quick-start)
|
|
13
|
+
- [Connections and configuration](#connections-and-configuration)
|
|
14
|
+
- [Models and columns](#models-and-columns)
|
|
15
|
+
- [CRUD operations](#crud-operations)
|
|
16
|
+
- [Queries](#queries)
|
|
17
|
+
- [Relationships and joins](#relationships-and-joins)
|
|
18
|
+
- [Bulk writes](#bulk-writes)
|
|
19
|
+
- [Transactions and concurrency](#transactions-and-concurrency)
|
|
20
|
+
- [Migrations](#migrations)
|
|
21
|
+
- [Errors](#errors)
|
|
22
|
+
- [Performance notes](#performance-notes)
|
|
23
|
+
- [Limitations](#limitations)
|
|
24
|
+
- [Project structure](#project-structure)
|
|
25
|
+
- [Tests and contribution](#tests-and-contribution)
|
|
26
|
+
- [License](#license)
|
|
27
|
+
|
|
28
|
+
## Design
|
|
29
|
+
|
|
30
|
+
Pyzzel uses model classes and descriptors to define tables and columns. Database work happens when an operation is called; a model instance does not hold a long-lived session. Each standalone operation borrows a connection from the pool and returns it afterward. A transaction explicitly keeps one connection for its block.
|
|
31
|
+
|
|
32
|
+
The library keeps reading explicit:
|
|
33
|
+
|
|
34
|
+
- `Model.get(...)` loads a model object.
|
|
35
|
+
- `Model.select(...)` builds a query that returns lightweight row values.
|
|
36
|
+
- Relationships are loaded only when requested with `.with_(...)`.
|
|
37
|
+
- `.to_sql()` exposes the generated SQL and its parameters without running it.
|
|
38
|
+
|
|
39
|
+
Values are passed separately from SQL using Psycopg parameters. Identifiers and SQL types are validated by Pyzzel's PostgreSQL SQL builder.
|
|
40
|
+
|
|
41
|
+
## Features
|
|
42
|
+
|
|
43
|
+
- Active Record models with `create()`, `get()`, `save()`, and `delete()`.
|
|
44
|
+
- PostgreSQL column types, Python defaults, and trusted server defaults.
|
|
45
|
+
- Change tracking and optimistic concurrency through a managed `version` column.
|
|
46
|
+
- Immutable query construction with conditions, sorting, paging, counting, and a row limit.
|
|
47
|
+
- Foreign keys, explicitly requested relationship loading, and inner or left joins.
|
|
48
|
+
- Atomic `create_many()`, conditional `update_where()`, and `delete_where()`.
|
|
49
|
+
- A Psycopg connection pool and explicit transactions with nested savepoints.
|
|
50
|
+
- Optional schema migrations, migration status, schema drift checks, and snapshot pull.
|
|
51
|
+
|
|
52
|
+
## Installation
|
|
53
|
+
|
|
54
|
+
Pyzzel requires Python 3.10 or newer and a PostgreSQL database. From a checkout of the project, install the package with:
|
|
55
|
+
|
|
56
|
+
```console
|
|
57
|
+
python -m pip install .
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
For development, including the test dependency:
|
|
61
|
+
|
|
62
|
+
```console
|
|
63
|
+
python -m pip install -e ".[dev]"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The runtime dependency is `psycopg[binary,pool]>=3.2`. The `dev` extra installs `pytest`. The project metadata does not specify a minimum PostgreSQL server version.
|
|
67
|
+
|
|
68
|
+
## Quick start
|
|
69
|
+
|
|
70
|
+
Create a `models.py` file in your application directory:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from pyzzel import Base, Boolean, Column, Integer, String
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class User(Base):
|
|
77
|
+
__tablename__ = "users"
|
|
78
|
+
|
|
79
|
+
id = Column(Integer, primary_key=True)
|
|
80
|
+
name = Column(String, nullable=False)
|
|
81
|
+
email = Column(String(255), unique=True)
|
|
82
|
+
age = Column(Integer)
|
|
83
|
+
active = Column(Boolean, default=True)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Generate and apply an initial migration. The `generate` command imports the model module, compares the registered models with the migration snapshot, and writes a numbered SQL file.
|
|
87
|
+
|
|
88
|
+
PowerShell:
|
|
89
|
+
|
|
90
|
+
```powershell
|
|
91
|
+
$env:PYZZEL_DATABASE_URL = "postgresql://user:password@localhost:5432/my_database"
|
|
92
|
+
python -m pyzzel.migrate generate create_users --models models
|
|
93
|
+
python -m pyzzel.migrate apply
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Then use the model from your application:
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
import os
|
|
100
|
+
|
|
101
|
+
from pyzzel import connect, disconnect
|
|
102
|
+
from models import User
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
connect(os.environ["PYZZEL_DATABASE_URL"])
|
|
106
|
+
try:
|
|
107
|
+
user = User.create(name="Amit", email="amit@example.test")
|
|
108
|
+
loaded = User.get(user.id)
|
|
109
|
+
|
|
110
|
+
loaded.name = "Rahul"
|
|
111
|
+
loaded.save()
|
|
112
|
+
|
|
113
|
+
loaded.delete()
|
|
114
|
+
finally:
|
|
115
|
+
disconnect()
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`generate` is offline; `apply` connects to the database. The command line reads `PYZZEL_DATABASE_URL` when `--url` is not supplied. Migration commands are described in [Migrations](#migrations).
|
|
119
|
+
|
|
120
|
+
For a small prototype without migrations, `Base.create_tables()` creates the registered model tables if they do not already exist. It does not alter or drop existing tables.
|
|
121
|
+
|
|
122
|
+
## Connections and configuration
|
|
123
|
+
|
|
124
|
+
Connect once during application startup and disconnect when the application is shutting down:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
import os
|
|
128
|
+
|
|
129
|
+
from pyzzel import connect, disconnect
|
|
130
|
+
|
|
131
|
+
connect(
|
|
132
|
+
os.environ["PYZZEL_DATABASE_URL"],
|
|
133
|
+
min_size=1,
|
|
134
|
+
max_size=10,
|
|
135
|
+
timeout=30.0,
|
|
136
|
+
)
|
|
137
|
+
try:
|
|
138
|
+
# Application database operations
|
|
139
|
+
...
|
|
140
|
+
finally:
|
|
141
|
+
disconnect()
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`connect(url, *, min_size=1, max_size=10, timeout=30.0, check=False, prepare_threshold=None)` first probes the database, then opens a `psycopg_pool.ConnectionPool` with autocommit enabled. Automatic prepared statements are disabled by default because transaction poolers such as Supabase's shared pooler do not support them. Set `prepare_threshold` to an integer only when the server connection mode supports prepared statements. The driver imports are lazy: importing `pyzzel` does not import Psycopg.
|
|
145
|
+
|
|
146
|
+
`create_many()` sends bounded multi-row `INSERT ... RETURNING` statements in one transaction. This avoids Psycopg's pipeline-based `executemany()` path, which shared transaction poolers do not support.
|
|
147
|
+
|
|
148
|
+
- `min_size` and `max_size` configure the pool.
|
|
149
|
+
- `timeout` is used for connection setup and pool waits.
|
|
150
|
+
- `check=True` checks a pooled connection before each operation. The project measurements show an additional database round trip; leave it off unless checking stale connections is important for your environment.
|
|
151
|
+
- Calling `connect()` while already connected raises `AlreadyConnectedError`.
|
|
152
|
+
- `disconnect()` closes the pool and is safe when no pool is open.
|
|
153
|
+
|
|
154
|
+
Pyzzel maintains one process-wide pool, so it currently supports one configured database per process. Database tests use the separate `PYZZEL_TEST_DATABASE_URL` variable and skip when it is unset. Migration CLI commands use `PYZZEL_DATABASE_URL` or accept `--url`.
|
|
155
|
+
|
|
156
|
+
## Models and columns
|
|
157
|
+
|
|
158
|
+
Models inherit from the package's `Base`. Each concrete model must define a unique `__tablename__` and exactly one integer primary key.
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
from pyzzel import Base, Column, Integer, Numeric, String
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
class Product(Base):
|
|
165
|
+
__tablename__ = "products"
|
|
166
|
+
|
|
167
|
+
id = Column(Integer, primary_key=True)
|
|
168
|
+
name = Column(String(120), nullable=False)
|
|
169
|
+
price = Column(Numeric(10, 2), nullable=False)
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
A column accepts a type class or an instance. Supported types are:
|
|
173
|
+
|
|
174
|
+
| Pyzzel type | PostgreSQL type | Python value |
|
|
175
|
+
|---|---|---|
|
|
176
|
+
| `SmallInteger`, `Integer`, `BigInteger` | `SMALLINT`, `INTEGER`, `BIGINT` | `int` |
|
|
177
|
+
| `Float` | `DOUBLE PRECISION` | `float` |
|
|
178
|
+
| `Numeric(precision=None, scale=None)` | `NUMERIC` or `NUMERIC(p,s)` | `decimal.Decimal` |
|
|
179
|
+
| `String(length=None)` | `TEXT` or `VARCHAR(n)` | `str` |
|
|
180
|
+
| `Boolean` | `BOOLEAN` | `bool` |
|
|
181
|
+
| `Date`, `Time` | `DATE`, `TIME` | `datetime.date`, `datetime.time` |
|
|
182
|
+
| `DateTime(timezone=True)` | `TIMESTAMPTZ` or `TIMESTAMP` | `datetime.datetime` |
|
|
183
|
+
| `UUID` | `UUID` | `uuid.UUID` |
|
|
184
|
+
| `JSON` | `JSONB` | JSON-compatible values |
|
|
185
|
+
| `LargeBinary` | `BYTEA` | `bytes` |
|
|
186
|
+
|
|
187
|
+
Common column options:
|
|
188
|
+
|
|
189
|
+
- `primary_key=True` marks the generated integer key.
|
|
190
|
+
- `nullable=False` creates a `NOT NULL` column.
|
|
191
|
+
- `unique=True` creates a unique constraint.
|
|
192
|
+
- `default=value` applies a Python-side default when a new object is constructed. Use a factory such as `default=list` for mutable values.
|
|
193
|
+
- `server_default="now()"` includes trusted SQL expression text in the table definition. It is written into DDL, so only use an expression you control.
|
|
194
|
+
- `foreign_key="users.id"` declares a PostgreSQL foreign key. See [Relationships and joins](#relationships-and-joins).
|
|
195
|
+
|
|
196
|
+
The hidden `version` column is created for each model table and managed by Pyzzel. It is used for optimistic concurrency; do not set it yourself. It is not included in `select()`'s default selected fields.
|
|
197
|
+
|
|
198
|
+
Shared model fields can live in an abstract base:
|
|
199
|
+
|
|
200
|
+
```python
|
|
201
|
+
from pyzzel import Base, Column, DateTime, Integer, String
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
class Timestamped(Base):
|
|
205
|
+
__abstract__ = True
|
|
206
|
+
created_at = Column(DateTime, server_default="now()")
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
class User(Timestamped):
|
|
210
|
+
__tablename__ = "users"
|
|
211
|
+
|
|
212
|
+
id = Column(Integer, primary_key=True)
|
|
213
|
+
name = Column(String, nullable=False)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Pyzzel clones inherited column descriptors for concrete models. A model cannot inherit from another concrete model.
|
|
217
|
+
|
|
218
|
+
### Defaults and change tracking
|
|
219
|
+
|
|
220
|
+
Python defaults are applied when creating model instances (and in `create_many()`). A callable default is called for each new object. Server defaults are applied by PostgreSQL; they are not Python defaults.
|
|
221
|
+
|
|
222
|
+
Assigning a different field value records that field for the next `save()`. Assigning the original value back clears the pending change. In-place mutation of JSON values is not detected; assign a new value instead:
|
|
223
|
+
|
|
224
|
+
```python
|
|
225
|
+
user.profile = {**user.profile, "theme": "dark"}
|
|
226
|
+
user.save()
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Naive datetimes use the database session's time zone. Prefer timezone-aware datetimes when using `DateTime(timezone=True)`.
|
|
230
|
+
|
|
231
|
+
## CRUD operations
|
|
232
|
+
|
|
233
|
+
### Create
|
|
234
|
+
|
|
235
|
+
`Model.create(**values)` constructs and saves an object, then returns that object. The database generates the primary key and initial version.
|
|
236
|
+
|
|
237
|
+
```python
|
|
238
|
+
user = User.create(name="Amit", email="amit@example.test")
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
You can also create an unsaved instance and call `save()`. Do not set the primary key on a new object.
|
|
242
|
+
|
|
243
|
+
### Get
|
|
244
|
+
|
|
245
|
+
`Model.get(primary_key)` returns the matching model instance or `None`. It also accepts one or more conditions, combined with AND, and returns the first matching object or `None`:
|
|
246
|
+
|
|
247
|
+
```python
|
|
248
|
+
user = User.get(12)
|
|
249
|
+
user = User.get(User.email == "amit@example.test")
|
|
250
|
+
user = User.get(User.active == True, User.age >= 18)
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### Save
|
|
254
|
+
|
|
255
|
+
Calling `save()` on a new instance inserts it and returns the same object. Calling it on a saved object updates only changed columns, increments the version, and returns the object. If there are no tracked changes, it performs no query.
|
|
256
|
+
|
|
257
|
+
### Delete
|
|
258
|
+
|
|
259
|
+
`user.delete()` deletes a saved row and returns `None`. Calling it on an unsaved instance raises `PyzzelError`.
|
|
260
|
+
|
|
261
|
+
### Raw SQL
|
|
262
|
+
|
|
263
|
+
`Base.execute(sql, params=None)` is an escape hatch for SQL that is not expressed by the ORM. It returns rows as tuples, or an empty list for a statement without result rows. Keep values in the parameter sequence:
|
|
264
|
+
|
|
265
|
+
```python
|
|
266
|
+
rows = Base.execute(
|
|
267
|
+
'SELECT "id", "name" FROM "users" WHERE "email" = %s',
|
|
268
|
+
("amit@example.test",),
|
|
269
|
+
)
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Use PostgreSQL placeholders (`%s`) and never interpolate user-provided values into SQL text.
|
|
273
|
+
|
|
274
|
+
## Queries
|
|
275
|
+
|
|
276
|
+
`Model.select(*columns)` returns an immutable query builder. It does not run SQL until you call `.all()`, `.first()`, or `.count()`.
|
|
277
|
+
|
|
278
|
+
- With no columns, it selects all user-defined columns (not the hidden version column).
|
|
279
|
+
- With selected columns, each returned row exposes values by field name and by index.
|
|
280
|
+
- Query methods return a new query, so you can reuse an earlier query safely.
|
|
281
|
+
|
|
282
|
+
```python
|
|
283
|
+
adults = (
|
|
284
|
+
User.select(User.name, User.age)
|
|
285
|
+
.where(User.age >= 18, User.active == True)
|
|
286
|
+
.order_by(User.name)
|
|
287
|
+
.limit(50)
|
|
288
|
+
.offset(0)
|
|
289
|
+
.all()
|
|
290
|
+
)
|
|
291
|
+
|
|
292
|
+
for row in adults:
|
|
293
|
+
print(row.name, row[1])
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Available query methods:
|
|
297
|
+
|
|
298
|
+
| Method | Behavior |
|
|
299
|
+
|---|---|
|
|
300
|
+
| `.where(*conditions)` | Adds conditions; multiple and chained conditions are combined with AND. |
|
|
301
|
+
| `.order_by(*columns)` | Adds ascending order; pass `.asc()` or `.desc()` to choose direction. |
|
|
302
|
+
| `.limit(n)`, `.offset(n)` | Set non-negative integer paging values. |
|
|
303
|
+
| `.all()` | Executes and returns a list of row values. |
|
|
304
|
+
| `.first()` | Returns the first row or `None`; applies a limit of one. |
|
|
305
|
+
| `.count()` | Executes `COUNT(*)` for the query's conditions and joins. `distinct().count()` is unsupported. |
|
|
306
|
+
| `.distinct()` | Requests distinct result rows. |
|
|
307
|
+
| `.unlimited()` | Disables the automatic row guard for `.all()`. |
|
|
308
|
+
| `.to_sql()` | Returns a `Statement` with `.sql` and `.params`; does not execute it. |
|
|
309
|
+
|
|
310
|
+
Use `Base.max_rows` or `Model.max_rows` to set the default maximum returned by `.all()`. The default is 10,000. When no explicit limit is set, Pyzzel fetches at most one extra row to detect an overflow and raises `TooManyRowsError`. An explicit `.limit()` or `.unlimited()` disables that automatic guard.
|
|
311
|
+
|
|
312
|
+
### Conditions
|
|
313
|
+
|
|
314
|
+
Column comparisons create condition objects:
|
|
315
|
+
|
|
316
|
+
```python
|
|
317
|
+
from pyzzel import and_, or_
|
|
318
|
+
|
|
319
|
+
active_adults = User.select().where(
|
|
320
|
+
(User.active == True) & (User.age >= 18)
|
|
321
|
+
).all()
|
|
322
|
+
|
|
323
|
+
matches = User.select().where(
|
|
324
|
+
or_(User.name.ilike("a%"), User.name.ilike("r%"))
|
|
325
|
+
).all()
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
Supported comparisons are `==`, `!=`, `<`, `<=`, `>`, and `>=`. Compare with `None` using `== None` or `!= None`; these become `IS NULL` and `IS NOT NULL`. Other condition helpers are:
|
|
329
|
+
|
|
330
|
+
- `column.in_(values)` accepts a list, tuple, set, or frozenset and uses one PostgreSQL array parameter. An empty collection matches no rows.
|
|
331
|
+
- `column.like(pattern)` and `column.ilike(pattern)`.
|
|
332
|
+
- `column.is_null()` and `column.is_not_null()`.
|
|
333
|
+
- `&`, `|`, and `~`, or the `and_(...)` and `or_(...)` helpers.
|
|
334
|
+
|
|
335
|
+
Use parentheses around conditions combined with `&` and `|`. Python's `and`, `or`, `not`, and chained comparisons are not supported for constructing conditions.
|
|
336
|
+
|
|
337
|
+
## Relationships and joins
|
|
338
|
+
|
|
339
|
+
Declare a foreign key with a table and column name:
|
|
340
|
+
|
|
341
|
+
```python
|
|
342
|
+
class Order(Base):
|
|
343
|
+
__tablename__ = "orders"
|
|
344
|
+
|
|
345
|
+
id = Column(Integer, primary_key=True)
|
|
346
|
+
user_id = Column(
|
|
347
|
+
Integer,
|
|
348
|
+
nullable=False,
|
|
349
|
+
foreign_key="users.id",
|
|
350
|
+
on_delete="CASCADE",
|
|
351
|
+
)
|
|
352
|
+
total = Column(Numeric(10, 2), nullable=False)
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
Supported `on_delete` values are `NO ACTION` (the default), `RESTRICT`, `CASCADE`, and `SET NULL`. `SET NULL` requires a nullable child column. Foreign-key columns are indexed by default; set `index=False` to disable that index, or `index=True` to index another non-primary, non-unique column.
|
|
356
|
+
|
|
357
|
+
### Explicit relationship loading
|
|
358
|
+
|
|
359
|
+
Use `.with_(...)` to load one level of related rows as part of a query result. The selected row includes the named relation field:
|
|
360
|
+
|
|
361
|
+
```python
|
|
362
|
+
users = User.select().with_(orders=Order.user_id).all()
|
|
363
|
+
for user in users:
|
|
364
|
+
print(user.name, user.orders) # list of Order rows
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
When querying the child model, the relation is a parent row or `None`:
|
|
368
|
+
|
|
369
|
+
```python
|
|
370
|
+
orders = Order.select().with_(user=Order.user_id).all()
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
The key column used for the relationship must be selected. Each requested relation runs an additional query; related rows are ordered by primary key and their model's row guard applies. Relationship loading is one level only and never happens implicitly. Use `Base.transaction()` if the main query and relation queries need one consistent database view. `.to_sql()` shows only the main query.
|
|
374
|
+
|
|
375
|
+
### Joins
|
|
376
|
+
|
|
377
|
+
Joins return flat rows. A parent appears once per matching child row. The join condition is inferred from declared foreign keys:
|
|
378
|
+
|
|
379
|
+
```python
|
|
380
|
+
rows = (
|
|
381
|
+
User.select(User.name, Order.total)
|
|
382
|
+
.join(Order)
|
|
383
|
+
.where(Order.total > 100)
|
|
384
|
+
.all()
|
|
385
|
+
)
|
|
386
|
+
|
|
387
|
+
users_with_or_without_orders = User.select(User.name, Order.total).left_join(Order).all()
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
Use `.left_join(Model)` to preserve rows without a match; joined values are `None` when no row matches. If multiple foreign keys link the same models, choose one with `on=` and pass the linking foreign-key column:
|
|
391
|
+
|
|
392
|
+
```python
|
|
393
|
+
messages = Message.select(
|
|
394
|
+
Message.body,
|
|
395
|
+
User.name.label("sender_name"),
|
|
396
|
+
).join(User, on=Message.sender_id).all()
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
Use `.label("...")` when selected columns would otherwise have duplicate result field names. `.distinct()` requests distinct rows. Joins cannot be combined with `.with_(...)`.
|
|
400
|
+
|
|
401
|
+
## Bulk writes
|
|
402
|
+
|
|
403
|
+
`create_many(rows)` accepts dictionaries with the same column keys, applies Python defaults, inserts the rows in one transaction, and returns generated primary keys in input order:
|
|
404
|
+
|
|
405
|
+
```python
|
|
406
|
+
ids = User.create_many([
|
|
407
|
+
{"name": "Amit", "email": "amit@example.test"},
|
|
408
|
+
{"name": "Rahul", "email": "rahul@example.test"},
|
|
409
|
+
])
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
An empty list returns an empty list. If an insert fails, the transaction rolls back. All rows must have the same keys; primary key and version values cannot be supplied.
|
|
413
|
+
|
|
414
|
+
Conditional writes issue one SQL statement and require at least one condition:
|
|
415
|
+
|
|
416
|
+
```python
|
|
417
|
+
updated = User.update_where(User.age < 18, active=False)
|
|
418
|
+
deleted = User.delete_where(User.active == False)
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
Both return the affected row count. `update_where()` also increments the version of each updated row. To explicitly target all rows, pass a condition such as `User.id.is_not_null()`.
|
|
422
|
+
|
|
423
|
+
## Transactions and concurrency
|
|
424
|
+
|
|
425
|
+
Each standalone statement runs in autocommit mode. Use `Base.transaction()` when multiple operations must succeed or fail together:
|
|
426
|
+
|
|
427
|
+
```python
|
|
428
|
+
with Base.transaction():
|
|
429
|
+
debit_account.balance -= 10
|
|
430
|
+
debit_account.save()
|
|
431
|
+
credit_account.balance += 10
|
|
432
|
+
credit_account.save()
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
All operations inside the block reuse one connection. An exception escaping the outer block rolls back the work. A nested transaction block uses a PostgreSQL savepoint, so code may catch an inner error and continue the outer transaction.
|
|
436
|
+
|
|
437
|
+
Every model table has a managed integer `version` column. Updates and deletes match both the primary key and the version loaded by the object. A successful update increments the version. If another writer changed or removed the row, Pyzzel raises `VersionConflict` or `NotFound` respectively. This is optimistic concurrency control: it detects conflicting writes when they occur rather than locking rows in advance.
|
|
438
|
+
|
|
439
|
+
## Migrations
|
|
440
|
+
|
|
441
|
+
Pyzzel's optional `pyzzel.migrate` module generates and applies numbered SQL migration files. It is separate from the core package and is not loaded by `import pyzzel`.
|
|
442
|
+
|
|
443
|
+
### Typical workflow
|
|
444
|
+
|
|
445
|
+
1. Import your model modules and generate a migration against the current `snapshot.json`:
|
|
446
|
+
|
|
447
|
+
```console
|
|
448
|
+
python -m pyzzel.migrate generate add_orders --models models
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
2. Review the generated SQL and snapshot changes. The command does not connect to the database.
|
|
452
|
+
3. Apply pending migrations:
|
|
453
|
+
|
|
454
|
+
```console
|
|
455
|
+
python -m pyzzel.migrate apply --url "$PYZZEL_DATABASE_URL"
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
4. Check that the models, migration files, and database agree:
|
|
459
|
+
|
|
460
|
+
```console
|
|
461
|
+
python -m pyzzel.migrate check --models models --url "$PYZZEL_DATABASE_URL"
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
On PowerShell, use `$env:PYZZEL_DATABASE_URL` to set the environment variable. The CLI accepts `--url` for database commands or reads `PYZZEL_DATABASE_URL`. Import model modules using repeatable `--models module.path` options. `--dir` selects the migration directory (default `migrations`).
|
|
465
|
+
|
|
466
|
+
### Commands
|
|
467
|
+
|
|
468
|
+
| Command | Purpose |
|
|
469
|
+
|---|---|
|
|
470
|
+
| `generate NAME` | Diff registered models against `snapshot.json`; write a numbered SQL file and update the snapshot. If there are no changes, print `No changes.` |
|
|
471
|
+
| `create NAME` | Create an empty numbered SQL file for hand-written migration SQL. |
|
|
472
|
+
| `apply` | Apply pending files in order, recording each in the history table. |
|
|
473
|
+
| `status` | List migration files as `pending`, `applied`, or `edited`, and applied entries missing from disk as `missing`. |
|
|
474
|
+
| `check` | Compare models, migration files, and database drift. Requires at least one `--models` module. |
|
|
475
|
+
| `pull` | Compare the live database schema with the snapshot; `--write` replaces the snapshot with the live schema. Does not modify the database. |
|
|
476
|
+
|
|
477
|
+
Database commands use `pyzzel_migrations` as the default history table; change it with `--history-table`. `check` and `pull` accept repeatable `--ignore TABLE` options. `apply` supports `--dry-run` to list pending files and `--allow-destructive` to permit migrations marked destructive.
|
|
478
|
+
|
|
479
|
+
Generated migrations can contain a `-- pyzzel:destructive` marker for operations such as dropping a table or column or changing a type. Pyzzel refuses to apply pending destructive migration files unless explicitly allowed. Review every generated migration before applying it. Each file and its history row run in a transaction; the migrator takes a transaction-scoped PostgreSQL advisory lock, which works with transaction poolers, and verifies SHA-256 checksums to detect edited applied files.
|
|
480
|
+
|
|
481
|
+
### Python API
|
|
482
|
+
|
|
483
|
+
The module exports `generate`, `create`, `apply`, `status`, `check`, and `pull`. The first two are offline. Database operations require an active Pyzzel connection; call `connect()` before invoking them. For example:
|
|
484
|
+
|
|
485
|
+
```python
|
|
486
|
+
import os
|
|
487
|
+
|
|
488
|
+
from pyzzel import connect, disconnect
|
|
489
|
+
from pyzzel.migrate import apply, status
|
|
490
|
+
|
|
491
|
+
connect(os.environ["PYZZEL_DATABASE_URL"])
|
|
492
|
+
try:
|
|
493
|
+
print(status("migrations"))
|
|
494
|
+
apply("migrations")
|
|
495
|
+
finally:
|
|
496
|
+
disconnect()
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
### Migration boundaries
|
|
500
|
+
|
|
501
|
+
There are no down migrations; make a new migration to move the schema forward. Renames are not detected automatically and may appear as a drop plus an add, so edit the generated SQL to use PostgreSQL's rename syntax when appropriate.
|
|
502
|
+
|
|
503
|
+
Schema comparison reads selected metadata from PostgreSQL's catalogs. It handles columns and types, nullability, defaults, primary keys, single-column unique constraints and foreign keys, and simple single-column indexes. Composite constraints, check constraints, triggers, views, sequences, arrays, enums, partial or expression indexes, and other unsupported objects are not fully compared; some produce warnings. Default expressions are normalized best-effort, so equivalent but unusual expressions may still appear different. If migration files are pending, edited, or missing, `check` reports those issues and does not check database drift.
|
|
504
|
+
|
|
505
|
+
## Errors
|
|
506
|
+
|
|
507
|
+
Pyzzel's custom errors are in `pyzzel.errors`:
|
|
508
|
+
|
|
509
|
+
- `PyzzelError`: base class for library errors.
|
|
510
|
+
- `ModelDefinitionError`: invalid model or column definition.
|
|
511
|
+
- `NotConnectedError`, `AlreadyConnectedError`: connection lifecycle errors.
|
|
512
|
+
- `NotFound`: the row was removed before an optimistic update or delete.
|
|
513
|
+
- `VersionConflict`: the row was changed by another writer.
|
|
514
|
+
- `QueryError`: invalid query or write operation.
|
|
515
|
+
- `TooManyRowsError`: a query exceeds the automatic row limit; this is a subclass of `QueryError`.
|
|
516
|
+
- `MigrationError`: migration processing error.
|
|
517
|
+
|
|
518
|
+
PostgreSQL errors, including constraint violations, are Psycopg errors and are not wrapped as Pyzzel errors. Catch the specific exception you expect:
|
|
519
|
+
|
|
520
|
+
```python
|
|
521
|
+
from pyzzel.errors import NotFound, VersionConflict
|
|
522
|
+
|
|
523
|
+
try:
|
|
524
|
+
user.save()
|
|
525
|
+
except VersionConflict:
|
|
526
|
+
# Reload and reconcile the latest row before retrying.
|
|
527
|
+
user = User.get(user.id)
|
|
528
|
+
except NotFound:
|
|
529
|
+
# The row no longer exists.
|
|
530
|
+
user = None
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
## Performance notes
|
|
534
|
+
|
|
535
|
+
The project includes a cross-adapter PostgreSQL benchmark for Pyzzel, SQLAlchemy, Drizzle, Psycopg, and Node.js `pg`. The latest Phase 7C runs cover normalized and idiomatic modes, with five rounds and 100 measured samples per adapter for bulk inserts of 100, 1,000, and 5,000 rows. The per-mode reports are in [`comparisons/PHASE7C_NORMALIZED_COMPARISON.md`](comparisons/PHASE7C_NORMALIZED_COMPARISON.md) and [`comparisons/PHASE7C_IDIOMATIC_COMPARISON.md`](comparisons/PHASE7C_IDIOMATIC_COMPARISON.md); raw round archives are preserved under `comparisons/results/`.
|
|
536
|
+
|
|
537
|
+
These bulk comparisons are descriptive, not an overall adapter ranking. The broader Phase 7C campaign remains incomplete because the database name used by the runs differs from the frozen configuration (`pyzzle_test` versus `pyzzel_test`). See [`comparisons/PHASE7C_STATISTICAL_REPORT.md`](comparisons/PHASE7C_STATISTICAL_REPORT.md) for validation status and limitations. Results are workload- and machine-dependent; use comparisons from the same configuration.
|
|
538
|
+
|
|
539
|
+
Earlier design measurements recorded:
|
|
540
|
+
|
|
541
|
+
- Single operations were measured within roughly 3–30% of raw Psycopg across the recorded runs.
|
|
542
|
+
- Query construction measured about 19–46 microseconds per composed query across several later sessions. The notes attribute much of the spread to machine variability; prepared-query caching was not considered necessary.
|
|
543
|
+
- A join loading 100 parents with three children each measured about twice as fast as explicit `.with_()` loading in the recorded comparisons. These are different result shapes and query strategies.
|
|
544
|
+
- For 1,000 inserts, `create_many()` measured about 6,300–12,800 rows/second, while plain Psycopg `executemany` measured about 13,900–19,900 rows/second. `create_many()` returns generated IDs and is atomic; the raw comparison does not provide the same ORM behavior.
|
|
545
|
+
- The measurements identified transaction commits and database round trips as larger costs than SQL string construction. Group related writes in `Base.transaction()` or use `create_many()` for same-shape inserts.
|
|
546
|
+
|
|
547
|
+
These are project measurements, not a comparative benchmark against SQLAlchemy, Django, Peewee, or other ORMs.
|
|
548
|
+
|
|
549
|
+
## Limitations
|
|
550
|
+
|
|
551
|
+
- PostgreSQL only; one configured database pool per process.
|
|
552
|
+
- No automatic lazy loading. Relationships are explicitly loaded and only one level deep.
|
|
553
|
+
- Joins support inner and left joins, but not aliases, self-joins, right/full joins, arbitrary `ON` expressions, or combining joins with `.with_(...)`.
|
|
554
|
+
- No `GROUP BY`; `.count()` is the only aggregate.
|
|
555
|
+
- No array, enum, or interval column types; primary keys must use an integer type.
|
|
556
|
+
- In-place JSON mutation is not tracked; assign a replacement value.
|
|
557
|
+
- `update_where()` accepts values, not SQL expressions. `create_many()` requires identical keys in every row.
|
|
558
|
+
- Migration tooling has no down migrations or automatic rename detection and compares only the schema objects listed above.
|
|
559
|
+
- The optional connection check adds a round trip to operations. With it off, the first use of a stale connection after a database restart can fail.
|
|
560
|
+
- Raw database errors are surfaced as Psycopg errors.
|
|
561
|
+
|
|
562
|
+
## Project structure
|
|
563
|
+
|
|
564
|
+
```text
|
|
565
|
+
src/pyzzel/
|
|
566
|
+
├── __init__.py # Public exports
|
|
567
|
+
├── errors.py # Pyzzel exception types
|
|
568
|
+
├── pool.py # Connection pool and transaction context
|
|
569
|
+
├── core/
|
|
570
|
+
│ ├── base.py # Base model and Active Record operations
|
|
571
|
+
│ ├── column.py # Column descriptors and model field definitions
|
|
572
|
+
│ ├── query.py # Immutable query object and row conversion
|
|
573
|
+
│ └── types.py # PostgreSQL column types
|
|
574
|
+
├── sql/
|
|
575
|
+
│ ├── builder.py # PostgreSQL SQL statement builders
|
|
576
|
+
│ └── conditions.py # Conditions and ordering values
|
|
577
|
+
└── migrate/ # Optional migration and schema comparison tools
|
|
578
|
+
├── __init__.py
|
|
579
|
+
├── __main__.py
|
|
580
|
+
├── apply.py
|
|
581
|
+
├── compare.py
|
|
582
|
+
├── diff.py
|
|
583
|
+
├── introspect.py
|
|
584
|
+
├── schema.py
|
|
585
|
+
└── sqlgen.py
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
The migration package is optional at import time; `import pyzzel` does not import it. The `scripts/` directory contains local measurement and demo scripts and is not included in the installed package.
|
|
589
|
+
|
|
590
|
+
## Tests and contribution
|
|
591
|
+
|
|
592
|
+
Run the test suite from the project checkout:
|
|
593
|
+
|
|
594
|
+
```console
|
|
595
|
+
python -m pytest -q
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
Tests requiring PostgreSQL read `PYZZEL_TEST_DATABASE_URL` and are skipped if it is unset. Use a dedicated disposable test database.
|
|
599
|
+
|
|
600
|
+
A separate contribution process is not documented in the repository yet.
|
|
601
|
+
|
|
602
|
+
## License
|
|
603
|
+
|
|
604
|
+
Pyzzel is licensed under the [MIT License](LICENSE).
|
|
605
|
+
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "Pyzzel"
|
|
7
|
+
version = "0.1.1"
|
|
8
|
+
requires-python = ">=3.10"
|
|
9
|
+
dependencies = ["psycopg[binary,pool]>=3.2"]
|
|
10
|
+
|
|
11
|
+
[project.optional-dependencies]
|
|
12
|
+
dev = ["pytest"]
|
|
13
|
+
|
|
14
|
+
[tool.setuptools]
|
|
15
|
+
package-dir = {"" = "src"}
|
|
16
|
+
|
|
17
|
+
[tool.setuptools.packages.find]
|
|
18
|
+
where = ["src"]
|
|
19
|
+
|
|
20
|
+
[tool.pytest.ini_options]
|
|
21
|
+
testpaths = ["tests"]
|
|
22
|
+
pythonpath = ["src"]
|
pyzzel-0.1.1/setup.cfg
ADDED