"""Context manager for controlling global state variables.""" from __future__ import annotations from abc import ABC from abc import abstractmethod import contextlib from typing import TYPE_CHECKING from typing import Generic from typing import Literal from typing import TypeVar from typing import cast from typing import final from typing import get_args from typing import overload from pyvista import _vtk from pyvista.core import _vtk_utilities if TYPE_CHECKING: from typing_extensions import Self T = TypeVar('T') class _StateManager(contextlib.AbstractContextManager[None], ABC, Generic[T]): """Abstract base class for managing a global state variable. Subclasses must: - Specify a `Literal` as the subclass' type argument. The literal's arguments must specify all allowable options for the state variable. - Define a getter and setter for the state. Input validation is not required - the input is automatically validated when setting the state. Examples -------- >>> from pyvista.core.utilities.state_manager import _StateManager >>> from typing import Literal Define the available options as a ``Literal`` and initialize a global state variable. >>> _StateOptions = Literal['on', 'off'] >>> _GLOBAL_STATE = ['off'] # Init global state. Use list to make it mutable. Define the class and its state property. >>> class MyState(_StateManager[_StateOptions]): ... @property ... def _state(self) -> _StateOptions: ... return _GLOBAL_STATE[0] ... ... @_state.setter ... def _state(self, state: _StateOptions) -> None: ... _GLOBAL_STATE[0] = state Finally, create an instance of the state manager. >>> my_state = MyState() Get the state. >>> my_state() 'off' Set the state. >>> _ = my_state('on') >>> my_state() 'on' Use it as a context manager to set the state temporarily: >>> with my_state('off'): ... pass """ @classmethod def _get_state_options_from_literal(cls) -> tuple[str | int | bool]: state_manager_fullname = f'{_StateManager.__module__}.{_StateManager.__name__}' for base in getattr(cls, '__orig_bases__', ()): if str(base).startswith(state_manager_fullname): # Get StateManager's typing args state_manager_args = get_args(base) if len(state_manager_args) == 1: # There must only be one arg and it must be a non-empty Literal literal = state_manager_args[0] if str(literal).startswith('typing.Literal'): args = get_args(literal) if len(args) >= 1: return args msg = ( 'Type argument for subclasses must be a single non-empty Literal with all state ' 'options provided.' ) raise TypeError(msg) def __init__(self) -> None: """Initialize context manager.""" self._valid_states = self._get_state_options_from_literal() self._original_state: T | None = None @property @abstractmethod def _state(self) -> T: """Get the current global state.""" @_state.setter @abstractmethod def _state(self, state: T) -> None: """Set the global state.""" @final def _validate_state(self, state: T) -> T: from pyvista import _validation # noqa: PLC0415 _validation.check_contains(self._valid_states, must_contain=state, name='state') return state def __enter__(self) -> None: """Enter context manager.""" if self._original_state is None: msg = 'State must be set before using it as a context manager.' raise ValueError(msg) def __exit__(self, exc_type, exc_value, traceback): # noqa: ANN001, ANN204 """Exit context manager and restore original state.""" self._state = cast('T', self._original_state) self._original_state = None # Reset @overload def __call__(self: Self, state: None) -> T: ... @overload def __call__(self: Self, state: T) -> Self: ... def __call__(self: Self, state: T | None = None) -> Self | T: """Call the context manager.""" if state is None: return self._state self._validate_state(state) # Create new instance and store the local state to be restored when exiting output = self.__class__() output._original_state = self._state output._state = state return output _VerbosityOptions = Literal[ 'off', 'error', 'warning', 'info', 'max', ] class _VTKVerbosity(_StateManager[_VerbosityOptions]): """Context manager to set VTK verbosity level. .. versionadded:: 0.45 Parameters ---------- verbosity : str Verbosity of the :vtk:`vtkLogger` to set. - ``'off'``: No output. - ``'error'``: Only error messages. - ``'warning'``: Errors and warnings. - ``'info'``: Errors, warnings, and info messages. - ``'max'``: All messages, including debug info. Examples -------- Get the current vtk verbosity. >>> import pyvista as pv >>> pv.vtk_verbosity() 'info' Set verbosity to max. >>> _ = pv.vtk_verbosity('max') >>> pv.vtk_verbosity() 'max' Create a :func:`~pyvista.Sphere`. Note how many VTK debugging messages are now generated as the sphere is created. >>> mesh = pv.Sphere() Use it as a context manager to temporarily turn it off. >>> with pv.vtk_verbosity('off'): ... mesh = mesh.cell_quality('volume') The state is restored to its previous value outside the context. >>> pv.vtk_verbosity() 'max' Note that the verbosity state is global and will persist between function calls. If the context manager isn't used, the state needs to be reset explicitly. Here, we set it back to its default value. >>> _ = pv.vtk_verbosity('info') """ @property def _state(self) -> _VerbosityOptions: int_to_string: dict[int, _VerbosityOptions] = { -9: 'off', -2: 'error', -1: 'warning', 0: 'info', 9: 'max', } state = _vtk.vtkLogger.GetCurrentVerbosityCutoff() try: return int_to_string[state] except KeyError: # Unsupported state, raise error using validation method self._validate_state(state) # type: ignore[arg-type] msg = 'This line should not be reachable.' # pragma: no cover raise RuntimeWarning(msg) # pragma: no cover @_state.setter def _state(self, state: _VerbosityOptions) -> None: verbosity_int = _vtk.vtkLogger.ConvertToVerbosity(state.upper()) _vtk.vtkLogger.SetStderrVerbosity(verbosity_int) vtk_verbosity = _VTKVerbosity() _VtkSnakeCaseOptions = Literal['allow', 'warning', 'error'] class _vtkSnakeCase(_StateManager[_VtkSnakeCaseOptions]): # noqa: N801 """Context manager to control access to VTK's pythonic snake_case API. VTK 9.4 introduced pythonic snake_case attributes, e.g. `output_port` instead of `GetOutputPort`. These can easily be confused for PyVista attributes which also use a snake_case convention. This class controls access to vtk's new interface. .. versionadded:: 0.45 Parameters ---------- state : 'allow' | 'warning' | 'error' Allow or disallow the use of VTK's pythonic snake_case API with PyVista-wrapped VTK classes. - 'allow': Allow accessing VTK-defined snake_case attributes. - 'warning': Print a RuntimeWarning when accessing VTK-defined snake_case attributes. - 'error': Raise a ``PyVistaAttributeError`` when accessing VTK-defined snake_case attributes. Examples -------- Get the current access state for VTK's snake_case api. >>> import pyvista as pv >>> pv.vtk_snake_case() 'error' The following will raise an error because the `information` property is defined by :vtk:`vtkDataObject` and is not part of PyVista's API. >>> # pv.PolyData().information Allow use of VTK's snake_case attributes. No warning or error is raised. >>> _ = pv.vtk_snake_case('allow') >>> pv.PolyData().information >> _ = pv.vtk_snake_case('error') Use it as a context manager instead. This way, the state is only temporarily modified and is automatically restored. >>> with pv.vtk_snake_case('allow'): ... _ = pv.PolyData().information >>> pv.vtk_snake_case() 'error' """ @property def _state(self) -> _VtkSnakeCaseOptions: return _vtk_utilities._VTK_SNAKE_CASE_STATE @_state.setter def _state(self, state: _VtkSnakeCaseOptions) -> None: _vtk_utilities._VTK_SNAKE_CASE_STATE = state vtk_snake_case = _vtkSnakeCase() _AllowNewAttributesOptions = Literal['private', True, False] class _AllowNewAttributes(_StateManager[_AllowNewAttributesOptions]): """Context manager to control setting new attributes on PyVista classes. Python allows arbitrarily setting new attributes on objects at any time, but PyVista's classes do not always allow this. By default, setting a new attribute is only allowed when the attribute's name has a leading underscore "``_``", i.e. it is a private attribute; attempting to set a new public attribute raises an ``AttributeError``. This context manager may be used to allow or disallow setting `any` new attribute, public or private, either globally or within a context. .. versionadded:: 0.47 Parameters ---------- mode : 'private' | bool Control if setting new attributes is allowed. - ``'private'``: Allow setting private attributes, but do not allow setting public attributes. - ``True``: Allow setting any new attribute, either private or public. - ``False``: Do not allow setting new attributes, regardless if they are private or public. ``'private'`` is used by default, ``True`` removes all restrictions, and ``False`` is most strict. .. note:: An attribute is considered private if its name has a leading underscore "``_``". See Also -------- pyvista.set_new_attribute Function for setting any new attribute on a PyVista object. Notes ----- Allowing new attributes by default outside ``__init__`` and/or without formally defining class properties was found to be a source of bugs for both developers and users of PyVista. It's very easy to set the wrong attribute name (e.g. ``interpolate`` vs. ``interpolation``) without any errors being generated, and users transitioning from older versions of PyVista would have code that sets attributes which were once valid, but have since been deprecated and removed. Attempting to set an attribute which is not already defined now raises an ``AttributeError`` to clearly signal that there is a potential problem with this line of code. Examples -------- Get the default attribute mode. >>> import pyvista as pv >>> pv.allow_new_attributes() 'private' Setting new `private` attributes on PyVista objects is allowed by default. >>> mesh = pv.PolyData() >>> mesh._foo = 42 # OK >>> mesh.foo = 42 # ERROR # doctest: +SKIP Do not allow setting new attributes. >>> _ = pv.allow_new_attributes(False) >>> mesh._foo = 42 # ERROR # doctest:+SKIP >>> mesh.foo = 42 # ERROR # doctest:+SKIP Note that this state is global and will persist between function calls. Set it back to its original state explicitly. >>> _ = pv.allow_new_attributes('private') Use it as a context manager instead. This way, the state is only temporarily modified and is automatically restored. >>> with pv.allow_new_attributes(True): ... mesh._foo = 42 # OK ... mesh.foo = 42 # OK >>> pv.allow_new_attributes() 'private' """ @property def _state(self) -> _AllowNewAttributesOptions: from pyvista import _ALLOW_NEW_ATTRIBUTES_MODE # noqa: PLC0415 return _ALLOW_NEW_ATTRIBUTES_MODE @_state.setter def _state(self, state: _AllowNewAttributesOptions) -> None: import pyvista as pv # noqa: PLC0415 pv._ALLOW_NEW_ATTRIBUTES_MODE = state allow_new_attributes = _AllowNewAttributes()