Metadata-Version: 2.4
Name: private_attribute_cpp
Version: 1.4.4
Summary: A Python package that provides a way to define private attributes in C++ implementation.
Home-page: https://github.com/Locked-chess-official/private_attribute_cpp
Author: HuangHaoHua
Author-email: 13140752715@example.com
License: MIT
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: summary

# Private Attribute (c++ implementation)

## Introduction

This package provide a way to create the private attribute like "C++" does.

## All Base API

```python
from private_attribute import (PrivateAttrBase, PrivateWrapProxy)      # 1 Import public API

def my_generate_func(obj_id, attr_name):                           # 2 Optional: custom name generator
    return f"_hidden_{obj_id}_{attr_name}"

class MyClass(PrivateAttrBase, private_func=my_generate_func):     # 3 Inherit + optional custom generator
    __private_attrs__ = ['a', 'b', 'c', 'result', 'conflicted_name']  # 4 Must declare all private attrs

    def __init__(self):
        self.a = 1
        self.b = 2
        self.c = 3
        self.result = 42                    # deliberately conflicts with internal names

    # Normal methods can freely access private attributes
    def public_way(self):
        print(self.a, self.b, self.c)

    # Real-world case: method wrapped by multiple decorators
    @PrivateWrapProxy(memoize())                                   # 5 Apply any decorator safely
    @PrivateWrapProxy(login_required())                            # 5 Stack as many as needed
    @PrivateWrapProxy(rate_limit(calls=10))                        # 5
    def expensive_api_call(self, x):                               # First definition (will be wrapped)
        def inner(...):
            return some_implementation(self.a, self.b, self.c, x)
        inner(...)
        return heavy_computation(self.a, self.b, self.c, x)

    # Fix decorator order + resolve name conflicts
    @PrivateWrapProxy(expensive_api_call.result.name2, expensive_api_call)    # 6 Chain .result to push decorators down
    @PrivateWrapProxy(expensive_api_call.result.name1, expensive_api_call)    # 6 Resolve conflict with internal names
    def expensive_api_call(self, x):         # Final real implementation
        return heavy_computation(self.a, self.b, self.c, x)


# ====================== Usage ======================
obj = MyClass()
obj.public_way()                    # prints: 1 2 3

print(hasattr(obj, 'a'))            # False – truly hidden from outside
print(obj.expensive_api_call(10))   # works with all decorators applied
```

| # | API | Purpose | Required? |
| --- | ---------------------------------------- | ------------------------------------------------------- | ----------- |
| 1 | PrivateAttrBase | Base class – must inherit | Yes |
| 1 | PrivateWrapProxy | Decorator wrapper for arbitrary decorators | When needed |
| 2 | private_func=callable | Custom hidden-name generator | Optional |
| 3 | Pass private_func in class definition | Same as above | Optional |
| 4 | \_\_private_attrs\_\_ list | Declare which attributes are private | Yes |
| 5 | @PrivateWrapProxy(...) | Make any decorator compatible with private attributes | When needed |
| 6 | method.result.xxx chain + dummy wrap | Fix decorator order and name conflicts | When needed |

## Usage

This is a simple usage about the module:

```python
from private_attribute import PrivateAttrBase

class MyClass(PrivateAttrBase):
    __private_attrs__ = ['a', 'b', 'c']
    def __init__(self):
        self.a = 1
        self.b = 2
        self.c = 3

    def public_way(self):
        print(self.a, self.b, self.c)

obj = MyClass()
obj.public_way()  # (1, 2, 3)

print(hasattr(obj, 'a'))  # False
print(hasattr(obj, 'b'))  # False
print(hasattr(obj, 'c'))  # False
```

All of the attributes in `__private_attrs__` will be hidden from the outside world, and stored by another name.

You can use your function to generate the name. It needs the id of the obj and the name of the attribute:

```python
def my_generate_func(obj_id, attr_name):
    return some_string

class MyClass(PrivateAttrBase, private_func=my_generate_func):
    __private_attrs__ = ['a', 'b', 'c']
    def __init__(self):
        self.a = 1
        self.b = 2
        self.c = 3

    def public_way(self):
        print(self.a, self.b, self.c)

obj = MyClass()
obj.public_way()  # (1, 2, 3)

```

If the method will be decorated, the `property`, `classmethod` and `staticmethod` will be supported.
For the other, you can use the `PrivateWrapProxy` to wrap the function:

