unx-immutable 1.0.0__tar.gz

unx_immutable-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+Copyright 2025 Paul <unixator unixator@proton.me>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+---
+AI USE NOTICE
+This project allows its code to be analyzed or used in machine-learning
+and AI systems. However, any reproduction or redistribution of generated
+code that substantially copies this source without attribution constitutes
+a violation of the License’s attribution requirements.
+

unx_immutable-1.0.0/PKG-INFO

@@ -0,0 +1,358 @@
+Metadata-Version: 2.4
+Name: unx-immutable
+Version: 1.0.0
+Summary: Allows to make class and instance attributes immutable, supports a few different modes.
+Keywords: immutable,frozen,freezable,readonly
+Author: Paul
+Author-email: Paul <unixator@proton.me>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Maintainer: Paul
+Maintainer-email: Paul <unixator@proton.me>
+Requires-Python: >=3.13
+Project-URL: Repository, https://codeberg.org/unixator/immutable.py
+Project-URL: Documentation, https://codeberg.org/unixator/immutable.py/src/branch/release/README.md
+Project-URL: Issues, https://codeberg.org/unixator/immutable.py/issues
+Project-URL: Changelog, https://codeberg.org/unixator/immutable.py/src/branch/release/CHANGELOG.md
+Project-URL: Mirror, https://gitlab.com/unixator/immutable.py
+Description-Content-Type: text/markdown
+
+# python package: immutable
+Package implements a few different modes of object immutability.
+
+
+- [License](#license)
+- [Repository](#repository)
+  - [Versioning](#versioning)
+  - [Branch strategy](#branch-strategy)
+- [Quick introduction](#quick-introduction)
+- [Immutability flags](#immutability-flags)
+  - [ImmutabilityMode](#immutabilitymode)
+- [Immutability implementation](#objects)
+  - [ImmutableClass](#immutableclass)
+  - [ImmutableObject](#immutableobject)
+  - [Immutable](#immutable)
+
+
+
+## License
+This project is licensed under the [Apache License 2.0](./LICENSE).
+
+  The author permits this code to be used for AI training, analysis, and
+  research. However, reproducing this source code or its derivatives without
+  proper attribution violates the Apache 2.0 License.
+
+
+## Repository
+The main repository is: https://codeberg.org/unixator/immutable.py
+Mirror on GitLab: https://gitlab.com/unixator/immutable.py
+
+
+### Versioning
+The next versioning scheme `vX.Y.Z` is used, where:
+- `X`: (major) reflects current stable version of interface.
+  - It must be increased in case of incompatible changes, when the code that use this package must be updated to use the new version.
+  - 0: means developing stage, so it can become incompatible without increasing major part of version.
+  - 1: is going to be the first stable release version.
+- `Y`: (minor) it must be changed with new added functionalities which do not break compatibility.
+- `Z`: (patch): for fixes/improvements which does not change anything to the end users (internal improvements).
+
+> additional flags are not supported like +build or -rc, -beta, etc.
+
+
+
+### Branch strategy
+Branch agreement:
+- The `release` branch:
+  - It's the default branch which contain only stable versions of package (Merge request only for stable code).
+  - all stable versions have signed annotated tag to help distinguish commits pointing to the stable version.
+  - all tagged versions have releases (codeberg/gitlab/pypi)
+- 0.x.x: Developing branch which will be removed after releasing 1.x.x.
+- 1.x.x: Current LTS release.
+  - 1.x.x means <n>.x.x where "x.x" is just a str, not pointer to the acutal version. Only the first (major) number is going to be changed.
+  - Branch always point to the latest 1.x.x stable version.
+  - For now 1.x.x and release should be the same
+- The `RC` branch:
+  - This branch contains the newest release candidate version of the package, which have not been released yet.
+  - Code in this branch should be tested and covered with unittests if applicable, it's like open-beta stage.
+  - When code is merged here, the version is already bumped.
+- Any other branches should be threated as developing ones and are not recommended for using until one knows what they are doing.
+
+
+
+
+## Quick introduction
+- [exceptions.py](src/unx/immutable/exceptions.py) represents exceptions used by the package
+- [mode.py](src/unx/immutable/mode.py) defines different immutability modes.
+- [obj.py](src/unx/immutable/obj.py) provides base clases/metaclasses to apply immutability modes to the objects.
+
+All entities can be imported from the `__init__.py` directly, so there is no need to import all files.
+Quick example how to create a custom class, where class attributes are frozen during class creating, and instance attributes are frozen after initialization:
+```python
+from unx.immutable import ImmutableError, Immutable, IMMUTABLE
+
+class A(Immutable, mode=IMMUTABLE):
+  cls_attr1: int = 15
+
+  def __init__(self):
+    self.instance_attr1 = "Attr"
+    self.immutability.freeze()
+
+try:
+  A.cls_attr1 = 42
+  A.instance_attr1 = "New str"
+except ImmutableError:
+  print("it happens on the class attribute but it's too late for both")
+```
+
+
+
+## Immutability flags
+
+Instead of using one **"read-only"** flag to mark an object as immutable,
+the package supports a few immutability flags for different object's parts to give more flexibility to freeze them independently.
+
+Flags are defined as number constants but set of flags is represented as a single unsigned integer
+where one flag takes one bit and **0** means no restrictions.
+
+> Please, do not use numbers directly to choose a mode.
+> In the [mode.py](src/unx/immutable/mode.py) file there are pre-defined constants for all supported flags and their naming consistency is garanteed.
+> For instance the `IMMUTABLE` constant always means all flags are raised so the actual value depends on the amount of flags.
+
+
+Next table represents list of supported constants, flag ids, and short description:
+| ID | CONSTANT NAME         | DESCRIPTION |
+| -- | :-----------:         | :---------- |
+|  0 | `UNRESTRICTED`        | No flags are raised, no restrictions are applied, The target class must not be restricted. |
+|  1 | `NO_DEL`              | The `ImmutableError` exception is raised to prevent any attribute/item deletion. |
+|  2 | `NO_NEW`              | The `ImmutableError` is raised if new attr/item is going to be added. |
+|  3 | `SEALED`              | The same as `NO_NEW \| NO_DEL`); no attr/item deletion or adding. |
+|  4 | `IMMUTABLE_NONE`      | The `None` values cannot be replaced with other. |
+|  8 | `IMMUTABLE_EMPTY`     | The **"EMPTY"** (`not bool(value)`) values cannot be modified. |
+| 16 | `IMMUTABLE_EVALUATED` | Already defined values (`bool(value)`) cannot be modified. |
+| 28 | `IMMUTABLE_EXISTED`   | Combination of the `IMMUTABLE_NONE \| IMMUTABLE_EMPTY \| IMMUTABLE_EVALUATED`, all existing attrs/items are immutable. |
+| 31 | `IMMUTABLE`           | `SEALED \| IMMUTABLE_EXISTED` gives full immutability. |
+
+
+> All constants can be imported directly: `from unx.immutable import IMMUTABLE, IMMUTABLE_EXISTED, SEALED`
+
+
+
+### ImmutabilityMode
+The `ImmutabilityMode` class has been created to store immutability flags under one namespace,
+provide methods to raise separate flags, and properties to read their state.
+
+This class is only about storing and managing but not restricting anything by itself.
+
+
+> **Invariant:** The state is monotonic — flags can only be raised, up to full immutability and never lowered.
+
+
+All methods that raise flags return `self`.
+So, method calls can be chained, for example:
+```python
+fm = ImmutableMode().seal().freeze_none()
+```
+
+
+Code example:
+```python
+    mode1 = ImmutabilityMode(11)  # not recommended to use numbers directly, adding new flags in the future can break such code.
+    mode2 = ImmutabilityMode(IMMUTABLE_NONE | SEALED)
+    mode3 = ImmutabilityMode().freeze_none().seal()
+    assert mode1 == mode2 == mode3  # modes are comparable
+    assert ImmutabilityMode(SEALED) < ImmutabilityMode(IMMUTABLE_NONE)
+    assert ImmutabilityMode().seal() < ImmutabilityMode().freeze_none()
+
+    mode = ImmutabilityMode()  # by default mode is UNRESTRICTED (0), no flags are raised.
+    assert bool(mode) is False  # False means no flags have been raised.
+    assert mode.state == 0  # the current mode
+    assert bool(ImmutabilityMode().forbid_new()) is True  # since NO_NEW flag has been raised.
+
+    assert mode.immutable_none is False  # Shows if the IMMUTABLE_NONE flag is raised.
+    assert mode.immutable_empty is False
+    assert mode.immutable_evaluated is False
+    assert mode.immutable_existed is False
+    assert mode.sealed is False
+    assert mode.no_new is False
+    assert mode.no_del is False
+    assert mode.immutable is False  # it's True when all flags are raised, so it's IMMUTABLE
+
+    mode.freeze_none()  # Raise the IMMUTABLE_NONE flag
+    mode.freeze_empty()
+    mode.freeze_evaluated()
+    mode.freeze_existed()
+    mode.forbid_new_attrs()
+    mode.forbid_attrs_removing()
+    mode.seal()
+    mode.freeze()  # Raise all flags
+```
+
+
+
+## Objects
+
+`obj.py` file provides one metaclass and two classes to add read-only functionality for python objects.
+
+All classes support all defined flags and use `ImmutabilityMode` as flag management point.
+For any forbidden modification the `ImmutableError` exception is raised.
+
+
+### ImmutableClass
+This metaclass should be used to add immutability at the class level to restrict **class** attributes.
+
+When a custom class use `ImmutableClass` as metaclass,
+it has `cls_immutability` attribute which is an instance of the `ImmutabilityMode` class.
+
+
+> It's possible to freeze class at the definition stage by using the mode keyword in a class definition (see examples bellow).
+
+```python
+from unx.immutable import ImmutableClass, ImmutabilityMode
+class A(metaclass=ImmutableClass, mode=ImmutabilityMode().freeze()):
+    attr = "value"
+
+assert A.attr == "value"
+try:
+    A.attr = None
+except ImmutableError:
+    print("Class is immutable and cannot be modified.")
+
+#---------------------------------------------
+# other ways to freeze at the definition level
+class A(metaclass=ImmutableClass, mode=ImmutabilityMode().freeze_none().seal()):...
+class A(metaclass=ImmutableClass, mode=ImmutabilityMode(IMMUTABLE_NONE | SEALED)):...
+class A(metaclass=ImmutableClass, mode=IMMUTABLE_NONE | SEALED):...
+
+class A(metaclass=ImmutableClass, mode=ImmutabilityMode().seal()):
+  attr = "value"
+
+# this works because none of the modification flags have been raised.
+# SEALED (NO_NEW actually) forbids only adding new attributes, but not modifying existing ones.
+assert A.attr == "value"
+A.attr = None
+assert A.attr == None
+
+try:
+    A.attr2 = True
+except ImmutableError:
+    print("Class is sealed, so new attributes cannot be assigned.")
+
+
+#---------------------------------------------
+# For postponed freezing.
+class A(metaclass=ImmutableClass):...
+
+assert bool(A.cls_immutability) is False
+# new attributes can be defined.
+A.attr1 = None
+A.attr2 = True
+A.attr3 = 0
+
+# None
+A.cls_immutability.freeze_none()
+assert A.cls_immutability.immutable_none is True
+assert bool(A.cls_immutability) is True
+A.attr3 = 1
+
+try:
+  A.attr1 = 42
+except ImmutableError:
+    print("Raised IMMUTABLE_NONE flag fobids any atribute modifications with the None value.")
+
+
+# evaluated
+A.cls_immutability.freeze_evaluated()
+assert A.cls_immutability.immutable_evaluated is True
+assert A.cls_immutability.immutable_existed is True
+A.attr4 = "still work for now"
+try:
+  A.attr3 = 2
+except ImmutableError:
+    print("Raised IMMUTABLE_EVALUATED and IMMUTABLE_NONE flags fobid any atribute modifications.")
+
+
+A.cls_immutability.seal()
+assert A.cls_immutability.sealed is True
+
+
+A.cls_immutability.freeze()
+assert A.cls_immutability.immutable is True
+```
+
+
+
+
+
+
+### ImmutableObject
+
+`ImmutableObject` class should be used as base for those custom classes which take care
+to add read-only functionality for the new objects/instances of the class rather than class itself.
+
+> `ImmutableObject` adds `immutability` attribute which is instance of the `ImmutabilityMode` class to manage read-only flags for objects.
+
+
+Examples:
+```python
+class SealedDataclass(ImmutableObject):
+    def __init__(self):
+        self.attr1 = 42
+        self.attr2 = True
+        self.immutability.seal()
+
+obj = SealedDataclass()
+obj.attr1 = 24
+obj.attr2 = False
+
+try:
+  A.attr3 = 2
+except ImmutableError:
+    print("obj is sealed and cannot apply new attrs.")
+
+
+#-----------------------------------
+class CustomData(ImmutableObject):...
+    def __init__(self):
+      self.immutability.freeze_evaluated()
+
+obj = CustomData()
+d1 = {"a1": 1, "a2": 2}
+d2 = {"a1": 5, "a3": 3}
+
+for k, v in d1.items():
+    setattr(obj, k, v)
+
+try:
+    for k, v in d2.items():
+        setattr(obj, k, v)
+except ImmutableError:
+    print("failed on a1=5, because it's forbidden to override existing attributes with value other than None.")
+```
+
+
+
+
+### Immutable
+The `Immutable` class is just a quick way to get read-only functionality on both (instance and class) levels.
+Its definition is `class Immutable(ImmutableObject, metaclass=ImmutableClass)...`
+
+Custom class based on this one, have both attributes: `cls_immutability` at the class level, and `immutability` at the instance one.
+
+This is recommended way to use this module, since freezing both prevents some mistakes when instance have an attr with the same name as class have.
+
+
+
+Next simplified example shows how to get instance which prevents overriding existing values:
+```python
+class Template(Immutable, mode=IMMUTABLE):
+  def __init__(self, **kwargs):
+    self.immutability.freeze_existed()
+    for attr_name, val in kwargs.items():
+      setattr(self, attr_name, val)
+```