https://github.com/simphotonics/lockattrs
Python decorator used to lock class attributes.
https://github.com/simphotonics/lockattrs
attributes locking modifier python3 visibility
Last synced: 2 months ago
JSON representation
Python decorator used to lock class attributes.
- Host: GitHub
- URL: https://github.com/simphotonics/lockattrs
- Owner: simphotonics
- License: bsd-3-clause
- Created: 2021-11-16T20:58:36.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2021-12-01T18:15:49.000Z (over 3 years ago)
- Last Synced: 2025-01-26T03:16:13.420Z (3 months ago)
- Topics: attributes, locking, modifier, python3, visibility
- Language: Python
- Homepage: https://pypi.org/project/lockattrs
- Size: 85.9 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Locking Class Attributes
[](https://github.com/simphotonics/lockattrs/actions/workflows/tests.yml)
[](https://lockattrs.simphotonics.com)
Most object oriented languages (C++, Java, Dart, Kotlin, Swift)
include visibiliy modifiers. This enables
encapsulation where for example the inner workings of a class
can be detached from the outside world and thus protected from
direct modification.
Python on the other hand does not have a language-backed concept
of privacy. Instead functions or variables with an identifier
that starts with an underscore are
deemed private and should not be modified or otherwise
relied upon since they may change in a future version of the module.
In some cases, certain attributes may be crucial for the
correct working a class and the programmer might
want to pervent any inadvertent modification.
The package [`lockattrs`][lockattrs] provides a decorator that can
be used with the method `__setattr__` to lock certain attributes
or all attributes.
Note that despite the name similarity [`lockattrs`][lockattrs] is
not related to the package [`attrs`][attrs] providing
a concise way of creating and validating data classes.
## Installation
To install the package [`lockattrs`][lockattrs] use the command:
```Console
$ pip install lockattrs
```
## Usage
This package provides the decorator function [`protect`][protect] which can be
used to prevent modification of attributes
after they have been initially set.
### 1. Locking Class Attributes
The intended use-case is demonstrated below. Locking the
instance attributes of a meta-class is equivalent to
locking the class attributes of the class (the meta-class instance).
Using the decorator [`protect`][protect] involves the following steps:
1. Declare a meta-class.
2. Override the method `__setattr__`.
3. Decorate `__setattr__` with the function [`protect`][protect].
4. Optionally: Specify which attributes should be locked and
what type of error should be raised during an attribute
modification attempt.
``` Python
from lockattrs import protect
class AMeta(type):
"""
Meta class of A.
"""
@protect(('data','id'), )
def __setattr__(self, name: str, value: Any) -> None:
return super().__setattr__(name, value)
class A(metaclass=AMeta):
id = 'a01'
pass
A.id = 'b02' # Raises an error. Attribute 'id' is set and locked.
A.data = 'initial-data' # First initiation is OK. Attribute 'data' is now locked.
A.data = 'new-data' # Raises an error (default type: ProtectedAttributeError).
A.name = 'A'
A.name = 'A1' # OK, since the attribute 'name' is not locked.
```
### 2. Locking Instance Attributes
The code below demonstrates how to use the decorator
function `@protect` to lock certain attributes of a class instance.
``` Python
from lockattrs import protect
class B():
"""
Sample class with locked attributes.
"""
id = 57
@protect(('data','id'), ) # To lock all attributes use: @protect()
def __setattr__(self, name: str, value: Any) -> None:
return super().__setattr__(name, value)
B.id = 28 # OK. Class attributes are not locked.
# To lock class attributes see section above.
# Creating an instance of B.
b = B()
b.id = 77 # Modification of the attribute 'id' via 'self' raises
# an error since the annotated method `__setattr__` is
# called.
b.data = 'initial-data' # First initiation is OK. Attribute 'data' is now locked.
b.data = 'new-data' # Raises an error (default type: ProtectedAttributeError).
b.name = 'b'
b.name = 'b1' # OK, since the attribute 'name' is not locked.
```
## Performance
Note: Locking certain attributes may be prohibitively
costly in terms of computational time
when used with objects that are
instantiated often (for example in a loop)
and where attributes are set/modified frequently.
The benchmarks below were produced using the package
[`pytest-benchmark`][pytest-benchmark] on a PC with 32GB RAM
and an Intel Core i5-6260U CPU running at 1.80GHz.
As the mean runtimes show, setting an attribute of class `A`
takes approximately 40 times as long compared to a standard class
(without an annotated `__setattr__` method).
``` Console
--------------------------------- benchmark: 2 tests -----------------------------------
Name (time in ns) Mean StdDev Rounds Iterations
----------------------------------------------------------------------------------------
test_benchmark_set_attrs 348.8611 (1.0) 66.8829 (1.0) 4 20000
test_benchmark_set_attrs_A 13,496.0524 (38.69) 912.2178 (13.64) 4 20000
----------------------------------------------------------------------------------------
```
## Features and bugs
Please file feature requests and bugs at the [issue tracker].
Contributions are welcome.
[issue tracker]: https://github.com/simphotonics/lockattrs/issues
[attrs]: https://pypi.org/project/attrs
[protect]: http://lockattrs.simphotonics.com/reference/lockattrs/decorators/#protect
[pypi]: https:://pypi.org
[pytest]: https://pypi.org/project/pytest/
[pytest-benchmark]: https://pypi.org/project/pytest-benchmark/
[lockattrs]: https://github.com/simphotonics/lockattrs