```python
from private_attribute import PrivateAttrBase, PrivateWrapProxy

class MyClass(PrivateAttrBase):
    __private_attrs__ = ['a', 'b', 'c']
    @PrivateWrapProxy(decorator1())
    @PrivateWrapProxy(decorator2())
    def method1(self):
        ...

    @PrivateWrapProxy(method1.attr_name, method1) # Use the argument "method1" to save old func
    def method1(self):
        ...

    @PrivateWrapProxy(decorator3())
    def method2(self):
        ...

    @PrivateWrapProxy(method2.attr_name, method2) # Use the argument "method2" to save old func
    def method2(self):
        ...


```

The `PrivateWrapProxy` is a decorator, and it will wrap the function with the decorator. When it decorates the method, it returns a `_PrivateWrap` object.

The `_PrivateWrap` has the public api `result` and `funcs`. `result` returns the original decoratored result and `funcs` returns the tuple of the original functions.

```python
from private_attribute import PrivateAttrBase, PrivateWrapProxy

class MyClass(PrivateAttrBase):
    __private_attrs__ = ['a', 'b', 'c']
    @PrivateWrapProxy(decorator1())
    @PrivateWrapProxy(decorator2())
    def method1(self):
        ...

    @PrivateWrapProxy(method1.result.conflict_attr_name1, method1) # Use the argument "method1" to save old func
    def method1(self):
        ...

    @PrivateWrapProxy(method1.result.conflict_attr_name2, method1)
    def method1(self):
        ...

    @PrivateWrapProxy(decorator3())
    def method2(self):
```

## Advanced API

### define your metaclass based on one metaclass

You can define your metaclass based on one metaclass:

```python
from abc import ABCMeta, abstractmethod
import private_attribute

class PrivateAbcMeta(ABCMeta):
    def __new__(cls, name, bases, attrs, **kwargs):
        temp = private_attribute.prepare(name, bases, attrs, **kwargs)
        typ = super().__new__(cls, temp.name, temp.bases, temp.attrs, **temp.kwds)
        private_attribute.postprocess(typ, temp)
        return typ

private_attribute.register_metaclass(PrivateAbcMeta)
```

By this way you create a metaclass both can behave as ABC and private attribute:

```python
class MyClass(metaclass=PrivateAbcMeta):
    __private_attrs__ = ()
    __slots__ = ()

    @abstractmethod
    def my_function(self): ...

class MyImplement(MyClass):
    __private_attrs__ = ("_a",)
    def __init__(self, value=1):
        self._a = value

    def my_function(self):
        return self._a
```

Finally:

```python
>>> a = MyImplement(1)
>>> a.my_function()
1
>>> a._a
Traceback (most recent call last):
  File "<pyshell#2>", line 1, in <module>
    a._a
AttributeError: private attribute
>>> MyClass()
Traceback (most recent call last):
  File "<pyshell#3>", line 1, in <module>
    MyClass()
TypeError: Can't instantiate abstract class MyClass without an implementation for abstract method 'my_function'
```

## Notes

- All of the private attributes class must contain the `__private_attrs__` attribute.
- The `__private_attrs__` attribute must be a sequence of strings.
- You cannot define the name which in `__slots__` to `__private_attrs__`.
- When you define `__slots__` and `__private_attrs__` in one class, the attributes in `__private_attrs__` can also be defined in the methods, even though they are not in `__slots__`.
- All of the object that is the instance of the class "PrivateAttrBase" or its subclass are default to be unable to be pickled.
- Finally the attributes' names in `__private_attrs__` will be change to a tuple with two hash.
- Finally the `_PrivateWrap` object will be recoveried to the original object.
- One class defined in another class cannot use another class's private attribute.
- One parent class defined an attribute which not in `__private_attrs__` or not a `PrivateAttrType` instance, the child class shouldn't contain the attribute in its `__private_attrs__`.
- CPython may change "tp_getattro", "tp_setattro" and so on when you change the attribute "\_\_getattribute\_\_", "\_\_setattr\_\_" and so on. If you are fear about it, you can use `ensure_type` to reset those tp slots. For the other metaclasses, you can use `ensure_metaclass` to reset those tp slots. Also, don't set those methods on these classes in your code.
- `private_attribute.register_metaclass` must be called with the metaclass which support weakref.

## License

MIT

## Requirement

This package require the c++ module "[picosha2](https://github.com/okdshin/PicoSHA2)" to compute the sha256 hash.

## Support

Now it doesn't support "PyPy".
