pyiron_base.interfaces.lockable.Lockable

class pyiron_base.interfaces.lockable.Lockable(*args, lock_method: str = 'error', **kwargs)

Bases: object

A small mixin to lock attribute and method access at runtime.

The mixin maintains an read_only and offers a context manager to temporarily unset it. It does not restrict access to any attributes or methods on its own. Instead sub classes are expected to mark methods they wish protected with sentinel(). Wrapped methods will then raise Locked if read_only is set.

If the subclass also implements HasGroups, locking it will iterate over all nodes and (recursively) groups and lock them if possible and vice-versa for unlocking.

Once an object has been locked it should generally not be expected to be (permanently) unlocked again, especially not explicitely by the user.

Subclasses need to initialize this class by calling the inherited __init__, if explicitely overriding it. When not explicitely overriding it (as in the examples below), take care that either the other super classes call super().__init__ or place this class before them in the inheritance order. Also be sure to initialize it before using methods and properties decorated with sentinel().

Subclasses may override _on_lock() and _on_unlock() if they wish to customize locking/unlocking behaviour, provided that they call super() in their overloads.

Let’s start with a simple example; a list that can be locked

>>> class LockList(Lockable, list):
...   __setitem__ = sentinel(list.__setitem__)
...   clear = sentinel(list.clear)
>>> l = LockList([1,2,3])
>>> l
[1, 2, 3]

Deriving adds the read only flag

>>> l.read_only
False

While it is not set, we may mutate the object

>>> l[2] = 4
>>> l[2]
4

Once it is locked, the wrapped methods will raise errors

>>> l.lock()
>>> l.read_only
True
>>> l[1]
2
>>> l[1] = 4
Traceback (most recent call last):
    ...
lockable.Locked: Object is currently locked!  Use unlocked() if you know what you are doing.

You can lock an object multiple times to no effect

>>> l.lock()

From now on every modification should be done with the unlocked() context manager. It returns the unlocked object itself.

>>> with l.unlocked():
...   l[1] = 4
>>> l[1]
4
>>> with l.unlocked() as lopen:
...   print(l is lopen)
...   l[1] = 4
True

sentinel() can be used for methods, item and attribute access.

>>> l.clear()
Traceback (most recent call last):
    ...
lockable.Locked: Object is currently locked!  Use unlocked() if you know what you are doing.
>>> with l.unlocked():
...   l.clear()
>>> l
[]

When used together with HasGroups, objects will be locked recursively.

>>> class LockGroupDict(Lockable, dict, HasGroups):
...   __setitem__ = sentinel(dict.__setitem__)
...
...   def _list_groups(self):
...     return [k for k, v in self.items() if isinstance(v, LockGroupDict)]
...
...   def _list_nodes(self):
...     return [k for k, v in self.items() if not isinstance(v, LockGroupDict)]

>>> d = LockGroupDict(a=dict(c=1, d=2), b=LockGroupDict(c=1, d=2))
>>> d.lock()

Since the first item is a plain dict, it can still be mutated.

>>> type(d['a'])
<class 'dict'>
>>> d['a']['c'] = 23
>>> d['a']['c']
23

Where as the second will be locked from now on

>>> type(d['b'])
<class 'lockable.LockGroupDict'>
>>> d['b']['c'] = 23
Traceback (most recent call last):
    ...
lockable.Locked: Object is currently locked!  Use unlocked() if you know what you are doing.
>>> d['b']['c']
1

but we can unlock it as usual

>>> with d.unlocked():
...   d['b']['d'] = 23
>>> d['b']['d']
23

To use this class with properties, simply decorate the setter

>>> class MyLock(Lockable):
...   def __init__(self, foo):
...     super().__init__()
...     self._foo = foo
...   @property
...   def foo(self):
...     return self._foo
...   @foo.setter
...   @sentinel
...   def foo(self, value):
...     self._foo = value
>>> ml = MyLock(42)
>>> ml.foo
42
>>> ml.foo = 23
>>> ml.lock()
>>> ml.foo = 42
Traceback (most recent call last):
    ...
lockable.Locked: Object is currently locked!  Use unlocked() if you know what you are doing.

It’s possible to change the errors raised into a warning and allow modification by passing lock_method to __init__() or method to lock().

>>> mw = LockList(lock_method="warning")
>>> mw.append(0)
>>> mw.lock()
>>> mw[0] = 1 # will print the warning
>>> mw[0]
1

>>> mw = LockList()
>>> mw.append(0)
>>> mw.lock(method='warning')
>>> mw[0] = 1 # will print the warning
>>> mw[0]
1

__init__(*args, lock_method: str = 'error', **kwargs)

Methods

__init__(*args[, lock_method])
lock([method])	Set read_only.
unlocked()	Unlock the object temporarily.

Attributes

read_only

False if the object can currently be written to

lock(method: Literal['error', 'warning'] | None = None)

Set read_only.

Objects may be safely locked multiple times without further effect.

Parameters:

method (str, either "error" or "warning") – if “error” raise an Locked exception if modification is attempted; if “warning” raise a LockedWarning warning; default is “error” or the value passed to the constructor.

Raises:

ValueError – if method is not an allowed value

property read_only: bool

False if the object can currently be written to

Setting this value will trigger _on_lock() and _on_unlock() if it changes.

Type:

bool

unlocked() → _UnlockContext

Unlock the object temporarily.

Context manager returns this object again and relocks it after the with statement finished.

Note

lock() vs. unlocked()

There is a small asymmetry between these two methods. lock() can only be done once (meaningfully), while unlocked() is a context manager and can be called multiple times.