msb-arch 3.2.0__tar.gz → 3.2.2__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.
- {msb_arch-3.2.0 → msb_arch-3.2.2}/CHANGELOG.md +67 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/PKG-INFO +3 -3
- {msb_arch-3.2.0 → msb_arch-3.2.2}/README.md +2 -2
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/COMPATIBILITY.md +8 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/README.md +1 -1
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/ROADMAP.md +5 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/__init__.py +1 -1
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/base/basecontainer.py +10 -2
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/base/serializable.py +75 -2
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/model.py +2 -2
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/super/project.py +13 -2
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_declared_fields_of_collections.py +80 -0
- msb_arch-3.2.2/tests/test_interpreter_versions.py +170 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/.gitignore +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/LICENSE +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/NOTICE +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/api.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/architecture.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/diagrams.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/examples.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/guide.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/modules/base.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/modules/mega.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/modules/super.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/modules/utils.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/pyproject.toml +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/base/__init__.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/base/baseentity.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/catalogue.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/errors.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/interceptors.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/mega/__init__.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/mega/manipulator.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/pipeline.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/protocols.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/py.typed +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/results.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/scaffold.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/super/__init__.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/super/builtins.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/super/super.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/utils/__init__.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/utils/logging_setup.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/utils/validation.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/README.md +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/__init__.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/integration/__init__.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/integration/test_integration.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/performance/__init__.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/performance/test_benchmarks.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/performance/test_performance.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_adapters.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_aggregate_rules_and_copies.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_all.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_apply_methods_and_batch.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_async_surface.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_basecontainer.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_baseentity.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_builtin_operations.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_catalogue.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_compiled_validators.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_concurrency.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_constraints.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_declared_defaults.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_deferred_operations.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_deprecations.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_documentation.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_errors.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_interceptors.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_invariants.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_manipulator.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_model_graph.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_persistence.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_pipeline.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_project.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_protocols.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_provenance.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_readonly_cache.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_replay_address.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_response.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_revision.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_scaffold.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_serialization_round_trip.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_super.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_super_argument_binding.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_typevar_resolution.py +0 -0
- {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_utils_functions.py +0 -0
|
@@ -13,6 +13,73 @@ causes it, and what to do about it. Start there when moving between versions. An
|
|
|
13
13
|
records what was true at the time of that release and is not rewritten afterwards; where a
|
|
14
14
|
statement has since been overtaken, a note says where it was resolved.
|
|
15
15
|
|
|
16
|
+
## [3.2.2] - 2026-10-26
|
|
17
|
+
|
|
18
|
+
`requires-python` promised four interpreters. The workflow ran one. Two of the other three had
|
|
19
|
+
been broken for a year, and the suite was green the whole time.
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- **A class keeps the fields it declares, on Python 3.14 and 3.15.** Those versions made
|
|
24
|
+
annotations lazy ([PEP 649](https://peps.python.org/pep-0649/) and
|
|
25
|
+
[PEP 749](https://peps.python.org/pep-0749/)): a class body that annotates a name no longer
|
|
26
|
+
leaves `__annotations__` in the namespace a metaclass is handed, it leaves an `__annotate__`
|
|
27
|
+
function that computes them on demand. The metaclass read the namespace key, found nothing,
|
|
28
|
+
and dropped every field the class declared itself:
|
|
29
|
+
|
|
30
|
+
```python
|
|
31
|
+
class Client(BaseEntity):
|
|
32
|
+
credit: float = 0.0
|
|
33
|
+
|
|
34
|
+
Client(name="c", credit=5.0) # UnknownAttributeError: Unknown attributes ... {'credit'}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Fields inherited from a base still arrived, because reading `__annotations__` off a *built*
|
|
38
|
+
class does call `__annotate__` — so a hierarchy failed on exactly the fields it added. 273
|
|
39
|
+
tests failed on 3.14 and 3.15; all 1017 passed on 3.12.
|
|
40
|
+
|
|
41
|
+
Annotations are now read through `annotationlib.get_annotations` where it exists, with
|
|
42
|
+
`Format.FORWARDREF` so an annotation naming a class defined further down a module still does
|
|
43
|
+
not have to resolve while the class is being built — which is the laziness those PEPs added.
|
|
44
|
+
On 3.12 and 3.13 the previous path is untouched.
|
|
45
|
+
|
|
46
|
+
### Changed
|
|
47
|
+
|
|
48
|
+
- **The suite runs on every Python the metadata promises**: 3.12, 3.13, 3.14 and 3.15, with
|
|
49
|
+
`fail-fast: false` so one version failing cannot hide the rest.
|
|
50
|
+
|
|
51
|
+
### Added
|
|
52
|
+
|
|
53
|
+
- `tests/test_interpreter_versions.py`, which holds the promise and the matrix to each other.
|
|
54
|
+
It fails on the first interpreter the matrix does not list — the only moment anybody is in a
|
|
55
|
+
position to notice — and refuses any new direct read of `__annotations__` in the package, the
|
|
56
|
+
implementation detail that cost two versions.
|
|
57
|
+
|
|
58
|
+
### Upgrading from 3.2.1
|
|
59
|
+
|
|
60
|
+
| Symptom | Cause | What to do |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| `UnknownAttributeError` for a field the class plainly declares, on Python 3.14 or 3.15 | Lazy annotations; the declared field never reached `_fields` | Upgrade. Nothing in your code was wrong |
|
|
63
|
+
| Nothing, on Python 3.12 or 3.13 | Those versions were never affected | Upgrade when convenient |
|
|
64
|
+
|
|
65
|
+
## [3.2.1] - 2026-10-21
|
|
66
|
+
|
|
67
|
+
### Fixed
|
|
68
|
+
|
|
69
|
+
- **A subclass with a constructor of its own could not be restored.** 3.2.0 passed a container's
|
|
70
|
+
and a project's declared fields to the constructor as keywords, which is right for the classes
|
|
71
|
+
that take `**fields` and wrong for every class that wrote its own narrower `__init__` --
|
|
72
|
+
`__init__(self, name, items)` is the common shape, and the application this release came from
|
|
73
|
+
uses it. Every `from_dict` on such a class raised `TypeError: got an unexpected keyword
|
|
74
|
+
argument`.
|
|
75
|
+
|
|
76
|
+
Where the constructor cannot take them, the fields are applied after it instead, as one group,
|
|
77
|
+
so the rules are still checked once. Whether a class takes them is read from its signature once
|
|
78
|
+
per class.
|
|
79
|
+
|
|
80
|
+
Found by running the downstream suite against the release: 1604 of its tests pass on 3.2.1,
|
|
81
|
+
where 3.2.0 broke 668 of them.
|
|
82
|
+
|
|
16
83
|
## [3.2.0] - 2026-10-21
|
|
17
84
|
|
|
18
85
|
Reported from downstream, where a model of a brain was being put on MSB. Seven defects, all
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: msb_arch
|
|
3
|
-
Version: 3.2.
|
|
3
|
+
Version: 3.2.2
|
|
4
4
|
Summary: A dependency-free domain layer for Python: entities, invariants and operations behind one entry point, driven by requests that are data
|
|
5
5
|
Project-URL: Homepage, https://github.com/Torward1024/MSB
|
|
6
6
|
Project-URL: Documentation, https://github.com/Torward1024/MSB/docs
|
|
@@ -221,7 +221,7 @@ Description-Content-Type: text/markdown
|
|
|
221
221
|
|
|
222
222
|
[](https://www.python.org/)
|
|
223
223
|
[](LICENSE)
|
|
224
|
-
[](https://github.com/Torward1024/MSB)
|
|
225
225
|
[](pyproject.toml)
|
|
226
226
|
|
|
227
227
|
**A domain layer for Python, with no dependencies.** The model, the rules it must obey and the
|
|
@@ -513,4 +513,4 @@ Available for collaboration, contract work and support — [almax1024@gmail.com]
|
|
|
513
513
|
- **Author**: Alexey Rudnitskiy
|
|
514
514
|
- **Email**: [almax1024@gmail.com](mailto:almax1024@gmail.com)
|
|
515
515
|
- **Repository**: [https://github.com/Torward1024/MSB](https://github.com/Torward1024/MSB)
|
|
516
|
-
- **Version**: 3.2.
|
|
516
|
+
- **Version**: 3.2.2
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.python.org/)
|
|
4
4
|
[](LICENSE)
|
|
5
|
-
[](https://github.com/Torward1024/MSB)
|
|
6
6
|
[](pyproject.toml)
|
|
7
7
|
|
|
8
8
|
**A domain layer for Python, with no dependencies.** The model, the rules it must obey and the
|
|
@@ -294,4 +294,4 @@ Available for collaboration, contract work and support — [almax1024@gmail.com]
|
|
|
294
294
|
- **Author**: Alexey Rudnitskiy
|
|
295
295
|
- **Email**: [almax1024@gmail.com](mailto:almax1024@gmail.com)
|
|
296
296
|
- **Repository**: [https://github.com/Torward1024/MSB](https://github.com/Torward1024/MSB)
|
|
297
|
-
- **Version**: 3.2.
|
|
297
|
+
- **Version**: 3.2.2
|
|
@@ -131,6 +131,14 @@ warning for a release and then going.
|
|
|
131
131
|
walk, and a name is unique within a container rather than across a model. Where the answer
|
|
132
132
|
matters, address the object: `locate(path)` is defined, `find(name)` is a convenience.
|
|
133
133
|
|
|
134
|
+
## Behaviour corrected in 3.2.2
|
|
135
|
+
|
|
136
|
+
- **A class's own declared fields work on Python 3.14 and 3.15.** They were silently dropped
|
|
137
|
+
there: the metaclass read `__annotations__` out of the class namespace, and those versions
|
|
138
|
+
moved it behind a lazily called `__annotate__` function (PEP 649/749). Inherited fields were
|
|
139
|
+
unaffected, so a hierarchy broke on precisely the fields each class added. No API changed;
|
|
140
|
+
code that was correct simply works now. 3.12 and 3.13 are untouched.
|
|
141
|
+
|
|
134
142
|
## Behaviour corrected in 3.2.0
|
|
135
143
|
|
|
136
144
|
Five promises the documentation made and the code did not keep. Each changes what an existing
|
|
@@ -13,6 +13,7 @@ Each was considered and closed. Recorded so it is decided once rather than argue
|
|
|
13
13
|
|
|
14
14
|
| Idea | Verdict |
|
|
15
15
|
| --- | --- |
|
|
16
|
+
| **An aggregate's rule checked after every change inside a member** | Quadratic. A rule over a whole aggregate costs what the aggregate costs to walk: measured on 512 members, 106 µs against 7.8 µs for adding one, so assembling it would pay the walk 512 times. The rule is checked when the aggregate itself changes, on build, on restore, at **save** -- so a state that cannot be loaded cannot be written -- and whenever the application asks. A guard after every structural change belongs in an interceptor, which sees every request |
|
|
16
17
|
| **`pickle` of a model** | `save`/`load` already put a model on disk, and do it better: the data survives a change of class (migrations), reads in anything, and executes no code on load. The other use, moving a model between processes, does not arise — the executor is threads on purpose, since numerical libraries release the GIL |
|
|
17
18
|
| **An `inplace=False` mode** — operations that return a copy | Doubles the meaning of every operation, and every handler would have to implement both or the mode works by accident. Identity is load-bearing here: the ownership graph, cache invalidation, `address`/`locate` and replay all address the object in the model, and a returned copy is in no model. `clone()` plus a write on the copy is the same thing in two lines |
|
|
18
19
|
| **Incremental recomputation** — run only the steps whose inputs changed | The parts are already exposed: `fingerprint()` answers "did this change", and a `PipelineRun` holds each step's result. What is left is policy — what counts as a step's input, how long a cached answer is trusted — and that belongs to the calculation, not to the scheduler |
|
|
@@ -53,3 +54,7 @@ The places where the obvious answer was wrong. Kept because each will be propose
|
|
|
53
54
|
| Containers had a base-class fallback for handlers and entities did not | An asymmetry is a bug waiting to be reported |
|
|
54
55
|
| `clear()` nulled attributes, removed items, and dropped references | One name for three jobs reads as consistency and is not |
|
|
55
56
|
| Every cache added for speed was probed afterwards — inheritance, mixed types, threads, classes whose fields change | A cache is where the next bug lives |
|
|
57
|
+
| A collection wrote the fields it declared and read back the defaults, and `__eq__` called the two equal | Equality that looks at part of the state hides the loss of the rest. Round-trip tests are only as good as the comparison they end with |
|
|
58
|
+
| A class's own declared fields vanished on Python 3.14 while 3.12 stayed green for a year | Every interpreter `requires-python` promises is one the suite runs — and an implementation detail read instead of the documented API is a dependency nobody declared |
|
|
59
|
+
| A copied subtree kept the original's owners: `deepcopy` hands back the very same weak references | A copy belongs to whoever copied it. Anything derived from the ownership graph — an address, invalidation — is wrong until that holds |
|
|
60
|
+
| 3.2.0 passed a collection's fields to constructors that never asked for them, and broke 668 tests in the application built on it — none of its own 1044 | A release that passes your own suite can still break every subclass downstream. Run the downstream suite before tagging, not after |
|
|
@@ -740,8 +740,16 @@ class BaseContainer(Serializable, ABC, Generic[T]):
|
|
|
740
740
|
raise SerializationError(f"Failed to deserialize item '{key}' in {cls.__name__}: {str(e)}") from e
|
|
741
741
|
# The container's own declared fields, which `to_dict` has always written and this used
|
|
742
742
|
# to drop -- restoring the class's defaults over what the file said.
|
|
743
|
-
|
|
744
|
-
|
|
743
|
+
fields = cls._declared_payload(data, _RESTORED_SEPARATELY)
|
|
744
|
+
if fields and cls._takes_field_kwargs():
|
|
745
|
+
return cls(items=items, name=data.get("name"),
|
|
746
|
+
isactive=data.get("isactive", True), **fields)
|
|
747
|
+
restored = cls(items=items, name=data.get("name"), isactive=data.get("isactive", True))
|
|
748
|
+
if fields:
|
|
749
|
+
# A subclass with a constructor of its own takes the arguments it declared; its
|
|
750
|
+
# fields are written afterwards, as one group so its rules are checked once.
|
|
751
|
+
restored.set(fields)
|
|
752
|
+
return restored
|
|
745
753
|
|
|
746
754
|
def __iter__(self) -> Iterator[T]:
|
|
747
755
|
"""Iterate over the items in the container.
|
|
@@ -64,6 +64,52 @@ _TRAVERSAL: ContextVar = ContextVar("msb_arch_to_dict_seen", default=None)
|
|
|
64
64
|
# of a set, and the death of either would stop tracking the other.
|
|
65
65
|
_CACHING_OBJECTS: weakref.WeakValueDictionary = weakref.WeakValueDictionary()
|
|
66
66
|
|
|
67
|
+
try:
|
|
68
|
+
# Python 3.14 made annotations lazy (PEP 649/749): a class body that annotates a name no
|
|
69
|
+
# longer leaves `__annotations__` in the namespace, it leaves an `__annotate__` function
|
|
70
|
+
# that computes them on demand. Reading the namespace key found nothing there, so every
|
|
71
|
+
# field a class declared itself was lost -- `credit: float = 0.0` became an unknown
|
|
72
|
+
# attribute -- while fields inherited from a base still arrived, because reading
|
|
73
|
+
# `__annotations__` off a built class does call `__annotate__`. Tested on 3.12 only, so
|
|
74
|
+
# 3.14 and 3.15 were broken for a year without a red light.
|
|
75
|
+
from annotationlib import Format as _AnnotationFormat, get_annotations as _get_annotations
|
|
76
|
+
except ImportError: # 3.12 and 3.13, where the namespace key is the truth
|
|
77
|
+
_AnnotationFormat = None
|
|
78
|
+
_get_annotations = None
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def _own_annotations(owner: Any, namespace: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
82
|
+
"""Return the annotations a class declares itself, without inheriting or evaluating.
|
|
83
|
+
|
|
84
|
+
Args:
|
|
85
|
+
owner (Any): The class to read. On 3.14 and later this is asked for its annotations
|
|
86
|
+
even when a raw namespace is also available, since the namespace no longer has them.
|
|
87
|
+
namespace (Optional[Dict[str, Any]]): The class body's namespace, when the caller is a
|
|
88
|
+
metaclass that has one. Used only on 3.12 and 3.13.
|
|
89
|
+
|
|
90
|
+
Returns:
|
|
91
|
+
Dict[str, Any]: Field name mapped to its annotation, which may be a string or a
|
|
92
|
+
`ForwardRef`; `_resolve_type` already reduces both against the declaring class.
|
|
93
|
+
|
|
94
|
+
Notes:
|
|
95
|
+
- `Format.FORWARDREF` rather than the default: an annotation naming a class defined
|
|
96
|
+
further down the module would otherwise raise at class-creation time, which is
|
|
97
|
+
exactly the lazy evaluation 3.14 introduced to avoid. An unresolved name arrives as
|
|
98
|
+
a `ForwardRef` and travels the same path a string annotation always has.
|
|
99
|
+
- Own annotations only, on every version. The merge across bases is the caller's job,
|
|
100
|
+
and it is done bases-first so that a subclass redeclaring a field wins.
|
|
101
|
+
"""
|
|
102
|
+
if _get_annotations is not None:
|
|
103
|
+
try:
|
|
104
|
+
return dict(_get_annotations(owner, format=_AnnotationFormat.FORWARDREF))
|
|
105
|
+
except Exception: # a broken `__annotate__` must not stop class creation
|
|
106
|
+
logger.debug("Could not read the annotations of %r", owner)
|
|
107
|
+
return {}
|
|
108
|
+
if namespace is not None:
|
|
109
|
+
return dict(namespace.get('__annotations__', {}) or {})
|
|
110
|
+
return dict(getattr(owner, '__annotations__', {}) or {})
|
|
111
|
+
|
|
112
|
+
|
|
67
113
|
class EntityMeta(ABCMeta):
|
|
68
114
|
"""Metaclass for Serializable to handle type annotations and enforce attribute validation.
|
|
69
115
|
|
|
@@ -96,8 +142,8 @@ class EntityMeta(ABCMeta):
|
|
|
96
142
|
for base in reversed(bases):
|
|
97
143
|
if hasattr(base, '_fields'):
|
|
98
144
|
annotations.update(base._fields)
|
|
99
|
-
annotations.update(
|
|
100
|
-
annotations.update(
|
|
145
|
+
annotations.update(_own_annotations(base))
|
|
146
|
+
annotations.update(_own_annotations(new_class, attrs))
|
|
101
147
|
new_class._fields = annotations
|
|
102
148
|
new_class._type_cache = {}
|
|
103
149
|
# Rules declared with `@invariant`, collected here rather than on first use: the check
|
|
@@ -788,6 +834,33 @@ class Serializable(ABC, metaclass=EntityMeta):
|
|
|
788
834
|
object.__setattr__(self, key, previous)
|
|
789
835
|
self._invalidate_cache()
|
|
790
836
|
|
|
837
|
+
@classmethod
|
|
838
|
+
def _takes_field_kwargs(cls) -> bool:
|
|
839
|
+
"""Report whether this class's constructor accepts arbitrary field keywords.
|
|
840
|
+
|
|
841
|
+
Returns:
|
|
842
|
+
bool: True when `__init__` has a `**kwargs` of its own.
|
|
843
|
+
|
|
844
|
+
Notes:
|
|
845
|
+
- A subclass is free to write a narrower constructor -- `__init__(self, name, items)`
|
|
846
|
+
is a common and reasonable one -- and `from_dict` must not hand such a class
|
|
847
|
+
keywords it never asked for. Where it cannot, the fields are applied after
|
|
848
|
+
construction instead.
|
|
849
|
+
- Worked out once per class: reading a signature is not something to do per object.
|
|
850
|
+
"""
|
|
851
|
+
cached = cls.__dict__.get('_field_kwargs_cache')
|
|
852
|
+
if cached is not None:
|
|
853
|
+
return cached
|
|
854
|
+
|
|
855
|
+
from inspect import Parameter, signature
|
|
856
|
+
try:
|
|
857
|
+
takes = any(parameter.kind is Parameter.VAR_KEYWORD
|
|
858
|
+
for parameter in signature(cls.__init__).parameters.values())
|
|
859
|
+
except (TypeError, ValueError): # a constructor that cannot be read
|
|
860
|
+
takes = False
|
|
861
|
+
type.__setattr__(cls, '_field_kwargs_cache', takes)
|
|
862
|
+
return takes
|
|
863
|
+
|
|
791
864
|
@classmethod
|
|
792
865
|
def _declared_payload(cls, data: Dict[str, Any], skip: frozenset) -> Dict[str, Any]:
|
|
793
866
|
"""Return the declared fields a serialized mapping carries, ready for the constructor.
|
|
@@ -19,7 +19,7 @@ Limits:
|
|
|
19
19
|
import logging
|
|
20
20
|
from typing import Any, Dict, List, Optional, Set, get_args
|
|
21
21
|
|
|
22
|
-
from .base.serializable import Serializable
|
|
22
|
+
from .base.serializable import Serializable, _own_annotations
|
|
23
23
|
from .utils.logging_setup import logger
|
|
24
24
|
|
|
25
25
|
#: The derivation only. Callers go through `manipulator.describe_model()`.
|
|
@@ -301,7 +301,7 @@ def member_called(name: str, owner: Any) -> Optional[Any]:
|
|
|
301
301
|
return held
|
|
302
302
|
|
|
303
303
|
# A container held in a field carries its own name, which is the one a path records.
|
|
304
|
-
for field in
|
|
304
|
+
for field in _own_annotations(type(owner)):
|
|
305
305
|
value = getattr(owner, field, None)
|
|
306
306
|
if isinstance(value, Serializable) and getattr(value, "name", None) == name:
|
|
307
307
|
return value
|
|
@@ -482,8 +482,19 @@ class Project(Serializable, ABC):
|
|
|
482
482
|
except (TypeError, ValueError) as e:
|
|
483
483
|
logger.error("Failed to deserialize item '%s' for project: %s", k, str(e))
|
|
484
484
|
raise SerializationError(f"Invalid data for item '{k}': {str(e)}") from e
|
|
485
|
-
|
|
486
|
-
|
|
485
|
+
fields = cls._declared_payload(data, _RESTORED_SEPARATELY)
|
|
486
|
+
isactive = data.get("isactive", True)
|
|
487
|
+
if cls._takes_field_kwargs():
|
|
488
|
+
return cls(name=data["name"], items=items, isactive=isactive, **fields)
|
|
489
|
+
# A subclass that wrote its own constructor takes the two arguments it declared --
|
|
490
|
+
# `__init__(self, name, items)` is the common shape -- so the rest is applied after
|
|
491
|
+
# it, as one group, with the rules checked once.
|
|
492
|
+
restored = cls(name=data["name"], items=items)
|
|
493
|
+
if isactive is not True:
|
|
494
|
+
restored.isactive = isactive
|
|
495
|
+
if fields:
|
|
496
|
+
restored.set(fields)
|
|
497
|
+
return restored
|
|
487
498
|
except (KeyError, TypeError, ValueError) as e:
|
|
488
499
|
logger.error("Failed to deserialize Project from dict with name '%s': %s", data.get('name', 'unknown'), str(e))
|
|
489
500
|
raise SerializationError(f"Invalid project data: {str(e)}") from e
|
|
@@ -170,3 +170,83 @@ def test_a_container_still_replaces_its_items_through_set():
|
|
|
170
170
|
|
|
171
171
|
if __name__ == "__main__":
|
|
172
172
|
pytest.main([__file__, "-v"])
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
# --- a subclass with a constructor of its own ------------------------------------------------------
|
|
176
|
+
|
|
177
|
+
class NarrowShelf(BaseContainer[Col]):
|
|
178
|
+
"""The common shape downstream: a constructor that names what it takes and nothing more."""
|
|
179
|
+
|
|
180
|
+
role: str = "spare"
|
|
181
|
+
|
|
182
|
+
def __init__(self, items=None, name=None, isactive=True, use_cache=False):
|
|
183
|
+
super().__init__(items=items, name=name, isactive=isactive, use_cache=use_cache)
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
class NarrowZone(Project):
|
|
187
|
+
_item_type = Col
|
|
188
|
+
|
|
189
|
+
role: str = "spare"
|
|
190
|
+
|
|
191
|
+
def __init__(self, name="NARROW", items=None):
|
|
192
|
+
super().__init__(name=name, items=items)
|
|
193
|
+
|
|
194
|
+
def create_item(self, item_code: str = "ITEM", isactive: bool = True) -> None:
|
|
195
|
+
self.add_item(Col(name=item_code))
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def test_a_container_whose_constructor_is_narrow_still_restores_its_fields():
|
|
199
|
+
"""`from_dict` must not hand a class keywords its constructor never asked for.
|
|
200
|
+
|
|
201
|
+
Caught by an application downstream whose project declares `__init__(self, name, items)`:
|
|
202
|
+
3.2.0 passed the fields as keywords and every `from_dict` raised `TypeError`. Where the
|
|
203
|
+
constructor cannot take them, they are applied after it -- as one group, so the rules are
|
|
204
|
+
still checked once.
|
|
205
|
+
"""
|
|
206
|
+
shelf = NarrowShelf(name="front")
|
|
207
|
+
shelf.role = "main"
|
|
208
|
+
shelf.add(Col(name="c0"))
|
|
209
|
+
|
|
210
|
+
restored = NarrowShelf.from_dict(json.loads(json.dumps(dict(shelf.to_dict()))))
|
|
211
|
+
|
|
212
|
+
assert restored.role == "main"
|
|
213
|
+
assert restored == shelf
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
def test_a_project_whose_constructor_is_narrow_still_restores_its_fields():
|
|
217
|
+
zone = NarrowZone(name="v1")
|
|
218
|
+
zone.role = "main"
|
|
219
|
+
zone.create_item("c0")
|
|
220
|
+
|
|
221
|
+
restored = NarrowZone.from_dict(json.loads(json.dumps(dict(zone.to_dict()))))
|
|
222
|
+
|
|
223
|
+
assert restored.role == "main"
|
|
224
|
+
assert restored == zone
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def test_a_narrow_project_restores_an_inactive_flag_too():
|
|
228
|
+
zone = NarrowZone(name="v1")
|
|
229
|
+
zone.isactive = False
|
|
230
|
+
|
|
231
|
+
assert NarrowZone.from_dict(dict(zone.to_dict())).isactive is False
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
def test_a_rule_over_restored_fields_is_checked_once_on_a_narrow_subclass():
|
|
235
|
+
class Banded(NarrowZone):
|
|
236
|
+
capacity: int = 10
|
|
237
|
+
|
|
238
|
+
@invariant("capacity must fit the role")
|
|
239
|
+
def _fits(self) -> bool:
|
|
240
|
+
return self.capacity <= (5 if self.role == "main" else 100)
|
|
241
|
+
|
|
242
|
+
sound = Banded(name="v1")
|
|
243
|
+
sound.set({"role": "main", "capacity": 5})
|
|
244
|
+
|
|
245
|
+
assert Banded.from_dict(dict(sound.to_dict())) == sound
|
|
246
|
+
|
|
247
|
+
broken = dict(sound.to_dict())
|
|
248
|
+
broken["capacity"] = 50
|
|
249
|
+
# Restoring wraps what went wrong in `SerializationError` -- data that cannot be read is
|
|
250
|
+
# what the caller asked about -- and carries the rule in the message.
|
|
251
|
+
with pytest.raises(errors.SerializationError, match="capacity must fit the role"):
|
|
252
|
+
Banded.from_dict(broken)
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
# test_interpreter_versions.py
|
|
2
|
+
"""Every interpreter the package promises to work on is one the suite is run on.
|
|
3
|
+
|
|
4
|
+
`requires-python = ">=3.12"` promised four versions and the workflow ran one. What that hid:
|
|
5
|
+
Python 3.14 made annotations lazy (PEP 649/749), so a class body that annotates a name no
|
|
6
|
+
longer leaves `__annotations__` in the namespace the metaclass is handed -- it leaves an
|
|
7
|
+
`__annotate__` function. The metaclass read the namespace key, found nothing, and every field
|
|
8
|
+
a class declared itself was silently dropped. `credit: float = 0.0` became an unknown
|
|
9
|
+
attribute, 273 tests failed on 3.14 and 3.15, and 3.12 stayed green the whole time.
|
|
10
|
+
|
|
11
|
+
The lesson is not about annotations. A version in `requires-python` that nothing runs is a
|
|
12
|
+
claim, and this module turns the claim into a test: the matrix must start where the metadata
|
|
13
|
+
starts, cover every minor version in between, and reach at least the interpreter in hand --
|
|
14
|
+
so the day someone runs this on a version the workflow does not list, it says so.
|
|
15
|
+
"""
|
|
16
|
+
import ast
|
|
17
|
+
import pathlib
|
|
18
|
+
import re
|
|
19
|
+
import sys
|
|
20
|
+
import tomllib
|
|
21
|
+
|
|
22
|
+
import pytest
|
|
23
|
+
|
|
24
|
+
from msb_arch import BaseEntity
|
|
25
|
+
from msb_arch.base.serializable import _own_annotations
|
|
26
|
+
|
|
27
|
+
ROOT = pathlib.Path(__file__).resolve().parent.parent
|
|
28
|
+
PYPROJECT = ROOT / "pyproject.toml"
|
|
29
|
+
WORKFLOW = ROOT / ".github" / "workflows" / "ci.yml"
|
|
30
|
+
|
|
31
|
+
#: Only in a source checkout. Installed from a wheel, there is no workflow to read.
|
|
32
|
+
packaging_present = pytest.mark.skipif(
|
|
33
|
+
not (PYPROJECT.exists() and WORKFLOW.exists()),
|
|
34
|
+
reason="runs against a source checkout, not an installed wheel",
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def _promised_minimum() -> tuple:
|
|
39
|
+
"""Return the lowest Python `requires-python` allows, as a `(major, minor)` pair."""
|
|
40
|
+
metadata = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
|
|
41
|
+
spec = metadata["project"]["requires-python"]
|
|
42
|
+
match = re.fullmatch(r">=\s*(\d+)\.(\d+)", spec.strip())
|
|
43
|
+
assert match, f"requires-python is {spec!r}; this test reads the form '>=X.Y'"
|
|
44
|
+
return int(match.group(1)), int(match.group(2))
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _tested_versions() -> list:
|
|
48
|
+
"""Return the Python versions the CI matrix names, in the order it names them."""
|
|
49
|
+
text = WORKFLOW.read_text(encoding="utf-8")
|
|
50
|
+
match = re.search(r"python-version:\s*\[([^\]]+)\]", text)
|
|
51
|
+
assert match, "the workflow does not declare a python-version matrix"
|
|
52
|
+
return [tuple(int(part) for part in version.split("."))
|
|
53
|
+
for version in re.findall(r"['\"](\d+\.\d+)['\"]", match.group(1))]
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
# --- the promise and the matrix agree ---------------------------------------------------------
|
|
57
|
+
|
|
58
|
+
@packaging_present
|
|
59
|
+
def test_the_matrix_starts_where_the_metadata_starts():
|
|
60
|
+
assert _tested_versions()[0] == _promised_minimum()
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@packaging_present
|
|
64
|
+
def test_the_matrix_skips_no_version_in_between():
|
|
65
|
+
"""A gap is the same hole in a smaller shape: 3.13 untested is 3.13 unknown."""
|
|
66
|
+
tested = _tested_versions()
|
|
67
|
+
expected = [(tested[0][0], minor)
|
|
68
|
+
for minor in range(tested[0][1], tested[-1][1] + 1)]
|
|
69
|
+
|
|
70
|
+
assert tested == expected
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
@packaging_present
|
|
74
|
+
def test_the_matrix_reaches_the_interpreter_running_this():
|
|
75
|
+
"""Fails on the first Python released after the matrix was last extended, which is the
|
|
76
|
+
only moment anybody is in a position to notice."""
|
|
77
|
+
tested = _tested_versions()
|
|
78
|
+
|
|
79
|
+
assert max(tested) >= sys.version_info[:2], (
|
|
80
|
+
f"running on {sys.version_info.major}.{sys.version_info.minor}, "
|
|
81
|
+
f"matrix stops at {max(tested)[0]}.{max(tested)[1]}")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
# --- declared fields, read through the documented API ------------------------------------------
|
|
85
|
+
|
|
86
|
+
def test_a_class_keeps_the_field_it_declares_itself():
|
|
87
|
+
"""What 3.14 broke. Green on 3.12 before the fix and after it, which is the point: this
|
|
88
|
+
assertion was never the weak part -- running it on one interpreter was."""
|
|
89
|
+
class Client(BaseEntity):
|
|
90
|
+
credit: float = 0.0
|
|
91
|
+
|
|
92
|
+
assert "credit" in Client._fields
|
|
93
|
+
assert Client(name="c", credit=5.0).credit == 5.0
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def test_a_field_declared_on_a_base_arrives_too():
|
|
97
|
+
class Account(BaseEntity):
|
|
98
|
+
balance: float = 0.0
|
|
99
|
+
|
|
100
|
+
class Savings(Account):
|
|
101
|
+
rate: float = 0.01
|
|
102
|
+
|
|
103
|
+
assert {"balance", "rate"} <= set(Savings._fields)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def test_a_subclass_redeclaring_a_field_wins():
|
|
107
|
+
class Loose(BaseEntity):
|
|
108
|
+
code: object = None
|
|
109
|
+
|
|
110
|
+
class Strict(Loose):
|
|
111
|
+
code: str = ""
|
|
112
|
+
|
|
113
|
+
assert Strict._fields["code"] is str
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def test_own_annotations_does_not_inherit():
|
|
117
|
+
class Account(BaseEntity):
|
|
118
|
+
balance: float = 0.0
|
|
119
|
+
|
|
120
|
+
class Savings(Account):
|
|
121
|
+
rate: float = 0.01
|
|
122
|
+
|
|
123
|
+
assert set(_own_annotations(Savings)) == {"rate"}
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def test_a_forward_reference_does_not_raise_while_the_class_is_built():
|
|
127
|
+
"""Lazy annotations exist so a name defined further down the module can be named above it.
|
|
128
|
+
Reading them eagerly at class creation would give that back.
|
|
129
|
+
"""
|
|
130
|
+
class Holder(BaseEntity):
|
|
131
|
+
later: "DefinedBelow" = None
|
|
132
|
+
|
|
133
|
+
class DefinedBelow(BaseEntity):
|
|
134
|
+
pass
|
|
135
|
+
|
|
136
|
+
assert "later" in Holder._fields
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
# --- the detail that broke, kept out of the source --------------------------------------------
|
|
140
|
+
|
|
141
|
+
@packaging_present
|
|
142
|
+
def test_no_module_reads_the_annotations_of_a_namespace_or_a_class_directly():
|
|
143
|
+
"""`__annotations__` on a class, and in a class body's namespace, are implementation
|
|
144
|
+
details -- the documentation has said to use `inspect.get_annotations` since 3.10. Reading
|
|
145
|
+
the namespace key is what cost two interpreters. `_own_annotations` is the one place that
|
|
146
|
+
knows how to ask, so nothing else may ask.
|
|
147
|
+
"""
|
|
148
|
+
reading = re.compile(r"""(?:\.get\(\s*['"]__annotations__|getattr\([^)]*['"]__annotations__|"""
|
|
149
|
+
r"""\[\s*['"]__annotations__['"]\s*\]|\.__annotations__)""")
|
|
150
|
+
offenders = []
|
|
151
|
+
for path in sorted((ROOT / "src" / "msb_arch").rglob("*.py")):
|
|
152
|
+
text = path.read_text(encoding="utf-8")
|
|
153
|
+
# The helper's own body is the exception, found by name rather than by a comment a
|
|
154
|
+
# later edit could carry along to code that does not deserve it.
|
|
155
|
+
allowed = range(0)
|
|
156
|
+
for node in ast.walk(ast.parse(text)):
|
|
157
|
+
if isinstance(node, ast.FunctionDef) and node.name == "_own_annotations":
|
|
158
|
+
allowed = range(node.lineno, (node.end_lineno or node.lineno) + 1)
|
|
159
|
+
for number, line in enumerate(text.splitlines(), 1):
|
|
160
|
+
if number in allowed or line.lstrip().startswith("#"):
|
|
161
|
+
continue
|
|
162
|
+
if reading.search(line):
|
|
163
|
+
offenders.append(f"{path.relative_to(ROOT)}:{number}: {line.strip()}")
|
|
164
|
+
|
|
165
|
+
assert offenders == [], (
|
|
166
|
+
"read annotations through `_own_annotations` instead:\n" + "\n".join(offenders))
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
if __name__ == "__main__":
|
|
170
|
+
pytest.main([__file__, "-v"])
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|