unx-immutable 1.0.0

Allows to make class and instance attributes immutable, supports a few different modes.

python package: immutable

Package implements a few different modes of object immutability.

• License
• Repository
  • Versioning
  • Branch strategy
• Quick introduction
• Immutability flags
  • ImmutabilityMode
• Immutability implementation
  • ImmutableClass
  • ImmutableObject
  • Immutable

License

This project is licensed under the Apache License 2.0.

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 .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 represents exceptions used by the package
• mode.py defines different immutability modes.
• 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:

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 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:

fm = ImmutableMode().seal().freeze_none()

Code example:

    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).

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:

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:

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)