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.
Files changed (87) hide show
  1. {msb_arch-3.2.0 → msb_arch-3.2.2}/CHANGELOG.md +67 -0
  2. {msb_arch-3.2.0 → msb_arch-3.2.2}/PKG-INFO +3 -3
  3. {msb_arch-3.2.0 → msb_arch-3.2.2}/README.md +2 -2
  4. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/COMPATIBILITY.md +8 -0
  5. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/README.md +1 -1
  6. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/ROADMAP.md +5 -0
  7. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/__init__.py +1 -1
  8. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/base/basecontainer.py +10 -2
  9. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/base/serializable.py +75 -2
  10. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/model.py +2 -2
  11. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/super/project.py +13 -2
  12. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_declared_fields_of_collections.py +80 -0
  13. msb_arch-3.2.2/tests/test_interpreter_versions.py +170 -0
  14. {msb_arch-3.2.0 → msb_arch-3.2.2}/.gitignore +0 -0
  15. {msb_arch-3.2.0 → msb_arch-3.2.2}/LICENSE +0 -0
  16. {msb_arch-3.2.0 → msb_arch-3.2.2}/NOTICE +0 -0
  17. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/api.md +0 -0
  18. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/architecture.md +0 -0
  19. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/diagrams.md +0 -0
  20. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/examples.md +0 -0
  21. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/guide.md +0 -0
  22. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/modules/base.md +0 -0
  23. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/modules/mega.md +0 -0
  24. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/modules/super.md +0 -0
  25. {msb_arch-3.2.0 → msb_arch-3.2.2}/docs/modules/utils.md +0 -0
  26. {msb_arch-3.2.0 → msb_arch-3.2.2}/pyproject.toml +0 -0
  27. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/base/__init__.py +0 -0
  28. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/base/baseentity.py +0 -0
  29. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/catalogue.py +0 -0
  30. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/errors.py +0 -0
  31. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/interceptors.py +0 -0
  32. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/mega/__init__.py +0 -0
  33. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/mega/manipulator.py +0 -0
  34. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/pipeline.py +0 -0
  35. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/protocols.py +0 -0
  36. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/py.typed +0 -0
  37. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/results.py +0 -0
  38. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/scaffold.py +0 -0
  39. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/super/__init__.py +0 -0
  40. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/super/builtins.py +0 -0
  41. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/super/super.py +0 -0
  42. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/utils/__init__.py +0 -0
  43. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/utils/logging_setup.py +0 -0
  44. {msb_arch-3.2.0 → msb_arch-3.2.2}/src/msb_arch/utils/validation.py +0 -0
  45. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/README.md +0 -0
  46. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/__init__.py +0 -0
  47. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/integration/__init__.py +0 -0
  48. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/integration/test_integration.py +0 -0
  49. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/performance/__init__.py +0 -0
  50. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/performance/test_benchmarks.py +0 -0
  51. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/performance/test_performance.py +0 -0
  52. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_adapters.py +0 -0
  53. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_aggregate_rules_and_copies.py +0 -0
  54. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_all.py +0 -0
  55. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_apply_methods_and_batch.py +0 -0
  56. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_async_surface.py +0 -0
  57. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_basecontainer.py +0 -0
  58. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_baseentity.py +0 -0
  59. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_builtin_operations.py +0 -0
  60. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_catalogue.py +0 -0
  61. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_compiled_validators.py +0 -0
  62. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_concurrency.py +0 -0
  63. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_constraints.py +0 -0
  64. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_declared_defaults.py +0 -0
  65. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_deferred_operations.py +0 -0
  66. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_deprecations.py +0 -0
  67. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_documentation.py +0 -0
  68. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_errors.py +0 -0
  69. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_interceptors.py +0 -0
  70. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_invariants.py +0 -0
  71. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_manipulator.py +0 -0
  72. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_model_graph.py +0 -0
  73. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_persistence.py +0 -0
  74. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_pipeline.py +0 -0
  75. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_project.py +0 -0
  76. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_protocols.py +0 -0
  77. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_provenance.py +0 -0
  78. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_readonly_cache.py +0 -0
  79. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_replay_address.py +0 -0
  80. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_response.py +0 -0
  81. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_revision.py +0 -0
  82. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_scaffold.py +0 -0
  83. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_serialization_round_trip.py +0 -0
  84. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_super.py +0 -0
  85. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_super_argument_binding.py +0 -0
  86. {msb_arch-3.2.0 → msb_arch-3.2.2}/tests/test_typevar_resolution.py +0 -0
  87. {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.0
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
  [![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
223
223
  [![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
224
- [![Version](https://img.shields.io/badge/version-3.2.0-brightgreen.svg)](https://github.com/Torward1024/MSB)
224
+ [![Version](https://img.shields.io/badge/version-3.2.2-brightgreen.svg)](https://github.com/Torward1024/MSB)
225
225
  [![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](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.0
516
+ - **Version**: 3.2.2
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
4
4
  [![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
5
- [![Version](https://img.shields.io/badge/version-3.2.0-brightgreen.svg)](https://github.com/Torward1024/MSB)
5
+ [![Version](https://img.shields.io/badge/version-3.2.2-brightgreen.svg)](https://github.com/Torward1024/MSB)
6
6
  [![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen.svg)](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.0
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
@@ -75,7 +75,7 @@ error taxonomy, logging and the validation helpers.
75
75
 
76
76
  ## Version
77
77
 
78
- 3.2.0
78
+ 3.2.2
79
79
 
80
80
  ## License
81
81
 
@@ -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 |
@@ -51,4 +51,4 @@ __all__ = ["Serializable", "BaseEntity", "BaseContainer", "Super", "Project", "M
51
51
  "path_of",
52
52
  "RequestMetrics", "RequestJournal", "cache_statistics"]
53
53
 
54
- __version__ = "3.2.0"
54
+ __version__ = "3.2.2"
@@ -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
- return cls(items=items, name=data.get("name"), isactive=data.get("isactive", True),
744
- **cls._declared_payload(data, _RESTORED_SEPARATELY))
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(getattr(base, '__annotations__', {}))
100
- annotations.update(attrs.get('__annotations__', {}))
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 getattr(type(owner), "__annotations__", {}):
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
- return cls(name=data["name"], items=items, isactive=data.get("isactive", True),
486
- **cls._declared_payload(data, _RESTORED_SEPARATELY))
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