Source code for metatensor.operations.checks

"""
Metatensor performs `shape` as well as `consistency` checks for the metadata during each
operation. The check status can be verified with :py:func:`metatensor.checks_enabled()`
and controlled by :py:class:`metatensor.unsafe_enable_checks()` and
:py:class:`metatensor.unsafe_disable_checks()`.

.. warning::
    Using metatensor without checks is unsafe, can lead to unwanted results, and may
    produce cryptic error messages. Therefore, disabling checks is not recommended and
    should only be used by advanced users! If you see strange results after disabling
    checks, try running the code again with checks enabled.

Checks can either be disabled temporarily
via a compound statements or globally and permanently by calling the speicific function
directly.

The checks can also controlled wit the environment variable
``METATENSOR_UNSAFE_DISABLE_CHECKS``. To disable checks set

.. code-block:: bash

    export METATENSOR_UNSAFE_DISABLE_CHECKS=1


Note that :py:class:`metatensor.unsafe_enable_checks()` or
:py:class:`metatensor.unsafe_disable_checks()` overwrite the defintion of the enviroment
variable.
"""

import os


def _parse_bool_env_var(key):
    """Parses a boolean environment variable. Returns ``False`` if it doesn't exist."""
    value = os.environ.get(key, default="")
    return value.lower() in ["true", "1", "yes", "on"]


# global variable storing the state if checks should be performed or not
_CHECKS_ENABLED = not _parse_bool_env_var("METATENSOR_UNSAFE_DISABLE_CHECKS")


[docs] def checks_enabled() -> bool: """Check status if metatensor checks should be performed.""" return _CHECKS_ENABLED
class _SetChecks: """Private parent class for setting metatensor check control to a certain state. Refer to the docstring of ``disble_checks`` for more details.""" def __init__(self, state): global _CHECKS_ENABLED self.original_check_state = _CHECKS_ENABLED self.state = state _CHECKS_ENABLED = self.state def __repr__(self) -> str: return f"checks {'en' if self.state else 'dis'}abled" def __enter__(self): """Enter the context and set the checks to the desired state.""" global _CHECKS_ENABLED _CHECKS_ENABLED = self.state return self def __exit__(self, type, value, traceback): """Exit the context and restore the previous checks status.""" global _CHECKS_ENABLED _CHECKS_ENABLED = self.original_check_state
[docs] class unsafe_enable_checks(_SetChecks): """Enable metatensor checks. Checks are default enabled. Calling this function permanatly enables all metatensor operations checks. >>> import metatensor >>> metatensor.unsafe_enable_checks() checks enabled >>> print(metatensor.checks_enabled()) True You can also use a compound statement to enable checks only temporarily. This can be useful in nested constructions. >>> import metatensor >>> print(metatensor.checks_enabled()) True >>> with metatensor.unsafe_disable_checks(): ... # checks are disabled here ... print(metatensor.checks_enabled()) ... with metatensor.unsafe_enable_checks(): ... # checks enabled here again ... print(metatensor.checks_enabled()) ... False True >>> print(metatensor.checks_enabled()) True """ def __init__(self): super().__init__(state=True)
[docs] class unsafe_disable_checks(_SetChecks): """Disable metatensor checks. Calling this function permanatly disables all metatensor operations checks. >>> import metatensor >>> metatensor.unsafe_disable_checks() checks disabled >>> print(metatensor.checks_enabled()) False You can also use a compound statement to disable checks only temporarily. >>> metatensor.unsafe_enable_checks() checks enabled >>> with metatensor.unsafe_disable_checks(): ... # checks are disabled here ... print(metatensor.checks_enabled()) ... False >>> print(metatensor.checks_enabled()) True """ def __init__(self): super().__init__(state=False)