unx-immutable 1.3.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
• Modes
  • Immutability flags
  • ImmutabilityMode
• Object immutability
  • Classes
    • ImmutableClass
    • ImmutableObject
    • Immutable
  • Decorators
    • slots_only
    • freeze
    • seal
    • immutability
• ImmutableDict

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 default branch which is for the only stable code and points to the last release.
  • for every new official release vx.x.x signed annotated tag is created.
  • documentation update can be merged without tag creation, no need to bump version for README.
  • all tagged versions have created releases on codeberg/pypi
  • rc branch is used as a main source for releases.
  • fast_forward merge strategy is used for merging from the rc branch.
• 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
  • it's already created to indicate that when 2.x.x come, this branch still be supported.
• 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 ready to use, well tested and covered with unittests if applicable.
  • Documentation should be updated and describe new changes.
  • When code is merged to this branch, the version is already bumped.
  • rc branch is the main point to create feature/fix branches for contributing.
  • gpg signed merge commit with squashing is used for merging into the rc branch.
• Any other branches should be threated as developing ones and are not recommended for using until one knows what they are doing.

For contribution use the rc branch as the main source to clone and create a pull request.

Quick introduction

• mode.py defines different immutability modes.
• obj.py provides base clases/metaclasses to apply immutability modes to the objects.
• dict.py provides ImmutableDict class what is a dict but with immutability attribute.

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 immutable during class creating, and instance attributes become immutable after initialization:

from unx.immutable import ImmutableAttrError, Immutable, IMMUTABLE

class A(Immutable, mode=IMMUTABLE):
  cls_attr1: int = 15

  def __init__(self):
      super().__init__()
      self.instance_attr1 = "Attr"
      self.immutability.freeze()

# class attrs
try:
    A.cls_attr1 = 42
except ImmutableAttrError:
    print("it happens on the class attribute")

try:
    A.instance_attr1 = property(lambda x: 42)
except ImmutableAttrError:
    print("Class immutability also protects from such code as well since all changes is already prohibited.")

# instance attrs
a = A()
try:
    a.instance_attr1 = True
except ImmutableAttrError:
    print("This time instance_attr1 in instance of the class is frozen")