Metadata-Version: 2.4
Name: unx-immutable
Version: 1.3.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)
- [Modes](docs/mode.md)
  - [Immutability flags](docs/mode.md#immutability-flags)
  - [ImmutabilityMode](docs/mode.md#immutabilitymode)
- [Object immutability](docs/objects.md)
  - [Classes](docs/objects.md#classes)
    - [ImmutableClass](docs/objects.md#immutableclass)
    - [ImmutableObject](docs/objects.md#immutableobject)
    - [Immutable](docs/objects.md#immutable)
  - [Decorators](docs/objects.md#decorators)
    - [slots_only](docs/objects.md#slots_only)
    - [freeze](docs/objects.md#freeze)
    - [seal](docs/objects.md#seal)
    - [immutability](docs/objects.md#immutability)
- [ImmutableDict](docs/dict.md#immutabledict)


## 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 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 <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
  - 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](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.
- [dict.py](src/unx/immutable/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:
```python
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")
```
