Sphinx extension

This package provides a Sphinx extension to create or adjust documentation. For example, using the deprecated decorator adds a deprecation notice to the function’s description. To use the extension, add "scverse_misc.sphinx_ext" to your extensions array in conf.py. The extension requires scverse_misc to be installed with the sphinx extra.

Important

The scverse_misc.sphinx_ext extension must be listed before sphinx.ext.napoleon, otherwise it will not work.

Examples

Deprecating a function

source

from scverse_misc import deprecated, Deprecation


@deprecated(Deprecation("0.3.1", "Use bar instead."))
def foo(a: int, b: str) -> None:
    """Frobnicates its arguments.

    Args:
        a: The frobnicator.
        b: The frobnicatee.
    """

rendered

deprecated_decorator.foo(a, b)

Frobnicates its arguments.

Deprecated since version 0.3.1: Use bar instead.

Parameters:

• a (int) – The frobnicator.

• b (str) – The frobnicatee.

Return type:

None

Deprecating a function argument

source

from scverse_misc import deprecated_arg, Deprecation


@deprecated_arg("b", Deprecation("0.3.1", "Use function `bar()` instead."))
def foo(a: int, b: str) -> None:
    """Frobnicates its arguments.

    Args:
        a: The frobnicator.
        b: The frobnicatee.
    """

rendered

deprecated_arg.foo(a, b)

Frobnicates its arguments.

Parameters:

• a (int) – The frobnicator.

• b (str) –

  Deprecated since version 0.3.1: Use function bar() instead.

  The frobnicatee.

Return type:

None

Settings class

source

from typing import Annotated

from scverse_misc import Settings, deprecated, Deprecation
from pydantic import Field


class _Settings(Settings):
    frobnicate: bool = False
    """Controls whether to frobnicate."""

    eps: Annotated[
        float,
        Field(gt=0, lt=1, deprecated=deprecated(Deprecation("0.4.2", "This functionality does not exist anymore."))),
    ] = 1e-8
    """Small epsilon for numerical stability"""


settings = _Settings()

rendered

package.settings = _Settings(frobnicate=False, eps=1e-08)

Allows users to customize settings for the package package.

Settings here will generally be for advanced use-cases and should be used with caution.

For setting an option use override() (local) or set the attributes directly (global) e.g., package.settings.my_setting = foo. For assignment by environment variable, use the variable name in all caps with PACKAGE_ as the prefix before import of package.

The following options are available:

settings.frobnicate: bool = False

Controls whether to frobnicate.

settings.eps: float = 1e-08

Deprecated since version 0.4.2: This functionality does not exist anymore.

Small epsilon for numerical stability

package.settings.override(*, frobnicate=<no change>, eps=<no change>)

Provides local override via keyword arguments as a context manager.

Parameters:

• frobnicate (bool (default: <no change>)) – Controls whether to frobnicate.

• eps (float (default: <no change>)) – Small epsilon for numerical stability

Return type:

AbstractContextManager[None]

package.settings.reset(*names)

Reset passed settings to their default values.

Can be used as a context manager to make the resets temporary. On __enter__, the context manager returns the settings that have been changed.

Parameters:

names (Literal['frobnicate', 'eps'])

Return type:

AbstractContextManager[frozenset[Literal['frobnicate', 'eps']]]

Extension namespaces

source

from scverse_misc import make_register_namespace_decorator


class DummyClass:
    """Some class to extend."""


register_namespace = make_register_namespace_decorator(DummyClass, "dummy")

rendered

class extension.DummyClass

Some class to extend.

@extension.register_namespace(name)

Decorator for registering custom functionality with a DummyClass object.

This decorator allows you to extend DummyClass objects with custom methods and properties organized under a namespace. The namespace becomes accessible as an attribute on DummyClass instances, providing a clean way to you to add domain-specific functionality without modifying the DummyClass class itself, or extending the class with additional methods as you see fit in your workflow.

Parameters:

name (str) – Name under which the accessor should be registered. This will be the attribute name used to access your namespace’s functionality on DummyClass objects (e.g., instance.name). Cannot conflict with existing DummyClass attributes. The list of reserved attributes includes everything outputted by dir(DummyClass).

Return type:

Callable[[type[TypeVar(NameSpT, bound= ExtensionNamespace)]], type[TypeVar(NameSpT, bound= ExtensionNamespace)]]

Returns:

A decorator that registers the decorated class as a custom namespace.

Notes

Implementation requirements:

1. The decorated class must have an __init__ method that accepts exactly one parameter (besides self) named dummy and annotated with type DummyClass.

2. The namespace will be initialized with the DummyClass object on first access and then cached on the instance.

3. If the namespace name conflicts with an existing namespace, a warning is issued.

4. If the namespace name conflicts with a built-in DummyClass attribute, an AttributeError is raised.”,

Examples

>>> @register_namespace("do_something")
... class DoSomething:
...     def __init__(self, dummy: DummyClass):
...         self._obj = dummy
...
...     def has_foo(self) -> bool:
...         return hasattr(self._obj, "foo")
>>>
>>> # Create a DummyClass object
>>> obj = DummyClass()
>>>
>>> # use the registered namespace
>>> obj.do_something.has_foo()
False