private-attribute-cpp 3.0.4__tar.gz → 3.1.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 (23) hide show
  1. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/PKG-INFO +78 -10
  2. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/README.md +77 -9
  3. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/private_attribute.cpp +441 -51
  4. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/private_attribute.pyi +46 -9
  5. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/pyproject.toml +1 -1
  6. private_attribute_cpp-3.1.0/tests/test_private_metaclass_del.py +120 -0
  7. private_attribute_cpp-3.1.0/tests/test_private_obj_super.py +769 -0
  8. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/CMakeLists.txt +0 -0
  9. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/LICENSE +0 -0
  10. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/picosha2.h +0 -0
  11. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_attr_classify_owner.py +0 -0
  12. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_class_private_attrs.py +0 -0
  13. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_gc_collect.py +0 -0
  14. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_init_subclass.py +0 -0
  15. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_private_abc.py +0 -0
  16. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_private_attrs.py +0 -0
  17. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_private_func.py +0 -0
  18. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_private_inheritance.py +0 -0
  19. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_private_method.py +0 -0
  20. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_private_super.py +0 -0
  21. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_private_wrap.py +0 -0
  22. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.0}/tests/test_slots_cycle.py +0 -0
  23. {private_attribute_cpp-3.0.4 → private_attribute_cpp-3.1.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: 3.0.4
3
+ Version: 3.1.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,7 +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
+ - [Cross-class access (`PrivateSuper`, `PrivateClassSuper`, and `PrivateObjSuper`)](#cross-class-access-privatesuper-privateclasssuper-and-privateobjsuper)
40
40
  - [API reference](#api-reference)
41
41
  - [Custom metaclasses](#custom-metaclasses)
42
42
  - [Behavioral notes & limitations](#behavioral-notes--limitations)
@@ -266,12 +266,19 @@ unchanged; only the internal name set is merged. Default is `False`.
266
266
 
267
267
  ---
268
268
 
269
- ### Cross-class access (`PrivateSuper` and `PrivateClassSuper`)
269
+ ### Cross-class access (`PrivateSuper`, `PrivateClassSuper`, and `PrivateObjSuper`)
270
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):
271
+ Ordinary subclass code cannot see a parent's private attributes. Two explicit
272
+ helpers cover the two places those values live:
273
+
274
+ - **Class-level** storage — `PrivateSuper` and `PrivateClassSuper` (since v3.0.0).
275
+ - **Per-instance** storage — `PrivateObjSuper`.
276
+
277
+ #### Class-level (`PrivateSuper` and `PrivateClassSuper`)
278
+
279
+ `PrivateSuper` (instance flavour) and `PrivateClassSuper` (`@classmethod`
280
+ flavour) reach a parent class's class-level private attribute, including the
281
+ value it stored "for" an intermediate class:
275
282
 
276
283
  ```python
277
284
  import private_attribute
@@ -312,8 +319,61 @@ Leaf.read_grand_shadow_cls() # "written-on-mid"
312
319
  `A` (for `PrivateClassSuper`).
313
320
 
314
321
  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.
322
+ `__get__(obj, A)` (or `__get__(None, cls)`) is invoked. This pair is for
323
+ **class-level private attributes only**.
324
+
325
+ #### Per-instance (`PrivateObjSuper`)
326
+
327
+ `PrivateObjSuper` reads the value a **parent class** stored on a particular
328
+ instance. It does not look at class attributes, and it cannot assign or delete.
329
+
330
+ ```python
331
+ import private_attribute
332
+
333
+ class Parent(private_attribute.PrivateAttrBase):
334
+ __private_attrs__ = ["_secret"]
335
+
336
+ def __init__(self):
337
+ self._secret = 1
338
+
339
+ def get_secret(self):
340
+ return self._secret
341
+
342
+ class Child(Parent):
343
+ __private_attrs__ = ["_secret"]
344
+
345
+ def __init__(self):
346
+ super().__init__()
347
+ self._secret = 99 # Child's own storage
348
+
349
+ def read_own(self):
350
+ return self._secret
351
+
352
+ def read_parent(self):
353
+ # now_class=Child, parent_class=Parent, obj=this instance
354
+ return private_attribute.PrivateObjSuper(Child, Parent, self)._secret
355
+
356
+ obj = Child()
357
+ obj.get_secret() # 1 — parent code sees the parent's value
358
+ obj.read_own() # 99 — child code sees its own value
359
+ obj.read_parent() # 1 — parent's per-instance value, explicitly
360
+ ```
361
+
362
+ - `now_class` — the private-attribute type whose code is running. Access from
363
+ any other code raises `AttributeError`.
364
+ - `parent_class` — a private-attribute **parent** of `now_class` (not
365
+ `now_class` itself). The value is read from that class's storage for `obj`.
366
+ - `obj` — an instance of `now_class`. An instance of a further subclass is
367
+ accepted; an instance of a sibling or of the parent is not.
368
+
369
+ The name must be a private attribute of `parent_class` (or of one of its
370
+ private-attribute ancestors). The lookup does **not** fall back to a class
371
+ attribute, to a descriptor on the class, or to an ancestor's own instance
372
+ storage — pass the class that actually stored the value. A normal instance
373
+ returns the stored object unchanged. When `obj` is itself a class and the
374
+ stored value defines `__get__`, `__get__(None, obj)` is called. Keyword
375
+ arguments are rejected. See the [guide](docs/guide/cross-class-access.md) for
376
+ the error cases.
317
377
 
318
378
  ---
319
379
 
@@ -327,6 +387,7 @@ private attributes only** — it is not for instance-attribute cross-type access
327
387
  | `_PrivateWrap` | class | Returned by `PrivateWrapProxy`; exposes `.result` and `.funcs`. |
328
388
  | `PrivateSuper(A, B, C, obj)` | class | Read a parent class's class-level private attribute defined for another class; calls `__get__(obj, A)`. |
329
389
  | `PrivateClassSuper(A, B, C, cls)` | class | Classmethod flavour of `PrivateSuper`; calls `__get__(None, cls)`. |
390
+ | `PrivateObjSuper(now_class, parent_class, obj)` | class | Read a parent class's per-instance private attribute from subclass code. Read-only; no class-level fallback. |
330
391
  | `create_new(func=None)` | function | Register and control a custom metaclass automatically; placed in the metaclass body (or used as a decorator). |
331
392
  | `create_meta_slot(name)` | function | Create the final slot (e.g. `__setattr__`) for a registered metaclass; empty slot or decorator. |
332
393
  | `create_slot(name)` | function | Create the final slot for a private-attribute class; empty slot or decorator. |
@@ -428,6 +489,12 @@ class MyClass(private_attribute.PrivateAttrBase):
428
489
  `__getattribute__` / `__setattr__`). Use `ensure_type` (or
429
490
  `ensure_metaclass`) to re-inject them, and avoid setting those methods on
430
491
  private-attribute classes directly.
492
+ - **unreleased (after 3.0.4)** — `PrivateObjSuper(now_class, parent_class, obj)`
493
+ reads a parent class's per-instance private attribute from `now_class`'s
494
+ code. It is read-only and does not see class-level private attributes
495
+ (`PrivateSuper` / `PrivateClassSuper` remain the class-level helpers).
496
+ The private-class cache now drops a type's answer when that type is
497
+ collected, so a new type allocated at the same address is classified again.
431
498
  - **v3** — private attribute interception is implemented through C-struct
432
499
  descriptors installed as `__getattribute__` / `__getattr__` / `__setattr__` /
433
500
  `__delattr__` / `__del__` (and `__call__` on registered metaclasses), rather
@@ -473,7 +540,8 @@ python -m pytest tests/ -v
473
540
  ```
474
541
 
475
542
  The test suite covers attribute hiding, private methods, class-level private
476
- state, decorator wrapping, inheritance semantics (`use_parents`), ABC/metaclass
543
+ state, decorator wrapping, inheritance semantics (`use_parents`), cross-class
544
+ access (`PrivateSuper`, `PrivateClassSuper`, `PrivateObjSuper`), ABC/metaclass
477
545
  integration, `__slots__`, and GC/cycle-collection regressions.
478
546
 
479
547
  ---
@@ -26,7 +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
+ - [Cross-class access (`PrivateSuper`, `PrivateClassSuper`, and `PrivateObjSuper`)](#cross-class-access-privatesuper-privateclasssuper-and-privateobjsuper)
30
30
  - [API reference](#api-reference)
31
31
  - [Custom metaclasses](#custom-metaclasses)
32
32
  - [Behavioral notes & limitations](#behavioral-notes--limitations)
@@ -256,12 +256,19 @@ unchanged; only the internal name set is merged. Default is `False`.
256
256
 
257
257
  ---
258
258
 
259
- ### Cross-class access (`PrivateSuper` and `PrivateClassSuper`)
259
+ ### Cross-class access (`PrivateSuper`, `PrivateClassSuper`, and `PrivateObjSuper`)
260
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):
261
+ Ordinary subclass code cannot see a parent's private attributes. Two explicit
262
+ helpers cover the two places those values live:
263
+
264
+ - **Class-level** storage — `PrivateSuper` and `PrivateClassSuper` (since v3.0.0).
265
+ - **Per-instance** storage — `PrivateObjSuper`.
266
+
267
+ #### Class-level (`PrivateSuper` and `PrivateClassSuper`)
268
+
269
+ `PrivateSuper` (instance flavour) and `PrivateClassSuper` (`@classmethod`
270
+ flavour) reach a parent class's class-level private attribute, including the
271
+ value it stored "for" an intermediate class:
265
272
 
266
273
  ```python
267
274
  import private_attribute
@@ -302,8 +309,61 @@ Leaf.read_grand_shadow_cls() # "written-on-mid"
302
309
  `A` (for `PrivateClassSuper`).
303
310
 
304
311
  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.
312
+ `__get__(obj, A)` (or `__get__(None, cls)`) is invoked. This pair is for
313
+ **class-level private attributes only**.
314
+
315
+ #### Per-instance (`PrivateObjSuper`)
316
+
317
+ `PrivateObjSuper` reads the value a **parent class** stored on a particular
318
+ instance. It does not look at class attributes, and it cannot assign or delete.
319
+
320
+ ```python
321
+ import private_attribute
322
+
323
+ class Parent(private_attribute.PrivateAttrBase):
324
+ __private_attrs__ = ["_secret"]
325
+
326
+ def __init__(self):
327
+ self._secret = 1
328
+
329
+ def get_secret(self):
330
+ return self._secret
331
+
332
+ class Child(Parent):
333
+ __private_attrs__ = ["_secret"]
334
+
335
+ def __init__(self):
336
+ super().__init__()
337
+ self._secret = 99 # Child's own storage
338
+
339
+ def read_own(self):
340
+ return self._secret
341
+
342
+ def read_parent(self):
343
+ # now_class=Child, parent_class=Parent, obj=this instance
344
+ return private_attribute.PrivateObjSuper(Child, Parent, self)._secret
345
+
346
+ obj = Child()
347
+ obj.get_secret() # 1 — parent code sees the parent's value
348
+ obj.read_own() # 99 — child code sees its own value
349
+ obj.read_parent() # 1 — parent's per-instance value, explicitly
350
+ ```
351
+
352
+ - `now_class` — the private-attribute type whose code is running. Access from
353
+ any other code raises `AttributeError`.
354
+ - `parent_class` — a private-attribute **parent** of `now_class` (not
355
+ `now_class` itself). The value is read from that class's storage for `obj`.
356
+ - `obj` — an instance of `now_class`. An instance of a further subclass is
357
+ accepted; an instance of a sibling or of the parent is not.
358
+
359
+ The name must be a private attribute of `parent_class` (or of one of its
360
+ private-attribute ancestors). The lookup does **not** fall back to a class
361
+ attribute, to a descriptor on the class, or to an ancestor's own instance
362
+ storage — pass the class that actually stored the value. A normal instance
363
+ returns the stored object unchanged. When `obj` is itself a class and the
364
+ stored value defines `__get__`, `__get__(None, obj)` is called. Keyword
365
+ arguments are rejected. See the [guide](docs/guide/cross-class-access.md) for
366
+ the error cases.
307
367
 
308
368
  ---
309
369
 
@@ -317,6 +377,7 @@ private attributes only** — it is not for instance-attribute cross-type access
317
377
  | `_PrivateWrap` | class | Returned by `PrivateWrapProxy`; exposes `.result` and `.funcs`. |
318
378
  | `PrivateSuper(A, B, C, obj)` | class | Read a parent class's class-level private attribute defined for another class; calls `__get__(obj, A)`. |
319
379
  | `PrivateClassSuper(A, B, C, cls)` | class | Classmethod flavour of `PrivateSuper`; calls `__get__(None, cls)`. |
380
+ | `PrivateObjSuper(now_class, parent_class, obj)` | class | Read a parent class's per-instance private attribute from subclass code. Read-only; no class-level fallback. |
320
381
  | `create_new(func=None)` | function | Register and control a custom metaclass automatically; placed in the metaclass body (or used as a decorator). |
321
382
  | `create_meta_slot(name)` | function | Create the final slot (e.g. `__setattr__`) for a registered metaclass; empty slot or decorator. |
322
383
  | `create_slot(name)` | function | Create the final slot for a private-attribute class; empty slot or decorator. |
@@ -418,6 +479,12 @@ class MyClass(private_attribute.PrivateAttrBase):
418
479
  `__getattribute__` / `__setattr__`). Use `ensure_type` (or
419
480
  `ensure_metaclass`) to re-inject them, and avoid setting those methods on
420
481
  private-attribute classes directly.
482
+ - **unreleased (after 3.0.4)** — `PrivateObjSuper(now_class, parent_class, obj)`
483
+ reads a parent class's per-instance private attribute from `now_class`'s
484
+ code. It is read-only and does not see class-level private attributes
485
+ (`PrivateSuper` / `PrivateClassSuper` remain the class-level helpers).
486
+ The private-class cache now drops a type's answer when that type is
487
+ collected, so a new type allocated at the same address is classified again.
421
488
  - **v3** — private attribute interception is implemented through C-struct
422
489
  descriptors installed as `__getattribute__` / `__getattr__` / `__setattr__` /
423
490
  `__delattr__` / `__del__` (and `__call__` on registered metaclasses), rather
@@ -463,7 +530,8 @@ python -m pytest tests/ -v
463
530
  ```
464
531
 
465
532
  The test suite covers attribute hiding, private methods, class-level private
466
- state, decorator wrapping, inheritance semantics (`use_parents`), ABC/metaclass
533
+ state, decorator wrapping, inheritance semantics (`use_parents`), cross-class
534
+ access (`PrivateSuper`, `PrivateClassSuper`, `PrivateObjSuper`), ABC/metaclass
467
535
  integration, `__slots__`, and GC/cycle-collection regressions.
468
536
 
469
537
  ---