private-attribute-cpp 3.0.3__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.3 → private_attribute_cpp-3.1.0}/PKG-INFO +78 -21
  2. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/README.md +77 -20
  3. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/private_attribute.cpp +548 -432
  4. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/private_attribute.pyi +41 -27
  5. {private_attribute_cpp-3.0.3 → 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.3 → private_attribute_cpp-3.1.0}/CMakeLists.txt +0 -0
  9. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/LICENSE +0 -0
  10. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/picosha2.h +0 -0
  11. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_attr_classify_owner.py +0 -0
  12. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_class_private_attrs.py +0 -0
  13. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_gc_collect.py +0 -0
  14. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_init_subclass.py +0 -0
  15. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_private_abc.py +0 -0
  16. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_private_attrs.py +0 -0
  17. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_private_func.py +0 -0
  18. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_private_inheritance.py +0 -0
  19. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_private_method.py +0 -0
  20. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_private_super.py +0 -0
  21. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_private_wrap.py +0 -0
  22. {private_attribute_cpp-3.0.3 → private_attribute_cpp-3.1.0}/tests/test_slots_cycle.py +0 -0
  23. {private_attribute_cpp-3.0.3 → 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.3
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. |
@@ -398,10 +459,6 @@ class MyClass(private_attribute.PrivateAttrBase):
398
459
  __setattr__ = private_attribute.create_slot("__setattr__")()
399
460
  ```
400
461
 
401
- > The old `prepare` / `postprocess` pair and `register_metaclass` are
402
- > deprecated (they emit a warning) and kept only for backward compatibility;
403
- > new code should use `create_new`.
404
-
405
462
  ---
406
463
 
407
464
  ## Behavioral notes & limitations
@@ -428,15 +485,16 @@ class MyClass(private_attribute.PrivateAttrBase):
428
485
  - **v2.2.0** — a subclass must not define, in its own class body, a name that is
429
486
  private to a parent, unless it declares the name in its own
430
487
  `__private_attrs__` or opts in with `use_parents=True`.
431
- - **v2.2.1** — `prepare` locks private-attribute-type creation so only one type
432
- is being built (`type.__new__`) at a time; `postprocess` unlocks it. The lock
433
- is released automatically on failure. (Deprecated; see `create_new`.)
434
- - **v2.2.3** — prefer the `with` form of `prepare`/`postprocess` to guarantee
435
- the lock is released. (Deprecated; see `create_new`.)
436
488
  - CPython may reset the special-method slot descriptors (e.g. when you assign
437
489
  `__getattribute__` / `__setattr__`). Use `ensure_type` (or
438
490
  `ensure_metaclass`) to re-inject them, and avoid setting those methods on
439
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.
440
498
  - **v3** — private attribute interception is implemented through C-struct
441
499
  descriptors installed as `__getattribute__` / `__getattr__` / `__setattr__` /
442
500
  `__delattr__` / `__del__` (and `__call__` on registered metaclasses), rather
@@ -445,8 +503,6 @@ class MyClass(private_attribute.PrivateAttrBase):
445
503
  id records attribute names already confirmed non-private, so they go
446
504
  straight to the user callback without re-classification. Registered types and
447
505
  created types must be heap types (static types are rejected).
448
- - `register_metaclass` requires a metaclass that supports weak references.
449
- (Deprecated; use `create_new`, which registers the metaclass automatically.)
450
506
  - Do **not** set `__static_attributes__` on a private-attribute class; it is
451
507
  removed automatically.
452
508
 
@@ -484,7 +540,8 @@ python -m pytest tests/ -v
484
540
  ```
485
541
 
486
542
  The test suite covers attribute hiding, private methods, class-level private
487
- 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
488
545
  integration, `__slots__`, and GC/cycle-collection regressions.
489
546
 
490
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. |
@@ -388,10 +449,6 @@ class MyClass(private_attribute.PrivateAttrBase):
388
449
  __setattr__ = private_attribute.create_slot("__setattr__")()
389
450
  ```
390
451
 
391
- > The old `prepare` / `postprocess` pair and `register_metaclass` are
392
- > deprecated (they emit a warning) and kept only for backward compatibility;
393
- > new code should use `create_new`.
394
-
395
452
  ---
396
453
 
397
454
  ## Behavioral notes & limitations
@@ -418,15 +475,16 @@ class MyClass(private_attribute.PrivateAttrBase):
418
475
  - **v2.2.0** — a subclass must not define, in its own class body, a name that is
419
476
  private to a parent, unless it declares the name in its own
420
477
  `__private_attrs__` or opts in with `use_parents=True`.
421
- - **v2.2.1** — `prepare` locks private-attribute-type creation so only one type
422
- is being built (`type.__new__`) at a time; `postprocess` unlocks it. The lock
423
- is released automatically on failure. (Deprecated; see `create_new`.)
424
- - **v2.2.3** — prefer the `with` form of `prepare`/`postprocess` to guarantee
425
- the lock is released. (Deprecated; see `create_new`.)
426
478
  - CPython may reset the special-method slot descriptors (e.g. when you assign
427
479
  `__getattribute__` / `__setattr__`). Use `ensure_type` (or
428
480
  `ensure_metaclass`) to re-inject them, and avoid setting those methods on
429
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.
430
488
  - **v3** — private attribute interception is implemented through C-struct
431
489
  descriptors installed as `__getattribute__` / `__getattr__` / `__setattr__` /
432
490
  `__delattr__` / `__del__` (and `__call__` on registered metaclasses), rather
@@ -435,8 +493,6 @@ class MyClass(private_attribute.PrivateAttrBase):
435
493
  id records attribute names already confirmed non-private, so they go
436
494
  straight to the user callback without re-classification. Registered types and
437
495
  created types must be heap types (static types are rejected).
438
- - `register_metaclass` requires a metaclass that supports weak references.
439
- (Deprecated; use `create_new`, which registers the metaclass automatically.)
440
496
  - Do **not** set `__static_attributes__` on a private-attribute class; it is
441
497
  removed automatically.
442
498
 
@@ -474,7 +530,8 @@ python -m pytest tests/ -v
474
530
  ```
475
531
 
476
532
  The test suite covers attribute hiding, private methods, class-level private
477
- 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
478
535
  integration, `__slots__`, and GC/cycle-collection regressions.
479
536
 
480
537
  ---