private-attribute-cpp 2.2.9__tar.gz → 3.0.0__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 (21) hide show
  1. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/PKG-INFO +73 -10
  2. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/README.md +72 -9
  3. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/private_attribute.cpp +1497 -441
  4. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/private_attribute.pyi +37 -2
  5. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/pyproject.toml +1 -1
  6. private_attribute_cpp-3.0.0/tests/test_private_super.py +179 -0
  7. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/CMakeLists.txt +0 -0
  8. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/LICENSE +0 -0
  9. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/picosha2.h +0 -0
  10. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_attr_classify_owner.py +0 -0
  11. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_class_private_attrs.py +0 -0
  12. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_gc_collect.py +0 -0
  13. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_init_subclass.py +0 -0
  14. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_private_abc.py +0 -0
  15. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_private_attrs.py +0 -0
  16. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_private_func.py +0 -0
  17. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_private_inheritance.py +0 -0
  18. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_private_method.py +0 -0
  19. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_private_wrap.py +0 -0
  20. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_slots_cycle.py +0 -0
  21. {private_attribute_cpp-2.2.9 → private_attribute_cpp-3.0.0}/tests/test_use_parents.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: private_attribute_cpp
3
- Version: 2.2.9
3
+ Version: 3.0.0
4
4
  Summary: A Python package that provides a way to define private attributes in C++ implementation.
5
5
  Author-Email: HuangHaoHua <13140752715@example.com>
6
6
  License-Expression: MIT
