unx-immutable 1.0.0
Allows to make class and instance attributes immutable, supports a few different modes.
Requires Python: >=3.13
Keywords: immutable, frozen, freezable, readonly

# 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)
```