scverse_misc.Settings

class scverse_misc.Settings(_case_sensitive=None, _nested_model_default_partial_update=None, _env_prefix=None, _env_prefix_target=None, _env_file=PosixPath('.'), _env_file_encoding=None, _env_ignore_empty=None, _env_nested_delimiter=None, _env_nested_max_split=None, _env_parse_none_str=None, _env_parse_enums=None, _cli_prog_name=None, _cli_parse_args=None, _cli_settings_source=None, _cli_parse_none_str=None, _cli_hide_none_type=None, _cli_avoid_json=None, _cli_enforce_required=None, _cli_use_class_docs_for_groups=None, _cli_exit_on_error=None, _cli_prefix=None, _cli_flag_prefix_char=None, _cli_implicit_flags=None, _cli_ignore_unknown_args=None, _cli_kebab_case=None, _cli_shortcuts=None, _secrets_dir=None, _build_sources=None, **values)

Base class for package settings.

This class can be subclassed by individual packages to get package-specific settings handling. Settings will be validated on assignment thanks to Pydantic. The class requires the arguments exported_object_name and docstring_style, which will be used to construct a suitable docstring (see the examples).

Both a settings instance and its override and reset methods should be added to the package documentation. Note that the documentation is generated by the scverse_misc Sphinx extension, which must be enabled.

Thanks to Pydantic Settings, settings values will also be loaded from environment variables or .env files. Environment variables must be prefixex with $PACKAGE_NAME_ to take effect, where $PACKAGE_NAME is the name of the package of the subclass. This can be overridden by passing env_prefix=CUSTOMPREFIX as class argument.

Examples

>>> from typing import Annotated
... from pydantic import Field
... from scverse_misc import Settings
...
...
... class MySettings(Settings, exported_object_name="settings"):
...     eps: Annotated[float, Field(gt=0, lt=1)] = 1e-8
...     """Small epsilon for numerical stability."""
...
...     use_optional_feature: bool = False
...     """Whether to use the optional feature."""
...
...
... settings = MySettings()

See also

Settings class

Methods

override(**overrides)

Context manager for local setting overrides.

Subclasses will get a version with a docstring detailing the available parameters.

Return type:

Generator[None]

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.

Return type:

AbstractContextManager[frozenset[LiteralString]]