msb-arch 3.2.1__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.1 → msb_arch-3.2.2}/CHANGELOG.md +49 -0
  2. {msb_arch-3.2.1 → msb_arch-3.2.2}/PKG-INFO +3 -3
  3. {msb_arch-3.2.1 → msb_arch-3.2.2}/README.md +2 -2
  4. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/COMPATIBILITY.md +8 -0
  5. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/README.md +1 -1
  6. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/ROADMAP.md +5 -0
  7. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/__init__.py +1 -1
  8. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/base/serializable.py +48 -2
  9. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/model.py +2 -2
  10. msb_arch-3.2.2/tests/test_interpreter_versions.py +170 -0
  11. {msb_arch-3.2.1 → msb_arch-3.2.2}/.gitignore +0 -0
  12. {msb_arch-3.2.1 → msb_arch-3.2.2}/LICENSE +0 -0
  13. {msb_arch-3.2.1 → msb_arch-3.2.2}/NOTICE +0 -0
  14. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/api.md +0 -0
  15. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/architecture.md +0 -0
  16. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/diagrams.md +0 -0
  17. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/examples.md +0 -0
  18. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/guide.md +0 -0
  19. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/modules/base.md +0 -0
  20. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/modules/mega.md +0 -0
  21. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/modules/super.md +0 -0
  22. {msb_arch-3.2.1 → msb_arch-3.2.2}/docs/modules/utils.md +0 -0
  23. {msb_arch-3.2.1 → msb_arch-3.2.2}/pyproject.toml +0 -0
  24. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/base/__init__.py +0 -0
  25. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/base/basecontainer.py +0 -0
  26. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/base/baseentity.py +0 -0
  27. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/catalogue.py +0 -0
  28. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/errors.py +0 -0
  29. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/interceptors.py +0 -0
  30. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/mega/__init__.py +0 -0
  31. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/mega/manipulator.py +0 -0
  32. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/pipeline.py +0 -0
  33. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/protocols.py +0 -0
  34. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/py.typed +0 -0
  35. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/results.py +0 -0
  36. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/scaffold.py +0 -0
  37. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/super/__init__.py +0 -0
  38. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/super/builtins.py +0 -0
  39. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/super/project.py +0 -0
  40. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/super/super.py +0 -0
  41. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/utils/__init__.py +0 -0
  42. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/utils/logging_setup.py +0 -0
  43. {msb_arch-3.2.1 → msb_arch-3.2.2}/src/msb_arch/utils/validation.py +0 -0
  44. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/README.md +0 -0
  45. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/__init__.py +0 -0
  46. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/integration/__init__.py +0 -0
  47. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/integration/test_integration.py +0 -0
  48. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/performance/__init__.py +0 -0
  49. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/performance/test_benchmarks.py +0 -0
  50. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/performance/test_performance.py +0 -0
  51. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_adapters.py +0 -0
  52. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_aggregate_rules_and_copies.py +0 -0
  53. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_all.py +0 -0
  54. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_apply_methods_and_batch.py +0 -0
  55. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_async_surface.py +0 -0
  56. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_basecontainer.py +0 -0
  57. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_baseentity.py +0 -0
  58. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_builtin_operations.py +0 -0
  59. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_catalogue.py +0 -0
  60. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_compiled_validators.py +0 -0
  61. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_concurrency.py +0 -0
  62. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_constraints.py +0 -0
  63. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_declared_defaults.py +0 -0
  64. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_declared_fields_of_collections.py +0 -0
  65. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_deferred_operations.py +0 -0
  66. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_deprecations.py +0 -0
  67. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_documentation.py +0 -0
  68. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_errors.py +0 -0
  69. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_interceptors.py +0 -0
  70. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_invariants.py +0 -0
  71. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_manipulator.py +0 -0
  72. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_model_graph.py +0 -0
  73. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_persistence.py +0 -0
  74. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_pipeline.py +0 -0
  75. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_project.py +0 -0
  76. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_protocols.py +0 -0
  77. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_provenance.py +0 -0
  78. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_readonly_cache.py +0 -0
  79. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_replay_address.py +0 -0
  80. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_response.py +0 -0
  81. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_revision.py +0 -0
  82. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_scaffold.py +0 -0
  83. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_serialization_round_trip.py +0 -0
  84. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_super.py +0 -0
  85. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_super_argument_binding.py +0 -0
  86. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_typevar_resolution.py +0 -0
  87. {msb_arch-3.2.1 → msb_arch-3.2.2}/tests/test_utils_functions.py +0 -0
@@ -13,6 +13,55 @@ 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
+
16
65
  ## [3.2.1] - 2026-10-21
17
66
 
18
67
  ### Fixed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: msb_arch
3
- Version: 3.2.1
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.1-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.1
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.1-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.1
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.1
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.1"
54
+ __version__ = "3.2.2"
@@ -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
@@ -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
@@ -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