Nano-Utils 0.3.0 (#4)

* Added the ``SetAttr`` context manager.
* Updated the development status from alpha to beta.

Author: BvB93

CHANGELOG.rst

@@ -6,6 +6,12 @@ All notable changes to this project will be documented in this file.
 This project adheres to `Semantic Versioning <http://semver.org/>`_.
 
 
+0.3.0
+*****
+* Added the ``SetAttr`` context manager.
+* Updated the development status from alpha to beta.
+
+
 0.2.0
 *****
 * Added new NumPy-specific functions: ``as_nd_array()``, ``array_combinations()`` & ``fill_diagonal_blocks()``.

README.rst

@@ -20,7 +20,7 @@
 
 
 ################
-Nano-Utils 0.2.0
+Nano-Utils 0.3.0
 ################
 Utility functions used throughout the various nlesc-nano repositories.
 

docs/0_documentation.rst

@@ -6,3 +6,4 @@ API
     3_schema.rst
     4_typing.rst
     5_numpy.rst
+    6_set_attr.rst

docs/6_set_attr.rst

@@ -0,0 +1,3 @@
+nanoutils.set_attr
+==================
+.. automodule:: nanoutils.set_attr

nanoutils/__init__.py

@@ -1,14 +1,15 @@
-"""Nano-Utils."""
+"""The **Nano-Utils** package."""
 
 # flake8: noqa: F403,F401
 
 from .__version__ import __version__
 
-from . import typing_utils, empty, utils, numpy_utils, schema
+from . import typing_utils, empty, utils, numpy_utils, schema, set_attr
 from .typing_utils import *
 from .empty import *
 from .utils import *
 from .numpy_utils import *
+from .set_attr import *
 from .schema import (
     Default, Formatter, supports_float, supports_int,
     isinstance_factory, issubclass_factory, import_factory
@@ -24,3 +25,4 @@
 __all__ += utils.__all__
 __all__ += numpy_utils.__all__
 __all__ += schema.__all__
+__all__ += set_attr.__all__

nanoutils/__version__.py

@@ -1,3 +1,3 @@
-"""The Nano-Utils version."""
+"""The **Nano-Utils** version."""
 
-__version__ = '0.2.0'
+__version__ = '0.3.0'

nanoutils/set_attr.py

@@ -0,0 +1,165 @@
+"""A module for containing the :class:`SetAttr` class.
+
+Index
+-----
+.. currentmodule:: nanoutils
+.. autosummary::
+    {autosummary}
+
+API
+---
+{autofunction}
+
+"""
+
+import reprlib
+from types import TracebackType
+from typing import Generic, TypeVar, NoReturn, Dict, Any, Optional, Type
+from threading import RLock
+
+from .utils import construct_api_doc
+
+__all__ = ['SetAttr']
+
+T1 = TypeVar('T1')
+T2 = TypeVar('T2')
+ST = TypeVar('ST', bound='SetAttr')
+
+
+class SetAttr(Generic[T1, T2]):
+    """A context manager for temporarily changing an attribute's value.
+
+    The :class:`SetAttr` context manager is thread-safe, reusable and reentrant.
+
+    Warnings
+    --------
+    Note that while :meth:`SetAttr.__enter__` and :meth:`SetAttr.__exit__` are thread-safe,
+    the same does *not* hold for :meth:`SetAttr.__init__`.
+
+    Examples
+    --------
+    .. code:: python
+
+        >>> from nanoutils import SetAttr
+
+        >>> class Test:
+        ...     a = False
+
+        >>> print(Test.a)
+        False
+
+        >>> set_attr = SetAttr(Test, 'a', True)
+        >>> with set_attr:
+        ...     print(Test.a)
+        True
+
+    """
+
+    __slots__ = ('__weakref__', '_obj', '_name', '_value', '_value_old', '_lock', '_hash')
+
+    @property
+    def obj(self) -> T1:
+        """:class:`T1<typing.TypeVar>`: The to-be modified object."""
+        return self._obj
+
+    @property
+    def name(self) -> str:
+        """:class:`str`: The name of the to-be modified attribute."""
+        return self._name
+
+    @property
+    def value(self) -> T2:
+        """:class:`T2<typing.TypeVar>`: The value to-be assigned to the :attr:`name` attribute of :attr:`SetAttr.obj`."""  # noqa: E501
+        return self._value
+
+    @property
+    def attr(self) -> T2:
+        """:class:`T2<typing.TypeVar>`: Get or set the :attr:`~SetAttr.name` attribute of :attr:`SetAttr.obj`."""  # noqa: E501
+        return getattr(self.obj, self.name)
+
+    @attr.setter
+    def attr(self, value: T2) -> None:
+        with self._lock:
+            setattr(self.obj, self.name, value)
+
+    def __init__(self, obj: T1, name: str, value: T2) -> None:
+        """Initialize the :class:`SetAttr` context manager.
+
+        Parameters
+        ----------
+        obj : :class:`T1<typing.TypeVar>`
+            The to-be modified object.
+        name : :class:`str`
+            The name of the to-be modified attribute.
+        value : :class:`T2<typing.TypeVar>`
+            The value to-be assigned to the **name** attribute of **obj**.
+
+
+        :rtype: :data:`None`
+
+        """
+        self._obj = obj
+        self._name = name
+        self._value = value
+
+        self._value_old = self.attr
+        self._lock = RLock()
+
+    @reprlib.recursive_repr()
+    def __repr__(self) -> str:
+        """Implement :func:`str(self)<str>` and :func:`repr(self)<repr>`."""
+        obj = object.__repr__(self.obj)
+        value = reprlib.repr(self.value)
+        return f'{self.__class__.__name__}(obj={obj}, name={self.name!r}, value={value})'
+
+    def __eq__(self, value: object) -> bool:
+        """Implement :func:`self == value<object.__eq__>`."""
+        if type(self) is not type(value):
+            return False
+        return self.obj is value.obj and self.name == value.name and self.value == value.value  # type: ignore  # noqa: E501
+
+    def __reduce__(self) -> NoReturn:
+        """A Helper function for :mod:`pickle`.
+
+        Warnings
+        --------
+        Unsupported operation, raises a :exc:`TypeError`.
+
+        """
+        raise TypeError(f"can't pickle {self.__class__.__name__} objects")
+
+    def __copy__(self: ST) -> ST:
+        """Implement :func:`copy.copy(self)<copy.copy>`."""
+        return self
+
+    def __deepcopy__(self: ST, memo: Optional[Dict[int, Any]] = None) -> ST:
+        """Implement :func:`copy.deepcopy(self, memo=memo)<copy.deepcopy>`."""
+        return self
+
+    def __hash__(self) -> int:
+        """Implement :func:`hash(self)<hash>`.
+
+        Warnings
+        --------
+        A :exc:`TypeError` will be raised if :attr:`SetAttr.value` is not hashable.
+
+        """
+        try:
+            return self._hash
+        except AttributeError:
+            args = (type(self), (id(self.obj), self.name, self.value))
+            self._hash: int = hash(args)
+            return self._hash
+
+    def __enter__(self) -> None:
+        """Enter the context manager, modify :attr:`SetAttr.obj`."""
+        self.attr = self.value
+
+    def __exit__(self, exc_type: Optional[Type[BaseException]],
+                 exc_value: Optional[BaseException],
+                 traceback: Optional[TracebackType]) -> None:
+        """Exit the context manager, restore :attr:`SetAttr.obj`."""
+        self.attr = self._value_old
+
+
+__doc__ = construct_api_doc(globals())

nanoutils/utils.py

@@ -241,7 +241,10 @@ def split_dict(dct: MutableMapping[KT, VT], keep_keys: Iterable[KT],
     if keep_order:
         difference: Iterable[KT] = [k for k in dct if k not in keep_keys]
     else:
-        difference = set(dct.keys()).difference(keep_keys)
+        try:
+            difference = dct.keys() - keep_keys  # type: ignore
+        except (TypeError, AttributeError):
+            difference = set(dct.keys()).difference(keep_keys)
 
     return {k: dct.pop(k) for k in difference}
 

setup.py

@@ -60,7 +60,7 @@
         'libraries'
     ],
     classifiers=[
-        'Development Status :: 3 - Alpha',
+        'Development Status :: 4 - Beta',
         'Intended Audience :: Developers',
         'License :: OSI Approved :: Apache Software License',
         'Natural Language :: English',

tests/test_empty.py

@@ -0,0 +1,15 @@
+"""Tests for :mod:`nanoutils.empty`."""
+
+from collections import abc
+
+from nanoutils import EMPTY_SEQUENCE, EMPTY_MAPPING, EMPTY_COLLECTION, EMPTY_SET, EMPTY_CONTAINER
+from assertionlib import assertion
+
+
+def test_empty() -> None:
+    """Tests for :mod:`nanoutils.empty`."""
+    assertion.isinstance(EMPTY_SEQUENCE, abc.Sequence)
+    assertion.isinstance(EMPTY_MAPPING, abc.Mapping)
+    assertion.isinstance(EMPTY_COLLECTION, abc.Collection)
+    assertion.isinstance(EMPTY_SET, abc.Set)
+    assertion.isinstance(EMPTY_CONTAINER, abc.Container)

tests/test_set_attr.py

@@ -0,0 +1,49 @@
+"""Tests for :mod:`nanoutils.set_attr`."""
+
+import copy
+import reprlib
+from assertionlib import assertion
+
+from nanoutils import SetAttr
+
+
+class _Test:
+    a: bool = True
+
+
+OBJ = SetAttr(_Test, 'a', False)
+
+
+def test_setattr() -> None:
+    """Test :class:`~nanoutils.SetAttr`."""
+    assertion.is_(OBJ.obj, _Test)
+    assertion.eq(OBJ.name, 'a')
+    assertion.is_(OBJ.value, False)
+
+    assertion.is_(OBJ.attr, _Test.a)
+    try:
+        OBJ.attr = False
+        assertion.is_(OBJ.attr, False)
+    finally:
+        OBJ.attr = True
+
+    assertion.contains(repr(OBJ), SetAttr.__name__)
+    assertion.contains(repr(OBJ), object.__repr__(OBJ.obj))
+    assertion.contains(repr(OBJ), reprlib.repr(OBJ.value))
+    assertion.contains(repr(OBJ), 'a')
+
+    obj2 = SetAttr(_Test, 'a', False)
+    obj3 = SetAttr(_Test, 'a', True)
+    assertion.eq(OBJ, obj2)
+    assertion.ne(OBJ, obj3)
+    assertion.ne(OBJ, 0)
+
+    assertion.assert_(OBJ.__reduce__, exception=TypeError)
+    assertion.is_(copy.copy(OBJ), OBJ)
+    assertion.is_(copy.deepcopy(OBJ), OBJ)
+    assertion.truth(hash(OBJ))
+    assertion.eq(hash(OBJ), OBJ._hash)
+
+    with OBJ:
+        assertion.is_(_Test.a, False)
+    assertion.is_(_Test.a, True)

tests/test_docs.py renamed to tests/test_sphinx.py

@@ -0,0 +1,27 @@
+"""Tests for :mod:`nanoutils.typing_utils`."""
+
+import sys
+
+from assertionlib import assertion
+from nanoutils import Literal, Final, final, Protocol, TypedDict, SupportsIndex, runtime_checkable
+
+if sys.version_info < (3, 8):
+    import typing_extensions as t
+else:
+    import typing as t
+
+
+def test_typing() -> None:
+    """Tests for :mod:`nanoutils.typing_utils`."""
+    assertion.is_(Literal, t.Literal)
+    assertion.is_(Final, t.Final)
+    assertion.is_(final, t.final)
+    assertion.is_(Protocol, t.Protocol)
+    assertion.is_(TypedDict, t.TypedDict)
+    assertion.is_(runtime_checkable, t.runtime_checkable)
+
+    if sys.version_info >= (3, 8):
+        assertion.is_(SupportsIndex, t.SupportsIndex)
+    else:
+        assertion.contains(SupportsIndex.__bases__, Protocol)
+        assertion.hasattr(SupportsIndex, '__index__')

tests/test_typing.py

@@ -1,7 +1,10 @@
 """Tests for :mod:`nanoutils.utils`."""
 
+from inspect import isclass
+from functools import partial
+
 from assertionlib import assertion
-from nanoutils import set_docstring
+from nanoutils import set_docstring, get_importable, VersionInfo, version_info
 
 
 def test_set_docstring() -> None:
@@ -17,3 +20,34 @@ def func2():
 
     assertion.eq(func1.__doc__, 'TEST')
     assertion.eq(func2.__doc__, None)
+
+
+def test_get_importable() -> None:
+    """Tests for :func:`nanoutils.get_importable`."""
+    class Test:
+        split = True
+
+    assertion.is_(get_importable('builtins.dict'), dict)
+    assertion.is_(get_importable('builtins.dict', validate=isclass), dict)
+
+    assertion.assert_(get_importable, None, exception=TypeError)
+    assertion.assert_(get_importable, Test, exception=TypeError)
+    assertion.assert_(get_importable, 'builtins.len', validate=isclass, exception=RuntimeError)
+    assertion.assert_(get_importable, 'builtins.len', validate=partial(isclass),
+                      exception=RuntimeError)
+
+
+def test_version_info() -> None:
+    """Tests for :func:`nanoutils.VersionInfo`."""
+    tup1 = VersionInfo(0, 1, 2)
+    tup2 = VersionInfo.from_str('0.1.2')
+    assertion.eq(tup1, (0, 1, 2))
+    assertion.eq(tup2, (0, 1, 2))
+
+    assertion.eq(tup1.micro, tup1.patch)
+
+    assertion.assert_(VersionInfo.from_str, b'0.1.2', exception=TypeError)
+    assertion.assert_(VersionInfo.from_str, '0.1.2a', exception=ValueError)
+    assertion.assert_(VersionInfo.from_str, '0.1.2.3.4', exception=ValueError)
+
+    assertion.isinstance(version_info, VersionInfo)