agglovar.meta.decorators
========================

.. py:module:: agglovar.meta.decorators

.. autoapi-nested-parse::

   Decorators for common functionality.

   Defines several decorators for adding common functionality to classes and methods.

   Decorators include:

   - `immutable`: Make a class immutable after __init__ completes.
   - `lockable`: Sets a lock flag (o.is_locked) and provides a `lock()` method and on optional `unlock()` method when the
       lock is reversible. The meaning of the lock is up to the class using `lockable`. Object attributes are immutable
       while locked (can be disabled) or are always immutable (`immutable` flag).

   These decorators use instance variables to track state, which are automatically when they collide with variables defined
   in the decorated class.



Functions
---------

.. autoapisummary::

   agglovar.meta.decorators.immutable
   agglovar.meta.decorators.lockable


Module Contents
---------------

.. py:function:: immutable(cls=None)

   Make a class immutable after __init__ completes.


.. py:function:: lockable(cls=None, *, reversible: bool = False, attrs: bool = True, immutable: bool = False, var_name: str = '_lock')

   Make a class lockable so that it is immutable while locked.

   # Creates a lock variable that can be checked to see if the object is locked. Semantics of what "locked" means is
   defined by the class using this decorator. If "attrs" is `True`, then object attributes cannot be modified while
   the object is locked. If "immutable" is `True`, then object attributes cannot be modified at any time.

   A lock variable is added to the class with name `var_name`. If the class defines a variable with the same name, it
   will be renamed to avoid conflicts. For immutable objects, a flag is added to the object so __init__ can modify
   attributes, and the flag is removed after __init__ completes. The flag is called "_lockable_in_init", which is
   also renamed to avoid collisions.

   :param reversible: If True, allow object to be unlocked. Adds an "unlock()" method.
   :param attrs: If True, attributes cannot be modified while the object is locked.
   :param immutable: If True, class attributes are always immutable whether or not the instance is locked.
   :param var_name: Lock variable name. Change if "_lock" is already used by the class.