@@ -36,6 +36,7 @@ outside the declaring class's own code.
36
36
  - [Custom name generation (`private_func`)](#custom-name-generation-private_func)
37
37
  - [Decorated methods (`PrivateWrapProxy`)](#decorated-methods-privatewrapproxy)
38
38
  - [Inheritance and `use_parents`](#inheritance-and-use_parents)
39
+ - [Cross-class access (`PrivateSuper` and `PrivateClassSuper`)](#cross-class-access-privatesuper-and-privateclasssuper)
39
40
  - [API reference](#api-reference)
40
41
  - [Custom metaclasses](#custom-metaclasses)
41
42
  - [Behavioral notes & limitations](#behavioral-notes--limitations)
@@ -59,9 +60,10 @@ code that knows (or can guess) the mangled name can still read and mutate your
59
60
  from subclasses and from `getattr`/`hasattr`/`dir`.
60
61
  - Inside the declaring class, they look and behave like ordinary attributes.
61
62
 
62
- It does this by rewriting attribute access in `tp_getattro` / `tp_setattro` and
63
- storing private values under generated, collision-resistant names (a tuple of
64
- two SHA-256 hashes).
63
+ It does this by installing C-struct descriptors for `__getattribute__` /
64
+ `__getattr__` / `__setattr__` / `__delattr__` / `__del__` (and `__call__` on
65
+ registered metaclasses) and storing private values under generated,
66
+ collision-resistant names (a tuple of two SHA-256 hashes).
65
67
 
66
68
  ---
67
69
 
@@ -264,6 +266,57 @@ unchanged; only the internal name set is merged. Default is `False`.
264
266
 
265
267
  ---
266
268
 
269
+ ### Cross-class access (`PrivateSuper` and `PrivateClassSuper`)
270
+
271
+ Since v3.0.0 you can explicitly reach a parent class's class-level private
272
+ attribute — including the value it stored "for" an intermediate class — with
273
+ `PrivateSuper` (instance flavour) or `PrivateClassSuper` (`@classmethod`
274
+ flavour):
275
+
276
+ ```python
277
+ import private_attribute
278
+
279
+ class Grand(private_attribute.PrivateAttrBase):
280
+ __private_attrs__ = ["_g"]
281
+ _g = "grand"
282
+
283
+ @classmethod
284
+ def set_g(cls, value):
285
+ cls._g = value
286
+
287
+ class Mid(Grand):
288
+ __private_attrs__ = ["_m"]
289
+ _m = "mid"
290
+
291
+ class Leaf(Mid, use_parents=True):
292
+ __private_attrs__ = []
293
+
294
+ def read_grand_shadow(self):
295
+ # A=Leaf (running code), B=Grand (owning class), C=Mid (defined-for class)
296
+ return private_attribute.PrivateSuper(Leaf, Grand, Mid, self)._g
297
+
298
+ @classmethod
299
+ def read_grand_shadow_cls(cls):
300
+ return private_attribute.PrivateClassSuper(Leaf, Grand, Mid, cls)._g
301
+
302
+ Mid.set_g("written-on-mid")
303
+ Leaf().read_grand_shadow() # "written-on-mid"
304
+ Leaf.read_grand_shadow_cls() # "written-on-mid"
305
+ ```
306
+
307
+ - `A` — the type whose code is currently running.
308
+ - `B` — a parent type of `A` whose class-level private attribute is accessed.
309
+ - `C` — the class the private value was defined for; it must be `B`, `A`, or a
310
+ class that is both a subclass of `B` and a parent of `A`.
311
+ - the final argument is an instance of `A` (for `PrivateSuper`) or a subclass of
312
+ `A` (for `PrivateClassSuper`).
313
+
314
+ The attribute is resolved from `B`'s class-level storage for `C` and its
315
+ `__get__(obj, A)` (or `__get__(None, cls)`) is invoked. This is for **class-level
316
+ private attributes only** — it is not for instance-attribute cross-type access.
317
+
318
+ ---
319
+
267
320
  ## API reference
268
321
 
269
322
  | Name | Kind | Purpose |
@@ -272,11 +325,13 @@ unchanged; only the internal name set is merged. Default is `False`.
272
325
  | `PrivateAttrType` | metaclass | The metaclass that implements the private-attribute machinery. |
273
326
  | `PrivateWrapProxy(decorator, orig=None)` | decorator | Wrap an arbitrary decorator so it stays private-attribute-aware. |
274
327
  | `_PrivateWrap` | class | Returned by `PrivateWrapProxy`; exposes `.result` and `.funcs`. |
328
+ | `PrivateSuper(A, B, C, obj)` | class | Read a parent class's class-level private attribute defined for another class; calls `__get__(obj, A)`. |
329
+ | `PrivateClassSuper(A, B, C, cls)` | class | Classmethod flavour of `PrivateSuper`; calls `__get__(None, cls)`. |
275
330
  | `prepare(name, bases, attrs, **kwds)` | function | Context manager for building private-attribute classes in a custom metaclass. |
276
331
  | `postprocess(typ, temp)` | function | Finalize a class created via `prepare`. |
277
332
  | `register_metaclass(metaclass)` | function | Register a custom metaclass so it can produce private-attribute classes. |
278
- | `ensure_type(typ)` | function | Reset `tp_getattro`/`tp_setattro`/`tp_finalizer` slots on a type. |
279
- | `ensure_metaclass(metaclass)` | function | Reset the corresponding slots on a metaclass. |
333
+ | `ensure_type(typ)` | function | Re-inject the special-method slot descriptors and `tp_traverse`/`tp_clear` wrappers on a type. |
334
+ | `ensure_metaclass(metaclass)` | function | Re-inject the corresponding slot descriptors and wrappers on a metaclass. |
280
335
 
281
336
  Class-definition options:
282
337
 
@@ -362,10 +417,18 @@ released even if construction fails.
362
417
  is released automatically on failure.
363
418
  - **v2.2.3** — prefer the `with` form of `prepare`/`postprocess` to guarantee
364
419
  the lock is released.
365
- - CPython may change `tp_getattro` / `tp_setattro` when you assign
366
- `__getattribute__` / `__setattr__`. Use `ensure_type` (or `ensure_metaclass`)
367
- to reset those slots, and avoid setting those methods on private-attribute
368
- classes directly.
420
+ - CPython may reset the special-method slot descriptors (e.g. when you assign
421
+ `__getattribute__` / `__setattr__`). Use `ensure_type` (or
422
+ `ensure_metaclass`) to re-inject them, and avoid setting those methods on
423
+ private-attribute classes directly.
424
+ - **v3** — private attribute interception is implemented through C-struct
425
+ descriptors installed as `__getattribute__` / `__getattr__` / `__setattr__` /
426
+ `__delattr__` / `__del__` (and `__call__` on registered metaclasses), rather
427
+ than by directly setting `tp_getattro` / `tp_setattro` / `tp_finalize`. Only
428
+ `tp_traverse` / `tp_clear` are set directly. A public cache keyed by object
429
+ id records attribute names already confirmed non-private, so they go
430
+ straight to the user callback without re-classification. Registered types and
431
+ created types must be heap types (static types are rejected).
369
432
  - `register_metaclass` requires a metaclass that supports weak references.
370
433
  - Do **not** set `__static_attributes__` on a private-attribute class; it is
371
434
  removed automatically.
@@ -26,6 +26,7 @@ outside the declaring class's own code.
26
26
  - [Custom name generation (`private_func`)](#custom-name-generation-private_func)
27
27
  - [Decorated methods (`PrivateWrapProxy`)](#decorated-methods-privatewrapproxy)
28
28
  - [Inheritance and `use_parents`](#inheritance-and-use_parents)
29
+ - [Cross-class access (`PrivateSuper` and `PrivateClassSuper`)](#cross-class-access-privatesuper-and-privateclasssuper)
29
30
  - [API reference](#api-reference)
30
31
  - [Custom metaclasses](#custom-metaclasses)
31
32
  - [Behavioral notes & limitations](#behavioral-notes--limitations)
@@ -49,9 +50,10 @@ code that knows (or can guess) the mangled name can still read and mutate your
49
50
  from subclasses and from `getattr`/`hasattr`/`dir`.
50
51
  - Inside the declaring class, they look and behave like ordinary attributes.
51
52
 
52
- It does this by rewriting attribute access in `tp_getattro` / `tp_setattro` and
53
- storing private values under generated, collision-resistant names (a tuple of
54
- two SHA-256 hashes).
53
+ It does this by installing C-struct descriptors for `__getattribute__` /
54
+ `__getattr__` / `__setattr__` / `__delattr__` / `__del__` (and `__call__` on
55
+ registered metaclasses) and storing private values under generated,
56
+ collision-resistant names (a tuple of two SHA-256 hashes).
55
57
 
56
58
  ---
57
59
 
@@ -254,6 +256,57 @@ unchanged; only the internal name set is merged. Default is `False`.
254
256
 
255
257
  ---
256
258
 
259
+ ### Cross-class access (`PrivateSuper` and `PrivateClassSuper`)
260
+
261
+ Since v3.0.0 you can explicitly reach a parent class's class-level private
262
+ attribute — including the value it stored "for" an intermediate class — with
263
+ `PrivateSuper` (instance flavour) or `PrivateClassSuper` (`@classmethod`
264
+ flavour):
265
+
266
+ ```python
267
+ import private_attribute
268
+
269
+ class Grand(private_attribute.PrivateAttrBase):
270
+ __private_attrs__ = ["_g"]
271
+ _g = "grand"
272
+
273
+ @classmethod
274
+ def set_g(cls, value):
275
+ cls._g = value
276
+
277
+ class Mid(Grand):
278
+ __private_attrs__ = ["_m"]
279
+ _m = "mid"
280
+
281
+ class Leaf(Mid, use_parents=True):
282
+ __private_attrs__ = []
283
+
284
+ def read_grand_shadow(self):
285
+ # A=Leaf (running code), B=Grand (owning class), C=Mid (defined-for class)
286
+ return private_attribute.PrivateSuper(Leaf, Grand, Mid, self)._g
287
+
288
+ @classmethod
289
+ def read_grand_shadow_cls(cls):
290
+ return private_attribute.PrivateClassSuper(Leaf, Grand, Mid, cls)._g
291
+
292
+ Mid.set_g("written-on-mid")
293
+ Leaf().read_grand_shadow() # "written-on-mid"
294
+ Leaf.read_grand_shadow_cls() # "written-on-mid"
295
+ ```
296
+
297
+ - `A` — the type whose code is currently running.
298
+ - `B` — a parent type of `A` whose class-level private attribute is accessed.
299
+ - `C` — the class the private value was defined for; it must be `B`, `A`, or a
300
+ class that is both a subclass of `B` and a parent of `A`.
301
+ - the final argument is an instance of `A` (for `PrivateSuper`) or a subclass of
302
+ `A` (for `PrivateClassSuper`).
303
+
304
+ The attribute is resolved from `B`'s class-level storage for `C` and its
305
+ `__get__(obj, A)` (or `__get__(None, cls)`) is invoked. This is for **class-level
306
+ private attributes only** — it is not for instance-attribute cross-type access.
307
+
308
+ ---
309
+
257
310
  ## API reference
258
311
 
259
312
  | Name | Kind | Purpose |
@@ -262,11 +315,13 @@ unchanged; only the internal name set is merged. Default is `False`.
262
315
  | `PrivateAttrType` | metaclass | The metaclass that implements the private-attribute machinery. |
263
316
  | `PrivateWrapProxy(decorator, orig=None)` | decorator | Wrap an arbitrary decorator so it stays private-attribute-aware. |
264
317
  | `_PrivateWrap` | class | Returned by `PrivateWrapProxy`; exposes `.result` and `.funcs`. |
318
+ | `PrivateSuper(A, B, C, obj)` | class | Read a parent class's class-level private attribute defined for another class; calls `__get__(obj, A)`. |
319
+ | `PrivateClassSuper(A, B, C, cls)` | class | Classmethod flavour of `PrivateSuper`; calls `__get__(None, cls)`. |
265
320
  | `prepare(name, bases, attrs, **kwds)` | function | Context manager for building private-attribute classes in a custom metaclass. |
266
321
  | `postprocess(typ, temp)` | function | Finalize a class created via `prepare`. |
267
322
  | `register_metaclass(metaclass)` | function | Register a custom metaclass so it can produce private-attribute classes. |
268
- | `ensure_type(typ)` | function | Reset `tp_getattro`/`tp_setattro`/`tp_finalizer` slots on a type. |
269
- | `ensure_metaclass(metaclass)` | function | Reset the corresponding slots on a metaclass. |
323
+ | `ensure_type(typ)` | function | Re-inject the special-method slot descriptors and `tp_traverse`/`tp_clear` wrappers on a type. |
324
+ | `ensure_metaclass(metaclass)` | function | Re-inject the corresponding slot descriptors and wrappers on a metaclass. |
270
325
 
271
326
  Class-definition options:
272
327
 
@@ -352,10 +407,18 @@ released even if construction fails.
352
407
  is released automatically on failure.
353
408
  - **v2.2.3** — prefer the `with` form of `prepare`/`postprocess` to guarantee
354
409
  the lock is released.
355
- - CPython may change `tp_getattro` / `tp_setattro` when you assign
356
- `__getattribute__` / `__setattr__`. Use `ensure_type` (or `ensure_metaclass`)
357
- to reset those slots, and avoid setting those methods on private-attribute
358
- classes directly.
410
+ - CPython may reset the special-method slot descriptors (e.g. when you assign
411
+ `__getattribute__` / `__setattr__`). Use `ensure_type` (or
412
+ `ensure_metaclass`) to re-inject them, and avoid setting those methods on
413
+ private-attribute classes directly.
414
+ - **v3** — private attribute interception is implemented through C-struct
415
+ descriptors installed as `__getattribute__` / `__getattr__` / `__setattr__` /
416
+ `__delattr__` / `__del__` (and `__call__` on registered metaclasses), rather
417
+ than by directly setting `tp_getattro` / `tp_setattro` / `tp_finalize`. Only
418
+ `tp_traverse` / `tp_clear` are set directly. A public cache keyed by object
419
+ id records attribute names already confirmed non-private, so they go
420
+ straight to the user callback without re-classification. Registered types and
421
+ created types must be heap types (static types are rejected).
359
422
  - `register_metaclass` requires a metaclass that supports weak references.
360
423
  - Do **not** set `__static_attributes__` on a private-attribute class; it is
361
424
  removed automatically.