Source code for simvx.core.diagnostics

"""The warning category for mistakes in game code that the engine can see.

Checks that catch such a mistake run only while ``Node.dev_warnings`` is on, and
report through :mod:`warnings` under :class:`DevWarning`, so a developer can
filter them like any other warning::

    import warnings
    from simvx.core import DevWarning

    warnings.simplefilter("error", DevWarning)    # fail fast in a test run
    warnings.simplefilter("ignore", DevWarning)   # or silence them
"""

from __future__ import annotations

import warnings

import simvx

__all__ = ["DevWarning", "warn_dev"]

# The warning is attributed to the first frame outside the engine, so it names the
# game's own line (the ``connect`` call, say) rather than the check that noticed.
_ENGINE_PREFIXES = tuple(simvx.__path__)




class DevWarning(UserWarning):
    """A mistake in game code that the engine noticed while ``Node.dev_warnings`` is on.

    Each check reports a given mistake once, naming what is wrong and the fix.
    """





def warn_dev(message: str) -> None:
    """Issue ``message`` as a :class:`DevWarning`, attributed to the calling game code.

    The caller decides once-ness and guards the call on ``Node.dev_warnings``.
    """
    warnings.warn(message, DevWarning, skip_file_prefixes=_ENGINE_PREFIXES)