adorm 0.0.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.
Files changed (65) hide show
  1. adorm-0.0.1/LICENSE +21 -0
  2. adorm-0.0.1/PKG-INFO +128 -0
  3. adorm-0.0.1/README.md +94 -0
  4. adorm-0.0.1/adorm/__init__.py +200 -0
  5. adorm-0.0.1/adorm/__main__.py +8 -0
  6. adorm-0.0.1/adorm/checks.py +171 -0
  7. adorm-0.0.1/adorm/cli.py +232 -0
  8. adorm-0.0.1/adorm/codec.py +721 -0
  9. adorm-0.0.1/adorm/codegen/__init__.py +52 -0
  10. adorm-0.0.1/adorm/codegen/django.py +962 -0
  11. adorm-0.0.1/adorm/codegen/files.py +137 -0
  12. adorm-0.0.1/adorm/codegen/render.py +580 -0
  13. adorm-0.0.1/adorm/codegen/spec.py +513 -0
  14. adorm-0.0.1/adorm/contrib/__init__.py +1 -0
  15. adorm-0.0.1/adorm/contrib/django/__init__.py +20 -0
  16. adorm-0.0.1/adorm/contrib/django/apps.py +36 -0
  17. adorm-0.0.1/adorm/contrib/django/config.py +135 -0
  18. adorm-0.0.1/adorm/drivers/__init__.py +41 -0
  19. adorm-0.0.1/adorm/drivers/asyncpg/__init__.py +32 -0
  20. adorm-0.0.1/adorm/drivers/asyncpg/compiler.py +543 -0
  21. adorm-0.0.1/adorm/drivers/asyncpg/driver.py +725 -0
  22. adorm-0.0.1/adorm/drivers/asyncpg/writes.py +1158 -0
  23. adorm-0.0.1/adorm/drivers/base.py +1371 -0
  24. adorm-0.0.1/adorm/drivers/django/__init__.py +47 -0
  25. adorm-0.0.1/adorm/drivers/django/driver.py +1222 -0
  26. adorm-0.0.1/adorm/drivers/django/schema.py +114 -0
  27. adorm-0.0.1/adorm/drivers/django/translation.py +1205 -0
  28. adorm-0.0.1/adorm/drivers/django/vendors.py +759 -0
  29. adorm-0.0.1/adorm/drivers/postgresql.py +283 -0
  30. adorm-0.0.1/adorm/drivers/sql.py +138 -0
  31. adorm-0.0.1/adorm/events.py +618 -0
  32. adorm-0.0.1/adorm/exceptions.py +515 -0
  33. adorm-0.0.1/adorm/executor/__init__.py +80 -0
  34. adorm-0.0.1/adorm/executor/debug.py +30 -0
  35. adorm-0.0.1/adorm/executor/listen.py +245 -0
  36. adorm-0.0.1/adorm/executor/options.py +333 -0
  37. adorm-0.0.1/adorm/executor/pool.py +968 -0
  38. adorm-0.0.1/adorm/executor/sessions.py +223 -0
  39. adorm-0.0.1/adorm/executor/slot.py +1028 -0
  40. adorm-0.0.1/adorm/executor/transactions.py +716 -0
  41. adorm-0.0.1/adorm/executor/turns.py +342 -0
  42. adorm-0.0.1/adorm/models/__init__.py +60 -0
  43. adorm-0.0.1/adorm/models/base.py +572 -0
  44. adorm-0.0.1/adorm/models/contenttypes.py +290 -0
  45. adorm-0.0.1/adorm/models/inheritance.py +82 -0
  46. adorm-0.0.1/adorm/models/managers.py +587 -0
  47. adorm-0.0.1/adorm/models/meta.py +55 -0
  48. adorm-0.0.1/adorm/models/prefetch.py +514 -0
  49. adorm-0.0.1/adorm/models/registry.py +119 -0
  50. adorm-0.0.1/adorm/models/relations.py +534 -0
  51. adorm-0.0.1/adorm/operations.py +1207 -0
  52. adorm-0.0.1/adorm/porting.py +67 -0
  53. adorm-0.0.1/adorm/py.typed +0 -0
  54. adorm-0.0.1/adorm/query/__init__.py +149 -0
  55. adorm-0.0.1/adorm/query/expressions.py +985 -0
  56. adorm-0.0.1/adorm/query/lookups.py +630 -0
  57. adorm-0.0.1/adorm/query/query.py +771 -0
  58. adorm-0.0.1/adorm/query/queryset.py +636 -0
  59. adorm-0.0.1/adorm/schema.py +142 -0
  60. adorm-0.0.1/adorm/settings.py +517 -0
  61. adorm-0.0.1/adorm/testing/__init__.py +10 -0
  62. adorm-0.0.1/adorm/testing/django.py +867 -0
  63. adorm-0.0.1/adorm/testing/waits.py +210 -0
  64. adorm-0.0.1/pyproject.toml +166 -0
  65. adorm-0.0.1/pyproject.toml.orig +137 -0
