accretive 4.2__tar.gz → 4.3__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.
- accretive-4.3/.gitignore +7 -0
- {accretive-4.2 → accretive-4.3}/PKG-INFO +13 -8
- {accretive-4.2 → accretive-4.3}/README.rst +6 -0
- {accretive-4.2 → accretive-4.3}/pyproject.toml +30 -13
- accretive-4.3/sources/accretive/README.md +263 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/__/imports.py +3 -1
- {accretive-4.2 → accretive-4.3}/sources/accretive/__/nomina.py +11 -19
- {accretive-4.2 → accretive-4.3}/sources/accretive/__init__.py +2 -2
- {accretive-4.2 → accretive-4.3}/sources/accretive/classes.py +9 -9
- {accretive-4.2 → accretive-4.3}/sources/accretive/dictionaries.py +14 -7
- {accretive-4.2 → accretive-4.3}/sources/accretive/iclasses.py +13 -1
- accretive-4.2/.gitignore +0 -15
- {accretive-4.2 → accretive-4.3}/LICENSE.txt +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/__/__init__.py +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/__/dictionaries.py +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/__/doctab.py +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/__/exceptions.py +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/_typedecls/__builtins__.pyi +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/exceptions.py +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/modules.py +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/namespaces.py +0 -0
- {accretive-4.2 → accretive-4.3}/sources/accretive/py.typed +0 -0
accretive-4.3/.gitignore
ADDED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: accretive
|
|
3
|
-
Version: 4.
|
|
3
|
+
Version: 4.3
|
|
4
4
|
Summary: Accretive data structures.
|
|
5
5
|
Project-URL: Homepage, https://github.com/emcd/python-accretive
|
|
6
6
|
Project-URL: Documentation, https://emcd.github.io/python-accretive
|
|
@@ -15,17 +15,16 @@ Classifier: Development Status :: 5 - Production/Stable
|
|
|
15
15
|
Classifier: Intended Audience :: Developers
|
|
16
16
|
Classifier: License :: OSI Approved :: Apache Software License
|
|
17
17
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
-
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
20
18
|
Classifier: Programming Language :: Python :: 3.12
|
|
21
19
|
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
22
22
|
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
23
|
-
Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
24
23
|
Classifier: Topic :: Software Development
|
|
25
|
-
Requires-Python: >=3.
|
|
24
|
+
Requires-Python: >=3.12
|
|
26
25
|
Requires-Dist: absence~=1.1
|
|
27
|
-
Requires-Dist: classcore~=1.
|
|
28
|
-
Requires-Dist: dynadoc~=1.
|
|
26
|
+
Requires-Dist: classcore~=1.15
|
|
27
|
+
Requires-Dist: dynadoc~=1.4
|
|
29
28
|
Requires-Dist: typing-extensions
|
|
30
29
|
Description-Content-Type: text/x-rst
|
|
31
30
|
|
|
@@ -278,6 +277,9 @@ Other Projects by This Author 🌟
|
|
|
278
277
|
* `python-classcore <https://github.com/emcd/python-classcore>`_ (`classcore <https://pypi.org/project/classcore/>`_ on PyPI)
|
|
279
278
|
|
|
280
279
|
🏭 A Python library package which provides **foundational class factories and decorators** for providing classes with attributes immutability and concealment and other custom behaviors.
|
|
280
|
+
* `python-detextive <https://github.com/emcd/python-detextive>`_ (`detextive <https://pypi.org/project/detextive/>`_ on PyPI)
|
|
281
|
+
|
|
282
|
+
🕵️ A Python library which provides consolidated text detection capabilities for reliable content analysis. Offers MIME type detection, character set detection, and line separator processing.
|
|
281
283
|
* `python-dynadoc <https://github.com/emcd/python-dynadoc>`_ (`dynadoc <https://pypi.org/project/dynadoc/>`_ on PyPI)
|
|
282
284
|
|
|
283
285
|
📝 A Python library package which bridges the gap between **rich annotations** and **automatic documentation generation** with configurable renderers and support for reusable fragments.
|
|
@@ -290,6 +292,9 @@ Other Projects by This Author 🌟
|
|
|
290
292
|
* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ on PyPI)
|
|
291
293
|
|
|
292
294
|
🍦 **Flavorful Debugging** - A Python library which enhances the powerful and well-known ``icecream`` package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.
|
|
295
|
+
* `python-librovore <https://github.com/emcd/python-librovore>`_ (`librovore <https://pypi.org/project/librovore/>`_ on PyPI)
|
|
296
|
+
|
|
297
|
+
🐲 **Documentation Search Engine** - An intelligent documentation search and extraction tool that provides both a command-line interface for humans and an MCP (Model Context Protocol) server for AI agents. Search across Sphinx and MkDocs sites with fuzzy matching, extract clean markdown content, and integrate seamlessly with AI development workflows.
|
|
293
298
|
* `python-mimeogram <https://github.com/emcd/python-mimeogram>`_ (`mimeogram <https://pypi.org/project/mimeogram/>`_ on PyPI)
|
|
294
299
|
|
|
295
300
|
📨 A command-line tool for **exchanging collections of files with Large Language Models** - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.
|
|
@@ -247,6 +247,9 @@ Other Projects by This Author 🌟
|
|
|
247
247
|
* `python-classcore <https://github.com/emcd/python-classcore>`_ (`classcore <https://pypi.org/project/classcore/>`_ on PyPI)
|
|
248
248
|
|
|
249
249
|
🏭 A Python library package which provides **foundational class factories and decorators** for providing classes with attributes immutability and concealment and other custom behaviors.
|
|
250
|
+
* `python-detextive <https://github.com/emcd/python-detextive>`_ (`detextive <https://pypi.org/project/detextive/>`_ on PyPI)
|
|
251
|
+
|
|
252
|
+
🕵️ A Python library which provides consolidated text detection capabilities for reliable content analysis. Offers MIME type detection, character set detection, and line separator processing.
|
|
250
253
|
* `python-dynadoc <https://github.com/emcd/python-dynadoc>`_ (`dynadoc <https://pypi.org/project/dynadoc/>`_ on PyPI)
|
|
251
254
|
|
|
252
255
|
📝 A Python library package which bridges the gap between **rich annotations** and **automatic documentation generation** with configurable renderers and support for reusable fragments.
|
|
@@ -259,6 +262,9 @@ Other Projects by This Author 🌟
|
|
|
259
262
|
* `python-icecream-truck <https://github.com/emcd/python-icecream-truck>`_ (`icecream-truck <https://pypi.org/project/icecream-truck/>`_ on PyPI)
|
|
260
263
|
|
|
261
264
|
🍦 **Flavorful Debugging** - A Python library which enhances the powerful and well-known ``icecream`` package with flavored traces, configuration hierarchies, customized outputs, ready-made recipes, and more.
|
|
265
|
+
* `python-librovore <https://github.com/emcd/python-librovore>`_ (`librovore <https://pypi.org/project/librovore/>`_ on PyPI)
|
|
266
|
+
|
|
267
|
+
🐲 **Documentation Search Engine** - An intelligent documentation search and extraction tool that provides both a command-line interface for humans and an MCP (Model Context Protocol) server for AI agents. Search across Sphinx and MkDocs sites with fuzzy matching, extract clean markdown content, and integrate seamlessly with AI development workflows.
|
|
262
268
|
* `python-mimeogram <https://github.com/emcd/python-mimeogram>`_ (`mimeogram <https://pypi.org/project/mimeogram/>`_ on PyPI)
|
|
263
269
|
|
|
264
270
|
📨 A command-line tool for **exchanging collections of files with Large Language Models** - bundle multiple files into a single clipboard-ready document while preserving directory structure and metadata... good for code reviews, project sharing, and LLM interactions.
|
|
@@ -13,11 +13,11 @@ description = 'Accretive data structures.'
|
|
|
13
13
|
dynamic = [ 'version' ]
|
|
14
14
|
license = 'Apache-2.0'
|
|
15
15
|
readme = { 'file' = 'README.rst', 'content-type' = 'text/x-rst' }
|
|
16
|
-
requires-python = '>= 3.
|
|
16
|
+
requires-python = '>= 3.12'
|
|
17
17
|
dependencies = [
|
|
18
18
|
'absence~=1.1',
|
|
19
|
-
'classcore~=1.
|
|
20
|
-
'dynadoc~=1.
|
|
19
|
+
'classcore~=1.15',
|
|
20
|
+
'dynadoc~=1.4',
|
|
21
21
|
'typing-extensions',
|
|
22
22
|
# --- BEGIN: Injected by Copier ---
|
|
23
23
|
# --- END: Injected by Copier ---
|
|
@@ -28,12 +28,11 @@ classifiers = [ # https://pypi.org/classifiers
|
|
|
28
28
|
'License :: OSI Approved :: Apache Software License',
|
|
29
29
|
'Programming Language :: Python :: 3 :: Only',
|
|
30
30
|
# --- BEGIN: Injected by Copier ---
|
|
31
|
-
'Programming Language :: Python :: 3.10',
|
|
32
|
-
'Programming Language :: Python :: 3.11',
|
|
33
31
|
'Programming Language :: Python :: 3.12',
|
|
34
32
|
'Programming Language :: Python :: 3.13',
|
|
33
|
+
'Programming Language :: Python :: 3.14',
|
|
34
|
+
'Programming Language :: Python :: 3.15',
|
|
35
35
|
'Programming Language :: Python :: Implementation :: CPython',
|
|
36
|
-
'Programming Language :: Python :: Implementation :: PyPy',
|
|
37
36
|
# --- END: Injected by Copier ---
|
|
38
37
|
'Topic :: Software Development',
|
|
39
38
|
]
|
|
@@ -92,15 +91,15 @@ strict-naming = false
|
|
|
92
91
|
# --- BEGIN: Injected by Copier ---
|
|
93
92
|
# --- END: Injected by Copier ---
|
|
94
93
|
[tool.hatch.envs.default]
|
|
95
|
-
python = '3.
|
|
94
|
+
python = '3.12'
|
|
96
95
|
[tool.hatch.envs.develop]
|
|
97
96
|
description = ''' Development environment. '''
|
|
97
|
+
builder = true
|
|
98
98
|
dependencies = [
|
|
99
|
-
'Jinja2',
|
|
100
99
|
'coverage[toml]',
|
|
101
100
|
'furo',
|
|
102
101
|
'isort',
|
|
103
|
-
'
|
|
102
|
+
'myst-parser',
|
|
104
103
|
'pre-commit',
|
|
105
104
|
'pyright',
|
|
106
105
|
'pytest',
|
|
@@ -128,13 +127,23 @@ docsgen = [
|
|
|
128
127
|
"""sphinx-build -a -d .auxiliary/caches/sphinx --quiet \
|
|
129
128
|
documentation .auxiliary/artifacts/sphinx-html""",
|
|
130
129
|
]
|
|
130
|
+
fragments = [
|
|
131
|
+
"""python .auxiliary/scripts/validate-fragments.py""",
|
|
132
|
+
]
|
|
133
|
+
module-sizes = [
|
|
134
|
+
"""python .auxiliary/scripts/validate-module-sizes.py""",
|
|
135
|
+
]
|
|
131
136
|
linters = [
|
|
132
137
|
"""ruff check --quiet sources documentation tests""",
|
|
138
|
+
# External install only (e.g. uv tool install): a develop dependency
|
|
139
|
+
# cycles for packages below emcd-vibe-linter in the stack.
|
|
140
|
+
#"""vibelinter check""",
|
|
133
141
|
# --- BEGIN: Injected by Copier ---
|
|
134
142
|
# --- END: Injected by Copier ---
|
|
135
143
|
"""isort --check-only --diff sources tests""",
|
|
136
|
-
"""vulture""",
|
|
137
144
|
"""pyright sources""",
|
|
145
|
+
'fragments',
|
|
146
|
+
'module-sizes',
|
|
138
147
|
]
|
|
139
148
|
packagers = [
|
|
140
149
|
"""hatch build""",
|
|
@@ -171,11 +180,10 @@ description = ''' Quality assurance environment. '''
|
|
|
171
180
|
template = 'develop'
|
|
172
181
|
[[tool.hatch.envs.qa.matrix]]
|
|
173
182
|
python = [
|
|
174
|
-
'3.10',
|
|
175
|
-
'3.11',
|
|
176
183
|
'3.12',
|
|
177
184
|
'3.13',
|
|
178
|
-
'
|
|
185
|
+
'3.14',
|
|
186
|
+
'3.15',
|
|
179
187
|
]
|
|
180
188
|
[tool.hatch.version]
|
|
181
189
|
path = 'sources/accretive/__init__.py'
|
|
@@ -348,6 +356,15 @@ directory = 'repair'
|
|
|
348
356
|
name = 'Repairs'
|
|
349
357
|
showcontent = true
|
|
350
358
|
|
|
359
|
+
[tool.vibelinter]
|
|
360
|
+
context = 3
|
|
361
|
+
exclude_paths = [ '.auxiliary/**', '.venv/**', 'tests/**', ]
|
|
362
|
+
|
|
363
|
+
[tool.vibelinter.rules.VBL201]
|
|
364
|
+
hub_patterns = [
|
|
365
|
+
'__init__.py', '__main__.py', '__.py', '__/imports.py', '__/nomina.py',
|
|
366
|
+
]
|
|
367
|
+
|
|
351
368
|
[tool.vulture]
|
|
352
369
|
paths = [ '.auxiliary/configuration/vulturefood.py', 'sources' ]
|
|
353
370
|
min_confidence = 60
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
# Accretive Architecture
|
|
2
|
+
|
|
3
|
+
Accretive provides a family of data structures that enforce a grow-only
|
|
4
|
+
constraint: values can be added but never modified or removed once set. This
|
|
5
|
+
library addresses the need for collections that accumulate state with
|
|
6
|
+
immutability guarantees, useful for configuration registries, plugin systems,
|
|
7
|
+
and scenarios requiring sticky state.
|
|
8
|
+
|
|
9
|
+
## Core Architectural Concept
|
|
10
|
+
|
|
11
|
+
The library implements accretion through attribute assignment interception at
|
|
12
|
+
the metaclass level. When an assignment is attempted, the system checks whether
|
|
13
|
+
the attribute already exists and whether it is marked as mutable. If the
|
|
14
|
+
attribute exists and is not mutable, an exception is raised.
|
|
15
|
+
|
|
16
|
+
## Major Components
|
|
17
|
+
|
|
18
|
+
The architecture is organized into four primary component categories:
|
|
19
|
+
|
|
20
|
+
### Accretive Dictionaries
|
|
21
|
+
|
|
22
|
+
Mapping-based collections that prevent modification of existing entries:
|
|
23
|
+
|
|
24
|
+
- **AbstractDictionary**: Base class defining the accretive dictionary
|
|
25
|
+
interface. Implements `collections.abc.Mapping` with custom `__setitem__`
|
|
26
|
+
to enforce immutability of existing entries.
|
|
27
|
+
- **Dictionary**: Standard accretive dictionary implementation. Supports
|
|
28
|
+
initialization from multiple iterables and keyword arguments.
|
|
29
|
+
- **ProducerDictionary**: Auto-generates values for missing keys via factory
|
|
30
|
+
function. Similar to `collections.defaultdict` with accretive behavior.
|
|
31
|
+
- **ValidatorDictionary**: Validates entries before addition using predicate
|
|
32
|
+
function. Invalid entries are rejected rather than added.
|
|
33
|
+
- **ProducerValidatorDictionary**: Combines producer and validator behaviors.
|
|
34
|
+
Generated values must pass validation before being stored.
|
|
35
|
+
|
|
36
|
+
### Accretive Namespaces
|
|
37
|
+
|
|
38
|
+
Attribute-based containers modeled after `types.SimpleNamespace`:
|
|
39
|
+
|
|
40
|
+
- **Namespace**: Allows dynamic attribute addition with immutability after
|
|
41
|
+
assignment. Uses custom metaclass to intercept attribute assignment via
|
|
42
|
+
`__setattr__` and `__delattr__`.
|
|
43
|
+
|
|
44
|
+
### Accretive Classes
|
|
45
|
+
|
|
46
|
+
Metaclasses and decorators for creating user-defined accretive types:
|
|
47
|
+
|
|
48
|
+
- **Class**: Standard metaclass for classes with accretive instances.
|
|
49
|
+
- **Dataclass**: Metaclass for dataclasses with immutable instances.
|
|
50
|
+
- **DataclassMutable**: Metaclass for dataclasses with mutable instance
|
|
51
|
+
attributes but immutable class-level behavior.
|
|
52
|
+
- **Object**: Concrete class providing standard accretive behavior via
|
|
53
|
+
composition rather than metaclass.
|
|
54
|
+
|
|
55
|
+
These leverage the `classcore` library's class factory system to provide
|
|
56
|
+
consistent behavior configuration across all class types.
|
|
57
|
+
|
|
58
|
+
### Accretive Modules
|
|
59
|
+
|
|
60
|
+
Runtime module reclassification for enforcing module-level immutability:
|
|
61
|
+
|
|
62
|
+
- **Module**: Accretive variant of `types.ModuleType`.
|
|
63
|
+
- **finalize_module**: Utility to reclassify existing modules as accretive,
|
|
64
|
+
optionally processing entire package hierarchies recursively.
|
|
65
|
+
|
|
66
|
+
## Component Relationships
|
|
67
|
+
|
|
68
|
+
### Architecture Layers
|
|
69
|
+
|
|
70
|
+
The system is organized in layers of abstraction:
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
┌─────────────────────────────────────────────────────────┐
|
|
74
|
+
│ Public API Layer │
|
|
75
|
+
│ (dictionaries, namespaces, classes, modules) │
|
|
76
|
+
└─────────────────────────────────────────────────────────┘
|
|
77
|
+
│
|
|
78
|
+
↓
|
|
79
|
+
┌─────────────────────────────────────────────────────────┐
|
|
80
|
+
│ Behavior Implementation Layer (iclasses) │
|
|
81
|
+
│ (assign_attribute_if_absent_mutable) │
|
|
82
|
+
└─────────────────────────────────────────────────────────┘
|
|
83
|
+
│
|
|
84
|
+
↓
|
|
85
|
+
┌─────────────────────────────────────────────────────────┐
|
|
86
|
+
│ Foundation Layer (classcore) │
|
|
87
|
+
│ (class_factory, assigner system) │
|
|
88
|
+
└─────────────────────────────────────────────────────────┘
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### External Dependencies
|
|
92
|
+
|
|
93
|
+
- **classcore**: Provides the class factory system and behavior configuration
|
|
94
|
+
mechanisms. The `class_factory` function creates metaclasses with
|
|
95
|
+
configurable attribute assignment interceptors.
|
|
96
|
+
- **dynadoc**: Automatic docstring generation from type annotations and
|
|
97
|
+
documentation fragments.
|
|
98
|
+
- **absence**: Sentinel value for optional parameters, distinguishing between
|
|
99
|
+
`None` and truly absent values.
|
|
100
|
+
- **frigid**: Immutable data structures used internally for storing
|
|
101
|
+
configuration and metadata.
|
|
102
|
+
|
|
103
|
+
## Key Architectural Patterns
|
|
104
|
+
|
|
105
|
+
### Metaclass-Based Interception
|
|
106
|
+
|
|
107
|
+
All accretive behavior is implemented via metaclass `__setattr__` and
|
|
108
|
+
`__delattr__` hooks that delegate to the `assigner_core` function. This
|
|
109
|
+
allows consistent behavior across all accretive types while maintaining
|
|
110
|
+
compatibility with standard Python semantics.
|
|
111
|
+
|
|
112
|
+
### Assignment Core Strategy
|
|
113
|
+
|
|
114
|
+
The `assign_attribute_if_absent_mutable` function implements the core logic:
|
|
115
|
+
|
|
116
|
+
1. Check if attribute exists via a non-invoking probe
|
|
117
|
+
(`inspect.getattr_static`, so caching descriptors cannot re-enter
|
|
118
|
+
the assigner) with slot storage consulted for slot descriptors
|
|
119
|
+
2. If absent, allow assignment
|
|
120
|
+
3. If present, check immutability behaviors configuration
|
|
121
|
+
4. Check mutables exclusions (names, predicates, regexes)
|
|
122
|
+
5. If not mutable, raise `AttributeImmutability` exception
|
|
123
|
+
6. Otherwise, allow assignment
|
|
124
|
+
|
|
125
|
+
### Cascading Import Hub Pattern
|
|
126
|
+
|
|
127
|
+
The `__` subpackage centralizes all external imports, providing consistent
|
|
128
|
+
namespace management and reducing import duplication. All modules use
|
|
129
|
+
`from . import __` to access common dependencies.
|
|
130
|
+
|
|
131
|
+
## Data Flow
|
|
132
|
+
|
|
133
|
+
### Entry Addition Flow (Dictionaries)
|
|
134
|
+
|
|
135
|
+
1. User calls `dict[key] = value` or `dict.update(...)`
|
|
136
|
+
2. `__setitem__` checks if key exists
|
|
137
|
+
3. If key exists, raises `EntryImmutability` exception
|
|
138
|
+
4. If key absent, calls `_pre_setitem_` for validation
|
|
139
|
+
5. Calls `_store_item_` to persist entry
|
|
140
|
+
6. Entry becomes immutable
|
|
141
|
+
|
|
142
|
+
### Attribute Assignment Flow (Namespaces, Classes, Modules)
|
|
143
|
+
|
|
144
|
+
1. User assigns `obj.attr = value` or `del obj.attr`
|
|
145
|
+
2. Metaclass intercepts via `__setattr__` or `__delattr__`
|
|
146
|
+
3. Delegates to `assign_attribute_if_absent_mutable`
|
|
147
|
+
4. Function checks existence and mutability status
|
|
148
|
+
5. If immutable and exists, raises `AttributeImmutability` exception
|
|
149
|
+
6. Otherwise completes assignment/deletion
|
|
150
|
+
|
|
151
|
+
## Performance Considerations
|
|
152
|
+
|
|
153
|
+
- **Import Centralization**: The `__` pattern front-loads import costs to
|
|
154
|
+
package initialization time rather than individual module import time.
|
|
155
|
+
- **Attribute Lookup**: Immutability checks require metadata lookups
|
|
156
|
+
(behaviors, mutables predicates) on each assignment attempt. Cached lookups
|
|
157
|
+
minimize this overhead.
|
|
158
|
+
- **Dictionary Storage**: Uses standard `dict` internally for O(1) lookups.
|
|
159
|
+
|
|
160
|
+
## Error Handling Strategy
|
|
161
|
+
|
|
162
|
+
The package defines a clear exception hierarchy rooted in `Omniexception`:
|
|
163
|
+
|
|
164
|
+
- **Omnierror**: Base for all operational errors
|
|
165
|
+
- **AttributeImmutability**: Raised when attempting to modify immutable
|
|
166
|
+
attributes (inherits from `AttributeError` and `TypeError`)
|
|
167
|
+
- **EntryImmutability**: Raised when attempting to modify dictionary entries
|
|
168
|
+
- **EntryInvalidity**: Raised when validation fails in validator dictionaries
|
|
169
|
+
- **ErrorProvideFailure**: Raised when error class lookup fails
|
|
170
|
+
|
|
171
|
+
This design allows both specific exception handling (catch
|
|
172
|
+
`AttributeImmutability`) and general handling (catch `Omnierror`).
|
|
173
|
+
|
|
174
|
+
## Project Structure
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
python-accretive/
|
|
178
|
+
├── LICENSE.txt # Project license
|
|
179
|
+
├── README.rst # Project overview and quick start
|
|
180
|
+
├── pyproject.toml # Python packaging and tool configuration
|
|
181
|
+
├── documentation/ # Sphinx documentation source
|
|
182
|
+
├── sources/ # All source code
|
|
183
|
+
├── tests/ # Test suites
|
|
184
|
+
└── .auxiliary/ # Development workspace
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
### Package Layout
|
|
188
|
+
|
|
189
|
+
```text
|
|
190
|
+
sources/
|
|
191
|
+
└── accretive/ # Main Python package
|
|
192
|
+
├── __/ # Centralized import hub
|
|
193
|
+
│ ├── __init__.py # Re-exports core utilities
|
|
194
|
+
│ ├── dictionaries.py # Internal dictionary utilities and type aliases
|
|
195
|
+
│ ├── doctab.py # Documentation fragment table
|
|
196
|
+
│ ├── exceptions.py # Internal exception utilities
|
|
197
|
+
│ ├── imports.py # External library imports
|
|
198
|
+
│ └── nomina.py # Package-specific naming constants
|
|
199
|
+
├── __init__.py # Package entry point
|
|
200
|
+
├── py.typed # Type checking marker
|
|
201
|
+
├── classes.py # Accretive class metaclasses and decorators
|
|
202
|
+
├── dictionaries.py # Accretive dictionary implementations
|
|
203
|
+
├── exceptions.py # Package exception hierarchy
|
|
204
|
+
├── iclasses.py # Internal class implementations
|
|
205
|
+
├── modules.py # Accretive module implementation
|
|
206
|
+
└── namespaces.py # Accretive namespace implementation
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
All package modules use the `__` import hub pattern for consistent
|
|
210
|
+
namespace management and reduced import duplication.
|
|
211
|
+
|
|
212
|
+
## Design Rationale
|
|
213
|
+
|
|
214
|
+
### Why Accretive (Grow-Only) Semantics?
|
|
215
|
+
|
|
216
|
+
The library implements accretive (grow-only) semantics rather than other
|
|
217
|
+
immutability patterns:
|
|
218
|
+
|
|
219
|
+
| Pattern | Trade-off |
|
|
220
|
+
|---------|-----------|
|
|
221
|
+
| **Fully immutable** | No growth after initialization (frozen dataclasses, tuples) |
|
|
222
|
+
| **Copy-on-write** | Performance overhead, memory consumption |
|
|
223
|
+
| **Persistent data structures** | Complexity, unfamiliar APIs |
|
|
224
|
+
| **Accretive (grow-only)** | Middle ground — values accumulate but never change |
|
|
225
|
+
|
|
226
|
+
Accretive semantics are useful for registries, plugin systems, caches, and
|
|
227
|
+
configuration objects where state must accumulate reliably but never be
|
|
228
|
+
modified or removed once set. This provides clear use case differentiation
|
|
229
|
+
from fully immutable libraries like `frigid`.
|
|
230
|
+
|
|
231
|
+
### Why Metaclass-Based Interception?
|
|
232
|
+
|
|
233
|
+
Alternatives considered:
|
|
234
|
+
|
|
235
|
+
- **Descriptors**: Only work for class-level attributes, not instance attributes
|
|
236
|
+
- **Direct `__setattr__` override**: Doesn't integrate well with class factory pattern
|
|
237
|
+
- **Proxies**: Add indirection and complicate type checking
|
|
238
|
+
|
|
239
|
+
Metaclass interception via `__setattr__` and `__delattr__` hooks provides
|
|
240
|
+
consistent behavior across all accretive types while maintaining compatibility
|
|
241
|
+
with standard Python semantics and classcore's class factory system.
|
|
242
|
+
|
|
243
|
+
### Why classcore Integration?
|
|
244
|
+
|
|
245
|
+
Building on classcore's `class_factory` and behavior configuration system
|
|
246
|
+
rather than implementing from scratch provides:
|
|
247
|
+
|
|
248
|
+
- Consistent configuration API across all types (Class, Dataclass, Module, etc.)
|
|
249
|
+
- Reuse of well-tested behavior management code
|
|
250
|
+
- Integration with dynadoc and behavior exclusions (mutables predicates/regexes)
|
|
251
|
+
|
|
252
|
+
### Why Multiple Inheritance for Exceptions?
|
|
253
|
+
|
|
254
|
+
Exceptions inherit from both the package base (`Omnierror`) and appropriate
|
|
255
|
+
standard library exceptions (`AttributeError`, `TypeError`, `ValueError`).
|
|
256
|
+
This enables both specific handling (`catch AttributeImmutability`) and
|
|
257
|
+
general handling (`catch Omnierror`) while remaining compatible with
|
|
258
|
+
standard exception hierarchies.
|
|
259
|
+
|
|
260
|
+
## Sister Projects
|
|
261
|
+
|
|
262
|
+
- **[classcore](https://github.com/emcd/python-classcore)** — Foundational class factory and behavior system. Provides the metaclass machinery that accretive delegates to.
|
|
263
|
+
- **[frigid](https://github.com/emcd/python-frigid)** — Fully immutable data structures. Like accretive, but values cannot be added or changed after creation.
|
|
@@ -27,6 +27,7 @@ import abc
|
|
|
27
27
|
import collections.abc as cabc
|
|
28
28
|
import dataclasses as dcls
|
|
29
29
|
import functools as funct
|
|
30
|
+
import inspect
|
|
30
31
|
import types
|
|
31
32
|
|
|
32
33
|
import classcore.exceptions as ccexc
|
|
@@ -37,5 +38,6 @@ import typing_extensions as typx
|
|
|
37
38
|
# --- BEGIN: Injected by Copier ---
|
|
38
39
|
# --- END: Injected by Copier ---
|
|
39
40
|
|
|
40
|
-
|
|
41
41
|
from absence import AbsentSingleton, Absential, absent, is_absent
|
|
42
|
+
# --- BEGIN: Injected by Copier ---
|
|
43
|
+
# --- END: Injected by Copier ---
|
|
@@ -29,15 +29,21 @@ from . import imports as __
|
|
|
29
29
|
from classcore.standard.nomina import ( # isort: skip
|
|
30
30
|
AssignerLigation,
|
|
31
31
|
AttributesNamer,
|
|
32
|
+
AttrnameCalculator,
|
|
32
33
|
BehaviorExclusionNamesOmni,
|
|
33
34
|
BehaviorExclusionRegexes,
|
|
34
35
|
BehaviorExclusionPredicates,
|
|
35
36
|
BehaviorExclusionVerifiersOmni,
|
|
37
|
+
ClassDecorator,
|
|
38
|
+
ClassDecorators,
|
|
39
|
+
ClassDecoratorFactory,
|
|
36
40
|
DecorationPreparers as ClassDecorationPreparers,
|
|
37
41
|
DynadocConfiguration,
|
|
38
42
|
ErrorClassProvider,
|
|
43
|
+
ModuleReclassifier,
|
|
39
44
|
concealment_label,
|
|
40
45
|
immutability_label,
|
|
46
|
+
is_public_identifier,
|
|
41
47
|
)
|
|
42
48
|
|
|
43
49
|
|
|
@@ -51,17 +57,6 @@ ComparisonResult: __.typx.TypeAlias = bool | __.types.NotImplementedType
|
|
|
51
57
|
NominativeArguments: __.typx.TypeAlias = __.cabc.Mapping[ str, __.typx.Any ]
|
|
52
58
|
PositionalArguments: __.typx.TypeAlias = __.cabc.Sequence[ __.typx.Any ]
|
|
53
59
|
|
|
54
|
-
# TODO: Import ClassDecorator aliases from 'classcore' once documentation
|
|
55
|
-
# fragments have been removed from them.
|
|
56
|
-
ClassDecorator: __.typx.TypeAlias = (
|
|
57
|
-
__.cabc.Callable[ [ type[ U ] ], type[ U ] ] )
|
|
58
|
-
ClassDecorators: __.typx.TypeAlias = (
|
|
59
|
-
__.cabc.Sequence[ ClassDecorator[ U ] ] )
|
|
60
|
-
ClassDecoratorFactory: __.typx.TypeAlias = (
|
|
61
|
-
__.cabc.Callable[ ..., ClassDecorator[ U ] ] )
|
|
62
|
-
ModuleReclassifier: __.typx.TypeAlias = __.cabc.Callable[
|
|
63
|
-
[ __.cabc.Mapping[ str, __.typx.Any ] ], None ]
|
|
64
|
-
|
|
65
60
|
DictionaryNominativeArgument: __.typx.TypeAlias = __.typx.Annotated[
|
|
66
61
|
V,
|
|
67
62
|
__.ddoc.Doc(
|
|
@@ -90,11 +85,8 @@ DictionaryValidator: __.typx.TypeAlias = __.typx.Annotated[
|
|
|
90
85
|
package_name = __name__.split( '.', maxsplit = 1 )[ 0 ]
|
|
91
86
|
|
|
92
87
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
def is_public_identifier( name: str ) -> bool:
|
|
99
|
-
''' Is Python identifier public? '''
|
|
100
|
-
return not name.startswith( '_' )
|
|
88
|
+
# Configured with the accretive package prefix. Exposes the
|
|
89
|
+
# ``is_internal_name`` detector consumed by classcore 1.13+
|
|
90
|
+
# metaclass-carried internal-name contributions, so accretive internal
|
|
91
|
+
# names flow into attribute explanations and concealment.
|
|
92
|
+
calculate_attrname = AttrnameCalculator( package_name = package_name )
|
|
@@ -28,8 +28,8 @@
|
|
|
28
28
|
|
|
29
29
|
|
|
30
30
|
from . import __
|
|
31
|
-
# --- BEGIN: Injected by Copier ---
|
|
32
31
|
from . import exceptions
|
|
32
|
+
# --- BEGIN: Injected by Copier ---
|
|
33
33
|
# --- END: Injected by Copier ---
|
|
34
34
|
|
|
35
35
|
from .classes import *
|
|
@@ -39,7 +39,7 @@ from .namespaces import *
|
|
|
39
39
|
|
|
40
40
|
|
|
41
41
|
__version__: __.typx.Annotated[ str, __.ddoc.Visibilities.Reveal ]
|
|
42
|
-
__version__ = '4.
|
|
42
|
+
__version__ = '4.3'
|
|
43
43
|
|
|
44
44
|
|
|
45
45
|
finalize_module( __name__, dynadoc_table = __.fragments, recursive = True )
|
|
@@ -27,16 +27,16 @@ from . import __
|
|
|
27
27
|
from . import iclasses as _iclasses
|
|
28
28
|
|
|
29
29
|
|
|
30
|
-
|
|
31
|
-
visibles_default = _iclasses.visibles_default
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
_abc_class_mutables = (
|
|
30
|
+
abc_class_mutables = (
|
|
35
31
|
'_abc_cache',
|
|
36
32
|
'_abc_negative_cache',
|
|
37
33
|
'_abc_negative_cache_version',
|
|
38
34
|
'_abc_registry',
|
|
39
35
|
)
|
|
36
|
+
mutables_default = _iclasses.mutables_default
|
|
37
|
+
visibles_default = _iclasses.visibles_default
|
|
38
|
+
|
|
39
|
+
|
|
40
40
|
_class_factory = __.funct.partial(
|
|
41
41
|
__.ccstd.class_factory,
|
|
42
42
|
assigner_core = _iclasses.assign_attribute_if_absent_mutable,
|
|
@@ -239,7 +239,7 @@ class DataclassObjectMutable(
|
|
|
239
239
|
class Protocol(
|
|
240
240
|
__.typx.Protocol,
|
|
241
241
|
metaclass = _iclasses.ProtocolClass,
|
|
242
|
-
class_mutables =
|
|
242
|
+
class_mutables = abc_class_mutables,
|
|
243
243
|
instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable,
|
|
244
244
|
):
|
|
245
245
|
''' Standard base protocol class. '''
|
|
@@ -253,7 +253,7 @@ class Protocol(
|
|
|
253
253
|
class ProtocolMutable(
|
|
254
254
|
__.typx.Protocol,
|
|
255
255
|
metaclass = _iclasses.ProtocolClass,
|
|
256
|
-
class_mutables =
|
|
256
|
+
class_mutables = abc_class_mutables,
|
|
257
257
|
instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable,
|
|
258
258
|
instances_mutables = '*',
|
|
259
259
|
):
|
|
@@ -268,7 +268,7 @@ class ProtocolMutable(
|
|
|
268
268
|
class DataclassProtocol(
|
|
269
269
|
__.typx.Protocol,
|
|
270
270
|
metaclass = _iclasses.ProtocolDataclass,
|
|
271
|
-
class_mutables =
|
|
271
|
+
class_mutables = abc_class_mutables,
|
|
272
272
|
instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable,
|
|
273
273
|
):
|
|
274
274
|
''' Standard base protocol dataclass. '''
|
|
@@ -282,7 +282,7 @@ class DataclassProtocol(
|
|
|
282
282
|
class DataclassProtocolMutable(
|
|
283
283
|
__.typx.Protocol,
|
|
284
284
|
metaclass = _iclasses.ProtocolDataclassMutable,
|
|
285
|
-
class_mutables =
|
|
285
|
+
class_mutables = abc_class_mutables,
|
|
286
286
|
instances_assigner_core = _iclasses.assign_attribute_if_absent_mutable,
|
|
287
287
|
):
|
|
288
288
|
''' Base protocol dataclass with mutable instance attributes. '''
|
|
@@ -96,15 +96,15 @@ class AbstractDictionary( __.cabc.Mapping[ __.H, __.V ] ):
|
|
|
96
96
|
|
|
97
97
|
@__.abc.abstractmethod
|
|
98
98
|
def __iter__( self ) -> __.cabc.Iterator[ __.H ]:
|
|
99
|
-
raise NotImplementedError # pragma: no
|
|
99
|
+
raise NotImplementedError # pragma: no cover
|
|
100
100
|
|
|
101
101
|
@__.abc.abstractmethod
|
|
102
102
|
def __len__( self ) -> int:
|
|
103
|
-
raise NotImplementedError # pragma: no
|
|
103
|
+
raise NotImplementedError # pragma: no cover
|
|
104
104
|
|
|
105
105
|
@__.abc.abstractmethod
|
|
106
106
|
def __getitem__( self, key: __.H ) -> __.V:
|
|
107
|
-
raise NotImplementedError # pragma: no
|
|
107
|
+
raise NotImplementedError # pragma: no cover
|
|
108
108
|
|
|
109
109
|
def _pre_setitem_(
|
|
110
110
|
self, key: __.H, value: __.V
|
|
@@ -118,7 +118,7 @@ class AbstractDictionary( __.cabc.Mapping[ __.H, __.V ] ):
|
|
|
118
118
|
@__.abc.abstractmethod
|
|
119
119
|
def _store_item_( self, key: __.H, value: __.V ) -> None:
|
|
120
120
|
''' Stores entry in underlying storage. '''
|
|
121
|
-
raise NotImplementedError # pragma: no
|
|
121
|
+
raise NotImplementedError # pragma: no cover
|
|
122
122
|
|
|
123
123
|
def __setitem__( self, key: __.H, value: __.V ) -> None:
|
|
124
124
|
key, value = self._pre_setitem_( key, value )
|
|
@@ -184,7 +184,13 @@ class _DictionaryOperations( AbstractDictionary[ __.H, __.V ] ):
|
|
|
184
184
|
|
|
185
185
|
def __ror__( self, other: __.cabc.Mapping[ __.H, __.V ] ) -> __.typx.Self:
|
|
186
186
|
if not isinstance( other, __.cabc.Mapping ): return NotImplemented
|
|
187
|
-
|
|
187
|
+
conflicts = set( other.keys( ) ) & set( self.keys( ) )
|
|
188
|
+
if conflicts:
|
|
189
|
+
from .exceptions import EntryImmutability
|
|
190
|
+
raise EntryImmutability( next( iter( conflicts ) ) )
|
|
191
|
+
data = dict( other )
|
|
192
|
+
data.update( self )
|
|
193
|
+
return self.with_data( data )
|
|
188
194
|
|
|
189
195
|
def __and__(
|
|
190
196
|
self,
|
|
@@ -211,7 +217,7 @@ class _DictionaryOperations( AbstractDictionary[ __.H, __.V ] ):
|
|
|
211
217
|
@__.abc.abstractmethod
|
|
212
218
|
def copy( self ) -> __.typx.Self:
|
|
213
219
|
''' Provides fresh copy of dictionary. '''
|
|
214
|
-
raise NotImplementedError # pragma: no
|
|
220
|
+
raise NotImplementedError # pragma: no cover
|
|
215
221
|
|
|
216
222
|
@__.abc.abstractmethod
|
|
217
223
|
def with_data(
|
|
@@ -220,12 +226,13 @@ class _DictionaryOperations( AbstractDictionary[ __.H, __.V ] ):
|
|
|
220
226
|
**entries: __.DictionaryNominativeArgument[ __.V ],
|
|
221
227
|
) -> __.typx.Self:
|
|
222
228
|
''' Creates new dictionary with same behavior but different data. '''
|
|
223
|
-
raise NotImplementedError # pragma: no
|
|
229
|
+
raise NotImplementedError # pragma: no cover
|
|
224
230
|
|
|
225
231
|
|
|
226
232
|
class Dictionary(
|
|
227
233
|
_DictionaryOperations[ __.H, __.V ],
|
|
228
234
|
metaclass = _classes.AbstractBaseClass,
|
|
235
|
+
class_mutables = _classes.abc_class_mutables,
|
|
229
236
|
):
|
|
230
237
|
''' Accretive dictionary. '''
|
|
231
238
|
|
|
@@ -39,9 +39,21 @@ def assign_attribute_if_absent_mutable( # noqa: PLR0913
|
|
|
39
39
|
value: __.typx.Any,
|
|
40
40
|
) -> None:
|
|
41
41
|
''' Assigns attribute if it is absent or mutable, else raises error. '''
|
|
42
|
-
|
|
42
|
+
# Presence probe must not invoke descriptors: caching descriptors
|
|
43
|
+
# (e.g., Python 3.15 dataclass docstring descriptors) write during
|
|
44
|
+
# reads, which would re-enter this assigner infinitely.
|
|
45
|
+
try:
|
|
46
|
+
static = __.inspect.getattr_static( objct, name )
|
|
47
|
+
except AttributeError:
|
|
43
48
|
ligation( name, value )
|
|
44
49
|
return
|
|
50
|
+
if isinstance( static, __.types.MemberDescriptorType ):
|
|
51
|
+
# Slot: descriptor exists whether or not it holds a value, and
|
|
52
|
+
# only a slot getter is invocation-safe here, so read directly.
|
|
53
|
+
try: object.__getattribute__( objct, name )
|
|
54
|
+
except AttributeError:
|
|
55
|
+
ligation( name, value )
|
|
56
|
+
return
|
|
45
57
|
leveli = 'instance' if level == 'instances' else level
|
|
46
58
|
behaviors_name = attributes_namer( leveli, 'behaviors' )
|
|
47
59
|
behaviors = __.ccutils.getattr0( objct, behaviors_name, frozenset( ) )
|
accretive-4.2/.gitignore
DELETED
|
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
|