API Reference

def raises[T: Callable[..., object]](*exceptions: type[BaseException]) -> Callable[[T], T]:
    """Declare the exceptions a function may raise.

    At runtime, validates that each declared exception is in the current
    watched set (see ``enable``). Adds the declared exceptions to the
    watched set for the duration of the call.

    Args:
        *exceptions: Exception types the decorated function is allowed to raise.

    Returns:
        A decorator that wraps the function with exception validation.

    Raises:
        UnwatchedRaiseError: If a declared exception is not in the watched set.
    """

    def decorator(func: T) -> T:
        if inspect.iscoroutinefunction(func):

            @wraps(func)
            async def async_wrapper(*args: object, **kwargs: object) -> object:
                if error := _validate_exceptions(func.__name__, exceptions):
                    raise error.with_traceback(None)
                with watch_exceptions(*exceptions):
                    return await func(*args, **kwargs)

            return async_wrapper  # pyright: ignore[reportReturnType]

        @wraps(func)
        def wrapper(*args: object, **kwargs: object) -> object:
            if error := _validate_exceptions(func.__name__, exceptions):
                raise error.with_traceback(None)
            with watch_exceptions(*exceptions):
                return func(*args, **kwargs)

        return wrapper  # pyright: ignore[reportReturnType]

    return decorator

def register(*roots: str) -> None:
    """Install the import hook for the given package roots.

    Must be called **before** importing the packages you want to instrument,
    and in a separate file from those packages. The hook rewrites every
    ``try/except`` block at import time so that caught exception types are
    automatically added to the watched set.

    Args:
        *roots: Top-level package names to instrument (e.g. ``"myapp"``).

    Example:
        ```python
        import saferaise

        saferaise.register("myapp")  # must come before `import myapp`

        import myapp

        with saferaise.enable():
            myapp.run()
        ```

    Raises:
        NameCollisionError: If an instrumented module already has an attribute
            named ``_saferaise_watch_exceptions``.
    """
    sys.meta_path.insert(0, _TryCtxFinder(*roots))

def is_registered() -> bool:
    """Check if saferaise is registered for the current file.

    Returns:
        bool: True if saferaise is registered, False otherwise.
    """
    if (frame := inspect.currentframe()) and (prev_frame := frame.f_back):
        return WATCHER_KEY in prev_frame.f_globals
    return False

@contextmanager
def enable() -> Iterator[None]:
    """Enable exception watching with an empty watched set.

    Inside this context, any ``@raises``-decorated function will validate that
    its declared exceptions are being watched. Use this at the top level of
    your application or in tests to activate enforcement.

    Example:
        ```python
        import saferaise

        saferaise.register("myapp")
        import myapp

        with saferaise.enable():
            myapp.run()
        ```
    """
    token = _watched_exceptions.set(frozenset())
    try:
        yield
    finally:
        _watched_exceptions.reset(token)

def is_enabled() -> bool:
    """Check if exception watching is currently enabled.

    Returns:
        True if watching is enabled, False otherwise.
    """
    return _watched_exceptions.get() is not None

@contextmanager
def disable() -> Iterator[None]:
    """Temporarily disable exception watching.

    Inside this context, ``@raises`` validation is skipped entirely,
    regardless of any outer ``enable`` or ``watch_exceptions`` context.
    Use this in production hot paths or during migration when you want
    instrumentation in place but enforcement off.

    Example:
        ```python
        import os
        from saferaise import enable, disable

        ctx = enable if os.getenv("ENV") != "production" else disable
        with ctx():
            myapp.run()
        ```
    """
    token = _watched_exceptions.set(None)
    try:
        yield
    finally:
        _watched_exceptions.reset(token)

@contextmanager
def unsafe(*exceptions: type[BaseException]) -> Iterator[None]:
    """Add exceptions to the watched set without validating callers.

    Useful at bootstrapping boundaries where a ``try/except`` would be
    artificial - for example, entry points or test harnesses that need
    to manually declare which exceptions are acceptable.

    Args:
        *exceptions: Exception types to add to the watched set.

    Example:
        ```python
        from saferaise import enable, unsafe, raises


        @raises(ValueError)
        def parse(raw: str) -> int:
            return int(raw)


        with enable():
            with unsafe(ValueError):
                parse("abc")  # OK - ValueError manually added to watched set
        ```
    """
    token = _add_exceptions(*exceptions)
    try:
        yield
    finally:
        _reset_exceptions(token)