Custom lock/rlock classes owning the protected data

Compared to the well-known `threading.Lock`, the locks added here wrap
the data they protect. It is still possible to modify the data, since
Python does not have actual private attributes, but it's no longer
possible to do so by accident or by omission:

```python
# With the classical approach...
_SOME_SHARED_DATA_LOCK = threading.Lock()
SOME_SHARED_DATA = set()

# ... nothing stops me from changing the set without taking the lock:
SOME_SHARED_DATA.add('foo')

# On the other hand, with our custom locks, the set does not exist as
# a value I could modify directly...
SOME_SHARED_DATA: Lock[set[str]] = Lock(set())

# ... and it's "lent" to me only if the wrapper acquires the lock on my
# behalf:
with SOME_SHARED_DATA as the_wrapped_set:
    the_wrapped_set.add('foo')
```

Author: happz

tests/unit/test_threading.py

@@ -0,0 +1,17 @@
+from tmt.utils._threading import Lock
+
+
+def test_sanity() -> None:
+    some_data: list[str] = []
+
+    lock: Lock[list[str]] = Lock(some_data)
+
+    assert lock._Lock__lock.locked() is False  # type: ignore[attr-defined]
+    assert lock._Lock__value is some_data  # type: ignore[attr-defined]
+
+    with lock as data:
+        assert lock._Lock__lock.locked() is True  # type: ignore[attr-defined]
+        assert data is some_data
+
+    assert lock._Lock__lock.locked() is False  # type: ignore[attr-defined]
+    assert lock._Lock__value is some_data  # type: ignore[attr-defined]

tmt/utils/_threading.py

@@ -0,0 +1,90 @@
+"""
+Threading and synchronization helpers.
+"""
+
+import threading
+from typing import Generic, TypeVar
+
+T = TypeVar('T')
+LockT = TypeVar('LockT', threading.Lock, threading.RLock)
+
+
+class _Lock(Generic[LockT, T]):
+    __lock: LockT
+    __value: T
+
+    def __init__(self, lock: LockT, value: T) -> None:
+        self.__lock = lock
+        self.__value = value
+
+    def __enter__(self) -> T:
+        self.__lock.acquire()
+
+        return self.__value
+
+    def __exit__(self, *args: object) -> None:
+        self.__lock.release()
+
+
+class Lock(_Lock[threading.Lock, T]):
+    """
+    A lock protecting its payload from unsynchronized access.
+
+    In functionality it is similar to :py:class:`threading.Lock`, but
+    bundles together the protected value and lock protecting it.
+    To get the value, code is forced to acquire the lock:
+
+    .. code-block:: python
+
+        # A list, representing data shared between multiple threads,
+        # is not assigned to any global name. Instead, it is wrapped by
+        # the lock, and "borrowed" to caller using the context manager
+        # approach:
+        SHARED_DATA: Lock[list[str]] = Lock([])
+
+        ...
+
+        # `data` below is the list given to `Lock()` above:
+        with SHARED_DATA as data:
+            data += [...]
+
+    Compared to :py:class:`RLock`, ``Lock`` is not reentrant, i.e. it
+    can be acquired by the same thread only once, another attempt to
+    acquire the lock while already holding it will end up with a
+    deadlock. See :py:class:`threading.RLock` for more details on its
+    reentrancy.
+    """
+
+    def __init__(self, value: T) -> None:
+        super().__init__(threading.Lock(), value)
+
+
+class RLock(_Lock[threading.RLock, T]):
+    """
+    A reentrant variant of :py:class:`Lock`.
+
+    In functionality it is similar to :py:class:`threading.RLock`, but
+    bundles together the protected value and lock protecting it.
+    To get the value, code is forced to acquire the lock:
+
+    .. code-block:: python
+
+        # A list, representing data shared between multiple threads,
+        # is not assigned to any global name. Instead, it is wrapped by
+        # the lock, and "borrowed" to caller using the context manager
+        # approach:
+        SHARED_DATA: Lock[list[str]] = RLock([])
+
+        ...
+
+        # `data` below is the list given to `Lock()` above:
+        with SHARED_DATA as data:
+            data += [...]
+
+    Compared to :py:class:`Lock`, ``RLock`` is reentrant, i.e. it can
+    be reacquired by the same thread. See :py:class:`threading.RLock`
+    for more details on its reentrancy.
+    """
+
+    def __init__(self, value: T) -> None:
+        super().__init__(threading.RLock(), value)