adorm-0.0.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jure Erznožnik
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.
adorm-0.0.1/PKG-INFO ADDED
@@ -0,0 +1,128 @@
1
+ Metadata-Version: 2.4
2
+ Name: adorm
3
+ Version: 0.0.1
4
+ Summary: Asynchronous database ORM: one async query and model API executed by pluggable drivers.
5
+ Keywords: orm,async,asyncio,django,postgresql,database
6
+ Author: Jure Erznožnik
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 2 - Pre-Alpha
10
+ Classifier: Framework :: AsyncIO
11
+ Classifier: Framework :: Django
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Database
19
+ Classifier: Typing :: Typed
20
+ Requires-Dist: pydantic>=2.11
21
+ Requires-Dist: asgiref>=3.6,<4 ; extra == 'asyncpg'
22
+ Requires-Dist: asyncpg>=0.30 ; extra == 'asyncpg'
23
+ Requires-Dist: django>=5.2 ; extra == 'asyncpg'
24
+ Requires-Dist: psycopg>=3.2 ; extra == 'asyncpg'
25
+ Requires-Dist: asgiref>=3.6,<4 ; extra == 'django'
26
+ Requires-Dist: django>=5.2 ; extra == 'django'
27
+ Requires-Python: >=3.11
28
+ Project-URL: Homepage, https://github.com/velis74/adorm
29
+ Project-URL: Repository, https://github.com/velis74/adorm
30
+ Project-URL: Issues, https://github.com/velis74/adorm/issues
31
+ Provides-Extra: asyncpg
32
+ Provides-Extra: django
33
+ Description-Content-Type: text/markdown
34
+
35
+ # <img src="adorm-icon.svg" alt="" style="width:2.5em; height: 2.5em; vertical-align: middle"> adorm
36
+
37
+ adorm (asynchronous database ORM, pronounced "adore") is an asynchronous ORM for Python. Applications build
38
+ queries and model operations with adorm's API; a driver executes them natively on PostgreSQL (asyncpg) or through
39
+ an existing ORM (Django). The API is modelled on the Django ORM.
40
+
41
+ The package is pre-release; the API reference on the documentation site lists what it provides.
42
+
43
+ ## Requirements
44
+
45
+ - Python 3.11 or newer
46
+ - PostgreSQL for the test suite
47
+ - the conformance run on SQLite needs no database server (Python's `sqlite3`)
48
+
49
+ ## Development
50
+
51
+ The project uses [uv](https://docs.astral.sh/uv/).
52
+
53
+ ```bash
54
+ uv sync
55
+ uv run ruff check .
56
+ uv run ruff format --check .
57
+ uv run pytest
58
+ ```
59
+
60
+ The tests read the test database URL from `ADORM_TEST_DATABASE_URL` (default
61
+ `postgres://postgres@127.0.0.1:5432/adorm_test`). On that server they create and drop the database it names
62
+ (`<name>`: `ADORM_TEST_DATABASE_NAME` when set, `adorm_test` when the URL names `postgres` or none) and the databases
63
+ `<name>_demo`, `<name>_demo_owner`, `<name>_limited`, `<name>_parallel` and `<name>_parallel_<n>` (the clones of
64
+ `manage.py test --parallel`). Other databases and the server's roles are left untouched; runs with different names
65
+ on one server leave each other's databases alone. A run that leaves any of these databases, or a role named
66
+ `<name>_…`, on the server fails. Run the tests as a dedicated user with `CREATEDB`. Under a
67
+ superuser the test of the pool's refusal handling is skipped, because a database's connection limit does not apply to
68
+ a superuser, and so are the tests of the demo, which refuses a superuser:
69
+
70
+ ```sql
71
+ CREATE ROLE adorm LOGIN CREATEDB PASSWORD '...';
72
+ ```
73
+
74
+ `ADORM_TEST_CREATE_ROLES=1` also runs the tests of the `role` connection option. They create and drop the roles
75
+ `<name>_login`, `<name>_alice` and `<name>_bob` and need `CREATEROLE`. Roles belong to the whole server and
76
+ outlive the test databases: set the variable only on a server dedicated to the tests. CI runs the suite with
77
+ `CREATEDB` only, then grants `CREATEROLE` and runs these tests separately.
78
+
79
+ The demo reads its database URL from `ADORM_DEMO_DATABASE_URL`. Both variables can be set in `.env` in the repository
80
+ root (ignored by git; `.env.example` lists them). Variables set in the environment take precedence.
81
+
82
+ ```bash
83
+ cp .env.example .env # then fill in the user and password
84
+ uv run pytest
85
+ ```
86
+
87
+ The conformance suite also runs the Django driver on SQLite, in a database file in a temporary directory, without
88
+ PostgreSQL:
89
+
90
+ ```bash
91
+ uv run pytest --ds=tests.djangoproject.settings_sqlite tests/conformance
92
+ ```
93
+
94
+ ## Demo
95
+
96
+ `demo.py` runs the demo application, a library on PostgreSQL: every example and concurrency scenario on every
97
+ available driver, with the adorm code, the SQL each driver sent, the result and the time side by side.
98
+
99
+ [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/velis74/adorm?quickstart=1)
100
+
101
+ The codespace runs the demo with a PostgreSQL server of its own.
102
+
103
+ - `demo/backend`: a Django project with the app `library`;
104
+ - `demo/models`: the adorm models generated from it;
105
+ - `demo/api`: a FastAPI app running the examples and scenarios;
106
+ - `demo/frontend`: the Vue frontend; `demo/e2e`: its Playwright tests.
107
+
108
+ It creates (owned by the user of `ADORM_DEMO_DATABASE_URL`, which must not be a superuser), migrates and seeds the
109
+ demo database, then serves the API and the Vite dev server on <http://127.0.0.1:5173/>.
110
+
111
+ ```bash
112
+ npm install
113
+ uv run python demo.py
114
+ npm run test:e2e
115
+ ```
116
+
117
+ ## Documentation
118
+
119
+ The documentation site is in `docs/` (VitePress, published on docs.velis.si):
120
+
121
+ ```bash
122
+ npm install
123
+ npm run docs:dev
124
+ ```
125
+
126
+ ## Licence
127
+
128
+ MIT, see [LICENSE](LICENSE).
adorm-0.0.1/README.md ADDED
@@ -0,0 +1,94 @@
1
+ # <img src="adorm-icon.svg" alt="" style="width:2.5em; height: 2.5em; vertical-align: middle"> adorm
2
+
3
+ adorm (asynchronous database ORM, pronounced "adore") is an asynchronous ORM for Python. Applications build
4
+ queries and model operations with adorm's API; a driver executes them natively on PostgreSQL (asyncpg) or through
5
+ an existing ORM (Django). The API is modelled on the Django ORM.
6
+
7
+ The package is pre-release; the API reference on the documentation site lists what it provides.
8
+
9
+ ## Requirements
10
+
11
+ - Python 3.11 or newer
12
+ - PostgreSQL for the test suite
13
+ - the conformance run on SQLite needs no database server (Python's `sqlite3`)
14
+
15
+ ## Development
16
+
17
+ The project uses [uv](https://docs.astral.sh/uv/).
18
+
19
+ ```bash
20
+ uv sync
21
+ uv run ruff check .
22
+ uv run ruff format --check .
23
+ uv run pytest
24
+ ```
25
+
26
+ The tests read the test database URL from `ADORM_TEST_DATABASE_URL` (default
27
+ `postgres://postgres@127.0.0.1:5432/adorm_test`). On that server they create and drop the database it names
28
+ (`<name>`: `ADORM_TEST_DATABASE_NAME` when set, `adorm_test` when the URL names `postgres` or none) and the databases
29
+ `<name>_demo`, `<name>_demo_owner`, `<name>_limited`, `<name>_parallel` and `<name>_parallel_<n>` (the clones of
30
+ `manage.py test --parallel`). Other databases and the server's roles are left untouched; runs with different names
31
+ on one server leave each other's databases alone. A run that leaves any of these databases, or a role named
32
+ `<name>_…`, on the server fails. Run the tests as a dedicated user with `CREATEDB`. Under a
33
+ superuser the test of the pool's refusal handling is skipped, because a database's connection limit does not apply to
34
+ a superuser, and so are the tests of the demo, which refuses a superuser:
35
+
36
+ ```sql
37
+ CREATE ROLE adorm LOGIN CREATEDB PASSWORD '...';
38
+ ```
39
+
40
+ `ADORM_TEST_CREATE_ROLES=1` also runs the tests of the `role` connection option. They create and drop the roles
41
+ `<name>_login`, `<name>_alice` and `<name>_bob` and need `CREATEROLE`. Roles belong to the whole server and
42
+ outlive the test databases: set the variable only on a server dedicated to the tests. CI runs the suite with
43
+ `CREATEDB` only, then grants `CREATEROLE` and runs these tests separately.
44
+
45
+ The demo reads its database URL from `ADORM_DEMO_DATABASE_URL`. Both variables can be set in `.env` in the repository
46
+ root (ignored by git; `.env.example` lists them). Variables set in the environment take precedence.
47
+
48
+ ```bash
49
+ cp .env.example .env # then fill in the user and password
50
+ uv run pytest
51
+ ```
52
+
53
+ The conformance suite also runs the Django driver on SQLite, in a database file in a temporary directory, without
54
+ PostgreSQL:
55
+
56
+ ```bash
57
+ uv run pytest --ds=tests.djangoproject.settings_sqlite tests/conformance
58
+ ```
59
+
60
+ ## Demo
61
+
62
+ `demo.py` runs the demo application, a library on PostgreSQL: every example and concurrency scenario on every
63
+ available driver, with the adorm code, the SQL each driver sent, the result and the time side by side.
64
+
65
+ [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/velis74/adorm?quickstart=1)
66
+
67
+ The codespace runs the demo with a PostgreSQL server of its own.
68
+
69
+ - `demo/backend`: a Django project with the app `library`;
70
+ - `demo/models`: the adorm models generated from it;
71
+ - `demo/api`: a FastAPI app running the examples and scenarios;
72
+ - `demo/frontend`: the Vue frontend; `demo/e2e`: its Playwright tests.
73
+
74
+ It creates (owned by the user of `ADORM_DEMO_DATABASE_URL`, which must not be a superuser), migrates and seeds the
75
+ demo database, then serves the API and the Vite dev server on <http://127.0.0.1:5173/>.
76
+
77
+ ```bash
78
+ npm install
79
+ uv run python demo.py
80
+ npm run test:e2e
81
+ ```
82
+
83
+ ## Documentation
84
+
85
+ The documentation site is in `docs/` (VitePress, published on docs.velis.si):
86
+
87
+ ```bash
88
+ npm install
89
+ npm run docs:dev
90
+ ```
91
+
92
+ ## Licence
93
+
94
+ MIT, see [LICENSE](LICENSE).
@@ -0,0 +1,200 @@
1
+ """adorm: an asynchronous database ORM."""
2
+
3
+ from importlib.metadata import version as _distribution_version
4
+
5
+ from adorm.checks import check_schema, SchemaProblem
6
+ from adorm.exceptions import (
7
+ AdormError,
8
+ DatabaseError,
9
+ DataError,
10
+ DeadlockError,
11
+ Error,
12
+ FieldError,
13
+ IntegrityError,
14
+ InterfaceError,
15
+ InternalError,
16
+ MultipleObjectsReturned,
17
+ NotSupportedError,
18
+ ObjectDoesNotExist,
19
+ OperationalError,
20
+ OperationTimeout,
21
+ ProgrammingError,
22
+ ProtectedError,
23
+ RestrictedError,
24
+ SchemaCheckError,
25
+ SchemaMismatchError,
26
+ SessionTimeout,
27
+ TransactionClosed,
28
+ TransactionManagementError,
29
+ TransactionOverlapError,
30
+ ValidationError,
31
+ )
32
+ from adorm.executor import (
33
+ Atomic,
34
+ atomic,
35
+ BoundModel,
36
+ cancellation_outcome,
37
+ CancellationOutcome,
38
+ connection_options,
39
+ create_session,
40
+ current_session,
41
+ listen,
42
+ Listener,
43
+ on_commit,
44
+ Session,
45
+ timeout,
46
+ TransactionOutcome,
47
+ )
48
+ from adorm.models import (
49
+ content_types,
50
+ ContentTypes,
51
+ driver_method,
52
+ ForeignKey,
53
+ GenericForeignKey,
54
+ GenericPrefetch,
55
+ Manager,
56
+ ManyToMany,
57
+ Model,
58
+ ModelMeta,
59
+ Prefetch,
60
+ prefetch_related_objects,
61
+ ReverseForeignKey,
62
+ ReverseOneToOne,
63
+ )
64
+ from adorm.porting import client_base, expose
65
+ from adorm.query import (
66
+ Aggregate,
67
+ Avg,
68
+ Case,
69
+ Coalesce,
70
+ Concat,
71
+ Count,
72
+ Exists,
73
+ Expression,
74
+ F,
75
+ Func,
76
+ Length,
77
+ Lower,
78
+ Max,
79
+ Min,
80
+ Now,
81
+ OuterRef,
82
+ Q,
83
+ QuerySet,
84
+ Subquery,
85
+ Sum,
86
+ Trunc,
87
+ TruncDate,
88
+ TruncDay,
89
+ TruncHour,
90
+ TruncMinute,
91
+ TruncMonth,
92
+ TruncQuarter,
93
+ TruncSecond,
94
+ TruncTime,
95
+ TruncWeek,
96
+ TruncYear,
97
+ Upper,
98
+ Value,
99
+ When,
100
+ )
101
+ from adorm.settings import configure, ConnectionProfile, PoolSettings
102
+
103
+ __version__ = _distribution_version("adorm")
104
+
105
+ __all__ = [
106
+ "AdormError",
107
+ "Aggregate",
108
+ "Atomic",
109
+ "Avg",
110
+ "BoundModel",
111
+ "CancellationOutcome",
112
+ "Case",
113
+ "Coalesce",
114
+ "Concat",
115
+ "ConnectionProfile",
116
+ "ContentTypes",
117
+ "Count",
118
+ "DatabaseError",
119
+ "DataError",
120
+ "DeadlockError",
121
+ "Error",
122
+ "Exists",
123
+ "Expression",
124
+ "F",
125
+ "FieldError",
126
+ "ForeignKey",
127
+ "Func",
128
+ "GenericForeignKey",
129
+ "GenericPrefetch",
130
+ "IntegrityError",
131
+ "InterfaceError",
132
+ "InternalError",
133
+ "Length",
134
+ "Listener",
135
+ "Lower",
136
+ "Manager",
137
+ "ManyToMany",
138
+ "Max",
139
+ "Min",
140
+ "Model",
141
+ "ModelMeta",
142
+ "MultipleObjectsReturned",
143
+ "NotSupportedError",
144
+ "Now",
145
+ "ObjectDoesNotExist",
146
+ "OperationalError",
147
+ "OperationTimeout",
148
+ "OuterRef",
149
+ "PoolSettings",
150
+ "Prefetch",
151
+ "ProgrammingError",
152
+ "ProtectedError",
153
+ "Q",
154
+ "QuerySet",
155
+ "RestrictedError",
156
+ "ReverseForeignKey",
157
+ "ReverseOneToOne",
158
+ "SchemaCheckError",
159
+ "SchemaMismatchError",
160
+ "SchemaProblem",
161
+ "Session",
162
+ "SessionTimeout",
163
+ "Subquery",
164
+ "Sum",
165
+ "TransactionClosed",
166
+ "TransactionManagementError",
167
+ "TransactionOutcome",
168
+ "TransactionOverlapError",
169
+ "Trunc",
170
+ "TruncDate",
171
+ "TruncDay",
172
+ "TruncHour",
173
+ "TruncMinute",
174
+ "TruncMonth",
175
+ "TruncQuarter",
176
+ "TruncSecond",
177
+ "TruncTime",
178
+ "TruncWeek",
179
+ "TruncYear",
180
+ "Upper",
181
+ "ValidationError",
182
+ "Value",
183
+ "When",
184
+ "atomic",
185
+ "cancellation_outcome",
186
+ "check_schema",
187
+ "client_base",
188
+ "configure",
189
+ "connection_options",
190
+ "content_types",
191
+ "create_session",
192
+ "current_session",
193
+ "driver_method",
194
+ "expose",
195
+ "listen",
196
+ "on_commit",
197
+ "prefetch_related_objects",
198
+ "timeout",
199
+ "__version__",
200
+ ]
@@ -0,0 +1,8 @@
1
+ """``python -m adorm``: the ``adorm`` command line."""
2
+
3
+ import sys
4
+
5
+ from adorm.cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())
@@ -0,0 +1,171 @@
1
+ """The schema check: whether the database tables and the driver's models match the adorm models."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Awaitable, Callable, Iterable
6
+ from dataclasses import dataclass
7
+ from typing import Any, Literal, TYPE_CHECKING
8
+
9
+ from adorm.exceptions import SchemaCheckError, SchemaMismatchError
10
+ from adorm.models.base import get_relations, Model
11
+ from adorm.models.registry import registry
12
+ from adorm.models.relations import ManyToMany
13
+ from adorm.operations import CheckTable
14
+
15
+ if TYPE_CHECKING:
16
+ from adorm.executor.sessions import Session
17
+
18
+ __all__ = ["SchemaProblem", "SchemaProblemKind", "check_models", "check_schema", "table_check"]
19
+
20
+ SchemaProblemKind = Literal[
21
+ "schema_hash", "missing_table", "missing_column", "column_type", "nullability", "unknown_field", "required_column"
22
+ ]
23
+ """What a `SchemaProblem` reports:
24
+
25
+ - ``schema_hash``: the model's schema hash ``expected`` differs from the driver's ``actual``, or the driver has no hash
26
+ to compare it with (``actual`` ``None``, ``detail`` says why) (`adorm.SchemaMismatchError`);
27
+ - ``missing_table``: the database has no table ``table``;
28
+ - ``missing_column``: the table has no column ``column`` for ``field``;
29
+ - ``column_type``: the column's type ``actual`` differs from the ``expected`` one;
30
+ - ``nullability``: the column is ``actual`` (``"NULL"`` or ``"NOT NULL"``), the model expects ``expected``;
31
+ - ``unknown_field``: the driver's model has no field (or many-to-many relation) ``field``;
32
+ - ``required_column``: the table has a ``NOT NULL`` column without a default that the model does not write, so an
33
+ insert fails.
34
+ """
35
+
36
+ _KINDS = frozenset(SchemaProblemKind.__args__) # type: ignore[attr-defined]
37
+
38
+
39
+ @dataclass(frozen=True)
40
+ class SchemaProblem:
41
+ """A difference `check_schema()` found for the model ``model`` (a label).
42
+
43
+ ``field`` is the adorm name of the model's field or relation, ``table`` and ``column`` name the database table and
44
+ column, ``expected`` and ``actual`` the values compared, ``detail`` the reason of a ``schema_hash`` problem without
45
+ ``actual``; each is ``None`` where it does not apply. ``str()`` gives a one-line description.
46
+ """
47
+
48
+ model: str
49
+ kind: SchemaProblemKind
50
+ table: str | None = None
51
+ column: str | None = None
52
+ field: str | None = None
53
+ expected: str | None = None
54
+ actual: str | None = None
55
+ detail: str | None = None
56
+
57
+ def __post_init__(self) -> None:
58
+ if self.kind not in _KINDS:
59
+ raise ValueError(f"unknown schema problem kind {self.kind!r}")
60
+
61
+ def __str__(self) -> str:
62
+ where = self.model if self.field is None else f"{self.model}.{self.field}"
63
+ column = f"{self.table}.{self.column}"
64
+ if self.kind == "schema_hash":
65
+ if self.actual is None:
66
+ return f"{where}: cannot be compared with the driver's model: {self.detail or 'it has no schema hash'}"
67
+ return f"{where}: generated with schema hash {self.expected}, the driver's model has {self.actual}"
68
+ if self.kind == "missing_table":
69
+ return f"{where}: the table {self.table} does not exist"
70
+ if self.kind == "missing_column":
71
+ return f"{where}: the column {column} does not exist"
72
+ if self.kind in ("column_type", "nullability"):
73
+ return f"{where}: the column {column} is {self.actual}, the model expects {self.expected}"
74
+ if self.kind == "unknown_field":
75
+ return f"{where}: the driver's model has no such field"
76
+ return f"{where}: the column {column} ({self.actual}) is NOT NULL without a default; the model does not set it"
77
+
78
+
79
+ def _model(model: type[Model] | str) -> type[Model]:
80
+ if isinstance(model, str):
81
+ return registry.get(model)
82
+ if not isinstance(model, type) or not issubclass(model, Model) or model._meta is None:
83
+ raise TypeError(f"check_schema() takes model classes with _meta or their labels, not {model!r}")
84
+ return model
85
+
86
+
87
+ def table_check(model: type[Model]) -> CheckTable:
88
+ """The `CheckTable` operation of the model class ``model``: the ORM names of its fields and of its many-to-many
89
+ relations."""
90
+ meta = model._require_meta()
91
+ many_to_many = [name for name, relation in get_relations(model).items() if isinstance(relation, ManyToMany)]
92
+ return CheckTable(
93
+ meta.label,
94
+ tuple(meta.orm_name(name) for name in model.__pydantic_fields__),
95
+ tuple(meta.orm_name(name) for name in many_to_many),
96
+ )
97
+
98
+
99
+ def _problems(model: type[Model], operation: CheckTable, result: Any) -> list[SchemaProblem]:
100
+ names = {orm_name: name for name, orm_name in _orm_names(model).items()}
101
+ problems = []
102
+ for item in result:
103
+ values = {key: item.get(key) for key in ("table", "column", "field", "expected", "actual")}
104
+ if values["field"] is not None:
105
+ values["field"] = names.get(values["field"], values["field"])
106
+ problems.append(SchemaProblem(operation.model, item["kind"], **values))
107
+ return problems
108
+
109
+
110
+ def _orm_names(model: type[Model]) -> dict[str, str]:
111
+ """ORM name by adorm name, for the fields and relations of ``model``."""
112
+ meta = model._require_meta()
113
+ return {name: meta.orm_name(name) for name in (*model.__pydantic_fields__, *get_relations(model))}
114
+
115
+
116
+ async def check_models(
117
+ models: Iterable[type[Model]], execute: Callable[[CheckTable], Awaitable[Any]]
118
+ ) -> tuple[SchemaProblem, ...]:
119
+ """The problems of ``models`` (model classes with ``_meta``), each checked with `table_check()` passed to
120
+ ``execute``, in the order of ``models``; see `check_schema()`."""
121
+ found: list[SchemaProblem] = []
122
+ seen: set[tuple[Any, ...]] = set()
123
+ for model in dict.fromkeys(models):
124
+ operation = table_check(model)
125
+ try:
126
+ result = await execute(operation)
127
+ except SchemaMismatchError as exc:
128
+ if exc.model != operation.model:
129
+ raise
130
+ problem = SchemaProblem(
131
+ operation.model, "schema_hash", expected=exc.expected, actual=exc.actual, detail=exc.reason
132
+ )
133
+ problems = [problem]
134
+ else:
135
+ problems = _problems(model, operation, result)
136
+ for problem in problems:
137
+ key = (problem.kind, problem.table, problem.column, problem.field) if problem.table else (problem,)
138
+ if key not in seen:
139
+ seen.add(key)
140
+ found.append(problem)
141
+ return tuple(found)
142
+
143
+
144
+ async def check_schema(
145
+ models: Iterable[type[Model] | str] | None = None,
146
+ *,
147
+ session: Session | None = None,
148
+ raise_on_problems: bool = False,
149
+ ) -> tuple[SchemaProblem, ...]:
150
+ """Compare ``models`` (model classes or labels; default: every registered model) with the database and the
151
+ driver of ``session`` (default: the current session) and return the problems found, in the order of ``models``;
152
+ an empty tuple means they match.
153
+
154
+ Each model is checked with one `CheckTable` operation on the session, which also checks the model's schema hash
155
+ against the driver's (`adorm.drivers.Driver.check_schema_hash()`): a mismatch, and a model the driver's target
156
+ does not have, is a ``schema_hash`` problem and the model's tables are not compared. A problem of a table that
157
+ several models share (a proxy model and its concrete model, a parent table) is reported once, for the first of
158
+ them. With ``raise_on_problems`` it raises `SchemaCheckError` holding the problems instead of returning them.
159
+
160
+ A label without a registered model raises ``LookupError``, anything else that is not a model class with ``_meta``
161
+ ``TypeError``; a driver that does not support ``check_table`` raises `NotSupportedError`, and errors of the
162
+ database pass through.
163
+ """
164
+ from adorm.executor.sessions import current_session
165
+
166
+ session = current_session() if session is None else session
167
+ selected = list(registry) if models is None else [_model(model) for model in models]
168
+ found = await check_models(selected, session.execute)
169
+ if raise_on_problems and found:
170
+ raise SchemaCheckError(problems=found)
171
+ return found