scverse-misc 0.0.2__tar.gz → 0.0.4__tar.gz

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/.github/workflows/test.yaml

@@ -27,12 +27,12 @@ jobs:
     outputs:
       envs: ${{ steps.get-envs.outputs.envs }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           filter: blob:none
           fetch-depth: 0
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
       - name: Get test environments
         id: get-envs
         run: |
@@ -64,12 +64,12 @@ jobs:
     continue-on-error: ${{ contains(matrix.env.name, 'pre') }}  # make "all-green" pass even if pre-release job fails
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           filter: blob:none
           fetch-depth: 0
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           python-version: ${{ matrix.env.python }}
       - name: create hatch environment

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/.pre-commit-config.yaml

@@ -7,16 +7,16 @@ default_stages:
 minimum_pre_commit_version: 2.16.0
 repos:
   - repo: https://github.com/biomejs/pre-commit
-    rev: v2.4.6
+    rev: v2.4.12
     hooks:
       - id: biome-format
         exclude: ^\.cruft\.json$ # inconsistent indentation with cruft - file never to be modified manually.
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: v2.16.2
+    rev: v2.21.1
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.5
+    rev: v0.15.11
     hooks:
       - id: ruff-check
         types_or: [python, pyi, jupyter]
@@ -36,3 +36,13 @@ repos:
       # Check that there are no merge conflicts (could be generated by template sync)
       - id: check-merge-conflict
         args: [--assume-in-merge]
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.20.1
+    hooks:
+    - id: mypy
+      args: []
+      additional_dependencies:
+      - pydantic-settings
+      - pytest
+      - sphinx
+      - sphinxcontrib-katex

scverse_misc-0.0.4/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog][],
+and this project adheres to [Semantic Versioning][].
+
+[keep a changelog]: https://keepachangelog.com/en/1.1.0/
+[semantic versioning]: https://semver.org/spec/v2.0.0.html
+
+## [0.0.4]
+
+## Added
+
+- A `Settings` base class that packages can inherit from for their settings. This is based
+  on [Pydantic Settings](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) and
+  provides validation for settings values as well as loading settings from environment variables and
+  `.env` files.
+
+## [0.0.3]
+
+## Added
+
+- A `deprecated` decorator wrapping `warnings.deprecated` that additionally modifies the
+  docstring to include a deprecation notice.
+
+## [0.0.2]
+
+## Removed
+
+- The Pandas utility functions
+
+## [0.0.1]
+
+- Initial release
+
+[0.0.4]: https://github.com/scverse/scverse-misc/releases/tag/v0.0.4
+[0.0.3]: https://github.com/scverse/scverse-misc/releases/tag/v0.0.3
+[0.0.2]: https://github.com/scverse/scverse-misc/releases/tag/v0.0.2
+[0.0.1]: https://github.com/scverse/scverse-misc/releases/tag/v0.0.1

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scverse-misc
-Version: 0.0.2
+Version: 0.0.4
 Summary: Miscellaneous utility code used by scverse packages
 Project-URL: Documentation, https://scverse-misc.readthedocs.io/
 Project-URL: Homepage, https://github.com/scverse/scverse-misc
@@ -38,13 +38,15 @@ License: BSD 3-Clause License
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.11
-Requires-Dist: pandas>=1
+Requires-Python: >=3.12
 Requires-Dist: session-info2
+Requires-Dist: typing-extensions; python_version < '3.13'
+Provides-Extra: settings
+Requires-Dist: pydantic-settings; extra == 'settings'
+Requires-Dist: python-dotenv; extra == 'settings'
 Description-Content-Type: text/markdown
 
 # scverse-misc
@@ -101,7 +103,7 @@ If you found a bug, please use the [issue tracker][].
 [scverse discourse]: https://discourse.scverse.org/
 [issue tracker]: https://github.com/scverse/scverse-misc/issues
 [tests]: https://github.com/scverse/scverse-misc/actions/workflows/test.yaml
-[codecov]: https://codecov.io/gh/bioFAM/mofaflex
+[codecov]: https://codecov.io/gh/scverse/scverse-misc
 [documentation]: https://scverse-misc.readthedocs.io
 [changelog]: https://scverse-misc.readthedocs.io/en/latest/changelog.html
 [api documentation]: https://scverse-misc.readthedocs.io/latest/api.html

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/README.md

@@ -52,7 +52,7 @@ If you found a bug, please use the [issue tracker][].
 [scverse discourse]: https://discourse.scverse.org/
 [issue tracker]: https://github.com/scverse/scverse-misc/issues
 [tests]: https://github.com/scverse/scverse-misc/actions/workflows/test.yaml
-[codecov]: https://codecov.io/gh/bioFAM/mofaflex
+[codecov]: https://codecov.io/gh/scverse/scverse-misc
 [documentation]: https://scverse-misc.readthedocs.io
 [changelog]: https://scverse-misc.readthedocs.io/en/latest/changelog.html
 [api documentation]: https://scverse-misc.readthedocs.io/latest/api.html

scverse_misc-0.0.4/docs/api/settings.rst

@@ -0,0 +1,8 @@
+scverse\_misc.Settings
+======================
+
+.. currentmodule:: scverse_misc
+
+.. autoclass:: Settings
+
+    .. automethod:: override

scverse_misc-0.0.4/docs/api.md

@@ -0,0 +1,44 @@
+# API
+
+```{eval-rst}
+.. currentmodule:: scverse_misc
+.. toctree::
+```
+
+## Extensions
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    make_register_namespace_decorator
+```
+Types used by the former:
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    ExtensionNamespace
+```
+
+## Deprecations
+```{eval-rst}
+.. autosummary::
+   :toctree: generated
+
+   deprecated
+   Deprecation
+```
+
+## Settings
+
+```{eval-rst}
+.. toctree::
+   :hidden:
+
+   api/settings
+
++---------------------------+----------------------------------+
+| :class:`Settings` ()      | Base class for package settings. |
++---------------------------+----------------------------------+
+```

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/docs/conf.py

@@ -26,7 +26,7 @@ project = info["Name"]
 author = info["Author"]
 copyright = f"{datetime.now():%Y}, {author}."
 version = info["Version"]
-urls = dict(pu.split(", ") for pu in info.get_all("Project-URL"))
+urls = dict(pu.split(", ") for pu in info.get_all("Project-URL") or ())
 repository_url = urls["Source"]
 
 # The full version, including alpha/beta/rc tags
@@ -101,6 +101,7 @@ intersphinx_mapping = {
     "scipy": ("https://docs.scipy.org/doc/scipy", None),
     "pandas": ("https://pandas.pydata.org/docs/", None),
     "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
+    "pydantic": ("https://pydantic.dev/docs/validation/", None),
 }
 
 # List of patterns, relative to source directory, that match files and
@@ -130,7 +131,7 @@ html_theme_options = {
 pygments_style = "default"
 katex_prerender = shutil.which(katex.NODEJS_BINARY) is not None
 
-nitpick_ignore = [
+nitpick_ignore: list[tuple[str, str]] = [
     # If building the documentation fails because of a missing link that is outside your control,
     # you can add an exception to this list.
     #     ("py:class", "igraph.Graph"),

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/docs/extensions/typed_returns.py

@@ -6,7 +6,8 @@ import re
 from collections.abc import Generator, Iterable
 
 from sphinx.application import Sphinx
-from sphinx.ext.napoleon import NumpyDocstring
+from sphinx.ext.napoleon.docstring import NumpyDocstring, GoogleDocstring
+from sphinx.util.typing import ExtensionMetadata
 
 
 def _process_return(lines: Iterable[str]) -> Generator[str, None, None]:
@@ -17,7 +18,7 @@ def _process_return(lines: Iterable[str]) -> Generator[str, None, None]:
             yield line
 
 
-def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:
+def _parse_returns_section(self: GoogleDocstring, section: str) -> list[str]:
     lines_raw = self._dedent(self._consume_to_next_section())
     if lines_raw[0] == ":":
         del lines_raw[0]
@@ -27,6 +28,7 @@ def _parse_returns_section(self: NumpyDocstring, section: str) -> list[str]:
     return lines
 
 
-def setup(app: Sphinx):
+def setup(app: Sphinx) -> ExtensionMetadata:
     """Set app."""
-    NumpyDocstring._parse_returns_section = _parse_returns_section
+    NumpyDocstring._parse_returns_section = _parse_returns_section  # type: ignore[method-assign]
+    return ExtensionMetadata(parallel_read_safe=True)

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/pyproject.toml

@@ -13,20 +13,20 @@ maintainers = [
 authors = [
   { name = "Ilia Kats" },
 ]
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 classifiers = [
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
 ]
 dynamic = [ "version" ]
 dependencies = [
-  "pandas>=1",
   # for debug logging (referenced from the issue template)
   "session-info2",
+  "typing-extensions; python_version<'3.13'",
 ]
+optional-dependencies.settings = [ "pydantic-settings", "python-dotenv" ]
 # https://docs.pypi.org/project_metadata/#project-urls
 urls.Documentation = "https://scverse-misc.readthedocs.io/"
 urls.Homepage = "https://github.com/scverse/scverse-misc"
@@ -37,12 +37,13 @@ dev = [
   "pre-commit",
   "twine>=4.0.2",
 ]
-test = [ "coverage>=7.10", "numpy", "pytest" ]
+test = [ "coverage>=7.10", "numpy", "pytest", "scverse-misc[settings]", "sphinx" ]
 doc = [
   "ipykernel",
   "ipython",
   "myst-nb>=1.1",
   "pandas",
+  "scverse-misc[settings]",
   "sphinx>=8.1",
   "sphinx-autodoc-typehints",
   "sphinx-book-theme>=1",
@@ -54,7 +55,6 @@ doc = [
 ]
 
 [tool.hatch]
-build.hooks.vcs.version-file = "src/scverse_misc/_version.py"
 envs.default.installer = "uv"
 envs.default.dependency-groups = [ "dev" ]
 envs.docs.dependency-groups = [ "doc" ]
@@ -64,7 +64,7 @@ envs.docs.scripts.clean = "git clean -fdX -- {args:docs}"
 envs.hatch-test.dependency-groups = [ "dev", "test" ]
 envs.hatch-test.matrix = [
   # Test the lowest and highest supported Python versions with normal deps
-  { deps = [ "stable" ], python = [ "3.11", "3.14" ] },
+  { deps = [ "stable" ], python = [ "3.12", "3.14" ] },
   # Test the newest supported Python version also with pre-release deps
   { deps = [ "pre" ], python = [ "3.14" ] },
 ]
@@ -95,6 +95,7 @@ lint.select = [
 ]
 lint.ignore = [
   "B008",   # Errors from function calls in argument defaults. These are fine when the result is immutable.
+  "C408",   # `dict()` is sometimes nicer than `{}`
   "D100",   # Missing docstring in public module
   "D104",   # Missing docstring in public package
   "D105",   # __magic__ methods are often self-explanatory, allow missing docstrings
@@ -114,6 +115,11 @@ lint.per-file-ignores."docs/*" = [ "I" ]
 lint.per-file-ignores."tests/*" = [ "D" ]
 lint.pydocstyle.convention = "google"
 
+[tool.mypy]
+strict = true
+explicit_package_bases = true
+mypy_path = [ "$MYPY_CONFIG_FILE_DIR/stubs", "$MYPY_CONFIG_FILE_DIR/src" ]
+
 [tool.pytest]
 strict = true
 testpaths = [ "tests" ]

scverse_misc-0.0.4/src/scverse_misc/__init__.py

@@ -0,0 +1,11 @@
+from contextlib import suppress
+
+from ._deprecated import Deprecation, deprecated
+from ._extensions import ExtensionNamespace, make_register_namespace_decorator
+
+__all__ = ["ExtensionNamespace", "make_register_namespace_decorator", "deprecated", "Deprecation"]
+
+with suppress(ImportError):
+    from ._settings import Settings
+
+    __all__.append("Settings")

scverse_misc-0.0.4/src/scverse_misc/_deprecated.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import sys
+from inspect import getdoc
+from typing import TYPE_CHECKING, LiteralString
+
+if sys.version_info >= (3, 13):
+    from warnings import deprecated as _deprecated
+else:
+    from typing_extensions import deprecated as _deprecated
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+__all__ = ["deprecated", "Deprecation"]
+
+
+class Deprecation(str):
+    """Utility class storing information on deprecated functionality.
+
+    Args:
+        version_deprecated: The version of the package where the functionality was deprecated.
+        msg: The deprecation message.
+    """
+
+    version_deprecated: LiteralString
+
+    def __new__(cls, version_deprecated: LiteralString, msg: LiteralString = "") -> LiteralString:  # type: ignore[misc]  # typing.Intersection doesn’t exist yet
+        if not msg:
+            msg = ""  # be lenient here, people don’t want to see “None” or “False” here
+        obj = super().__new__(cls, msg)
+        obj.version_deprecated = version_deprecated
+        return obj
+
+
+def _deprecated_at[F: Callable[..., object]](
+    msg: Deprecation, *, category: type[Warning] = FutureWarning, stacklevel: int = 1
+) -> Callable[[F], F]:
+    """Decorator to indicate that a class, function, or overload is deprecated.
+
+    Wraps :func:`warnings.deprecated` and additionally modifies the docstring to include a deprecation notice.
+
+    Args:
+        msg: The deprecation message.
+        category: The category of the warning that will be emitted at runtime.
+        stacklevel: The stack level of the warning.
+
+    Examples:
+        >>> @deprecated(Deprecation("0.2", "Use bar() instead."))
+        ... def foo(baz):
+        ...     pass
+    """
+
+    def decorate(func: F) -> F:
+        kind = "function" if func.__name__ == func.__qualname__ else "method"
+        warnmsg = f"The {kind} {func.__name__} is deprecated and will be removed in the future."
+
+        doc = getdoc(func)
+        docmsg = f".. version-deprecated:: {msg.version_deprecated}"
+        if len(msg):
+            docmsg += f"\n   {msg}"
+            warnmsg += f" {msg}"
+
+        if doc is None:
+            doc = docmsg
+        else:
+            lines = doc.splitlines()
+            body = "\n".join(lines[1:])
+            doc = f"{lines[0]}\n\n{docmsg}\n{body}"
+        func.__doc__ = doc
+
+        return _deprecated(warnmsg, category=category, stacklevel=stacklevel)(func)
+
+    return decorate
+
+
+if TYPE_CHECKING:
+    deprecated = _deprecated
+else:
+    deprecated = _deprecated_at

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/src/scverse_misc/_extensions.py

@@ -1,14 +1,24 @@
+"""System to add extension attributes to classes.
+
+Based off of the extension framework in Polars:
+https://github.com/pola-rs/polars/blob/main/py-polars/polars/api.py
+"""
+
 from __future__ import annotations
 
 import inspect
+import sys
 import warnings
 from itertools import islice
-from typing import TYPE_CHECKING, Generic, Literal, Protocol, TypeVar, get_type_hints, overload, runtime_checkable
+from typing import TYPE_CHECKING, Literal, Protocol, get_type_hints, overload, runtime_checkable
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Set
 
 
+__all__ = ["make_register_namespace_decorator", "ExtensionNamespace"]
+
+
 @runtime_checkable
 class ExtensionNamespace(Protocol):
     """Protocol for extension namespaces.
@@ -19,21 +29,11 @@ class ExtensionNamespace(Protocol):
     checking with mypy and IDEs.
     """
 
-    def __init__(self, instance) -> None:
+    def __init__(self, instance: object) -> None:
         """Used to enforce the correct signature for extension namespaces."""
 
 
-# Based off of the extension framework in Polars
-# https://github.com/pola-rs/polars/blob/main/py-polars/polars/api.py
-
-__all__ = ["make_register_namespace_decorator", "ExtensionNamespace"]
-
-
-NameSpT = TypeVar("NameSpT", bound=ExtensionNamespace)
-T = TypeVar("T")
-
-
-class AccessorNameSpace(ExtensionNamespace, Generic[NameSpT]):
+class AccessorNameSpace[T, NameSpT: ExtensionNamespace]:
     """Establish property-like namespace object for user-defined functionality."""
 
     def __init__(self, name: str, namespace: type[NameSpT]) -> None:
@@ -50,7 +50,7 @@ class AccessorNameSpace(ExtensionNamespace, Generic[NameSpT]):
         if instance is None:
             return self._ns
 
-        ns_instance = self._ns(instance)  # type: ignore[call-arg]
+        ns_instance = self._ns(instance)
         setattr(instance, self._accessor, ns_instance)
         return ns_instance
 
@@ -81,7 +81,7 @@ def _check_namespace_signature(ns_class: type, cls: type, canonical_instance_nam
         TypeError: If both the name and type annotation of the second parameter are incorrect.
 
     """
-    sig = inspect.signature(ns_class.__init__)
+    sig = inspect.signature(ns_class.__init__)  # type: ignore[misc]  # https://github.com/python/mypy/issues/21236
     params = sig.parameters
 
     # Ensure there are at least two parameters (self and mdata)
@@ -89,9 +89,7 @@ def _check_namespace_signature(ns_class: type, cls: type, canonical_instance_nam
         raise TypeError(f"Namespace initializer must accept a {cls.__name__} instance as the second parameter.")
 
     # Get the second parameter (expected to be `canonical_instance_name`)
-    param = iter(params.values())
-    next(param)
-    param = next(param)
+    [_, param, *_] = params.values()
     if param.annotation is inspect.Parameter.empty:
         raise AttributeError(
             f"Namespace initializer's second parameter must be annotated as the {cls.__name__!r} class, got empty annotation."
@@ -101,7 +99,7 @@ def _check_namespace_signature(ns_class: type, cls: type, canonical_instance_nam
 
     # Resolve the annotation using get_type_hints to handle forward references and aliases.
     try:
-        type_hints = get_type_hints(ns_class.__init__)
+        type_hints = get_type_hints(ns_class.__init__)  # type: ignore[misc]  # https://github.com/python/mypy/issues/21236
         resolved_type = type_hints.get(param.name, param.annotation)
     except NameError as e:
         raise NameError(
@@ -130,7 +128,7 @@ def _check_namespace_signature(ns_class: type, cls: type, canonical_instance_nam
             )
 
 
-def _create_namespace(
+def _create_namespace[NameSpT: ExtensionNamespace](
     name: str, cls: type, reserved_namespaces: Set[str], canonical_instance_name: str
 ) -> Callable[[type[NameSpT]], type[NameSpT]]:
     """Register custom namespace against the underlying class."""
@@ -149,14 +147,14 @@ def _create_namespace(
     return namespace
 
 
-def _indent_string_lines(string: str, indentation_level: int, skip_lines: int = 0):
-    minspace = 1e6
+def _indent_string_lines(string: str, indentation_level: int, skip_lines: int = 0) -> str:
+    minspace = sys.maxsize
     for line in islice(string.splitlines(), 1, None):
         for i, char in enumerate(line):
             if not char.isspace():
                 minspace = min(minspace, i)
                 break
-    if minspace == 1e6:  # single-line string
+    if minspace == sys.maxsize:  # single-line string
         minspace = 0
     return "\n".join(
         " " * 4 * indentation_level + sline if i >= skip_lines else sline
@@ -165,7 +163,7 @@ def _indent_string_lines(string: str, indentation_level: int, skip_lines: int =
     )
 
 
-def make_register_namespace_decorator(
+def make_register_namespace_decorator[NameSpT: ExtensionNamespace](
     cls: type, canonical_instance_name: str, decorator_name: str, docstring_style: Literal["google", "numpy"] = "google"
 ) -> Callable[[str], Callable[[type[NameSpT]], type[NameSpT]]]:
     """Create a decorator for registering custom functionality with a class.

scverse_misc-0.0.4/src/scverse_misc/_settings.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import textwrap
+import warnings
+from collections.abc import Generator
+from contextlib import contextmanager
+from types import GenericAlias
+from typing import Literal
+
+import dotenv
+from pydantic.fields import FieldInfo
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
+
+from ._utils import copy_func
+
+
+def _type_str(field: FieldInfo) -> str:
+    return (
+        field.annotation.__name__
+        if isinstance(field.annotation, type) and not isinstance(field.annotation, GenericAlias)
+        else str(field.annotation)
+    )
+
+
+_docstring_template = """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 :func:`~{package}.{name}.override` (local) or set the attributes directly (global)
+i.e., `{package}.{name}.my_setting = foo`. For assignment by environment variable, use the variable name in
+all caps with `{env_prefix}` as the prefix before import of `{package}`.
+"""
+
+
+class Settings(BaseSettings):
+    '''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 one argument
+    `exported_object_name` and one optional argument `docstring_style`, which will be used to construct
+    a suitable docstring (see the examples).
+
+    Both a settings instance and its `override` method should be added to the package documentation.
+
+    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", docstring_style="numpy"):
+        ...     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()
+    '''
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return init_settings, env_settings, dotenv_settings
+
+    @staticmethod
+    def _get_packagename(subcls: type[Settings]) -> str:
+        package_name = subcls.__module__
+        dotidx = package_name.find(".")
+        if dotidx > -1:
+            package_name = package_name[:dotidx]
+        return package_name
+
+    def __init_subclass__(subcls, *, exported_object_name: str, docstring_style: Literal["google", "numpy"] = "google"):
+        if (config := subcls.__dict__.get("model_config")) is not None:
+            if not config.get("validate_assignment", True):
+                warnings.warn("`validate_assignment=False` is not supported, overriding.", RuntimeWarning, stacklevel=2)
+            if not config.get("use_attribute_docstrings", True):
+                warnings.warn(
+                    "`use_attribute_docstrings=False` is not supported, overriding.", RuntimeWarning, stacklevel=2
+                )
+            if config.get("env_file") is not None:
+                warnings.warn(
+                    "Setting a custom env_file location is not supported, overriding.", RuntimeWarning, stacklevel=2
+                )
+        else:
+            config = SettingsConfigDict()
+
+        config["validate_assignment"] = True
+        config["use_attribute_docstrings"] = True
+        config["env_file"] = dotenv.find_dotenv()
+
+        if not config.get("env_prefix"):
+            config["env_prefix"] = f"{__class__._get_packagename(subcls)}_"  # type: ignore[name-defined] # https://github.com/python/mypy/issues/4177
+        subcls.model_config = config
+
+        super().__init_subclass__()
+
+    @contextmanager
+    def override(self, **kwargs: object) -> Generator[None]:
+        """Context manager for local setting overrides.
+
+        Subclasses will get a version with a docstring detailing the available parameters.
+        """
+        oldsettings = {argname: getattr(self, argname) for argname in kwargs.keys()}
+        try:
+            for argname, argval in kwargs.items():
+                setattr(self, argname, argval)
+            yield
+        finally:
+            for argname, argval in reversed(oldsettings.items()):
+                setattr(self, argname, argval)
+
+    @classmethod
+    def __pydantic_init_subclass__(  # type: ignore[override]
+        subcls, *, exported_object_name: str, docstring_style: Literal["google", "numpy"] = "google"
+    ) -> None:
+        subcls.__doc__ = (
+            _docstring_template.format(
+                package=__class__._get_packagename(subcls),  # type: ignore[name-defined] # https://github.com/python/mypy/issues/4177
+                name=exported_object_name,
+                env_prefix=subcls.model_config["env_prefix"].upper(),
+            )
+            + "\n\nThe following options are available:\n"
+        )
+        override_doc = "Provides local override via keyword arguments as a context manager.\n\n"
+        if docstring_style == "google":
+            override_doc += "Args:\n"
+        else:
+            override_doc += "Parameters\n----------\n"
+        for fname, field in subcls.model_fields.items():
+            subcls.__doc__ += f"""
+.. attribute:: {exported_object_name}.{fname}
+   :type: {_type_str(field)}
+   :value: {field.default!r}\n"""
+
+            description = f"(default `{field.default!r}`) "
+            if field.description is not None:
+                subcls.__doc__ += f"\n{textwrap.indent(field.description, '   ')}\n"
+                description += field.description
+
+            if docstring_style == "google":
+                override_doc += f"""    {fname} ({_type_str(field)}): {textwrap.indent(description, "        ")}\n"""
+            else:
+                override_doc += f"""
+{fname} : {_type_str(field)}
+{textwrap.indent(description, "    ")}\n"""
+
+        subcls.override = copy_func(  # type: ignore[method-assign,type-var]
+            subcls.override,
+            __doc__=override_doc,
+            __module__=subcls.__module__,
+            __qualname__=f"{subcls.__qualname__}.override",
+        )

scverse_misc-0.0.4/src/scverse_misc/_utils.py

@@ -0,0 +1,25 @@
+import functools
+import sys
+from functools import WRAPPER_ASSIGNMENTS
+from types import FunctionType
+from typing import ParamSpec, TypedDict, TypeVar, TypeVarTuple, Unpack, cast
+
+
+class Overrides(TypedDict, total=False):
+    __module__: str
+    __name__: str
+    __qualname__: str
+    __doc__: str
+    # ≥3.14: __annotate__, <3.14: __annotations__
+    __type_params__: tuple[TypeVar | TypeVarTuple | ParamSpec, ...]
+
+
+def copy_func[F: FunctionType](func: F, /, **overrides: Unpack[Overrides]) -> F:
+    kw = dict(kwdefaults=func.__kwdefaults__) if sys.version_info >= (3, 13) else {}
+    new = FunctionType(
+        func.__code__, func.__globals__, name=func.__name__, argdefs=func.__defaults__, closure=func.__closure__, **kw
+    )
+    for key, value in overrides.items():
+        setattr(new, key, value)
+    copy = set(WRAPPER_ASSIGNMENTS) - overrides.keys()
+    return cast("F", functools.update_wrapper(new, func, assigned=copy))

scverse_misc-0.0.4/stubs/sphinxcontrib/__init__.pyi

@@ -0,0 +1,2 @@
+# mypy doesn’t understand namespace packages apparently
+from . import katex as katex

scverse_misc-0.0.4/stubs/sphinxcontrib/katex.pyi

@@ -0,0 +1,8 @@
+STARTUP_TIMEOUT: float
+"""How long to wait for the render server to start in seconds."""
+
+RENDER_TIMEOUT: float
+"""Timeout per rendering request in seconds."""
+
+NODEJS_BINARY: str
+"""nodejs binary to run javascript."""

scverse_misc-0.0.4/tests/test_deprecation_decorator.py

@@ -0,0 +1,65 @@
+from collections.abc import Callable
+from typing import cast
+
+import pytest
+
+from scverse_misc import Deprecation, deprecated
+
+
+@pytest.fixture(params=[pytest.param(None, id="no_message"), pytest.param("Test message.", id="message")])
+def msg(request: pytest.FixtureRequest) -> str | None:
+    return cast(str | None, request.param)
+
+
+@pytest.fixture(
+    params=[
+        pytest.param(None, id="no_docstring"),
+        pytest.param("Test function", id="short"),
+        pytest.param(
+            """Test function
+
+            This is a test.
+
+            Parameters
+            ----------
+            foo
+                bar
+            bar
+                baz
+            """,
+            id="long",
+        ),
+    ]
+)
+def docstring(request: pytest.FixtureRequest) -> str | None:
+    return cast(str | None, request.param)
+
+
+@pytest.fixture
+def deprecated_func(msg: str | None, docstring: str | None) -> Callable[[int, int], int]:
+    def func(foo: int, bar: int) -> int:
+        return 42
+
+    func.__doc__ = docstring
+    return deprecated(Deprecation("foo", msg or ""))(func)
+
+
+def test_deprecation_decorator(
+    deprecated_func: Callable[[int, int], int], docstring: str | None, msg: str | None
+) -> None:
+    with pytest.warns(FutureWarning, match="deprecated"):
+        assert deprecated_func(1, 2) == 42
+
+    assert deprecated_func.__doc__ is not None
+    lines = deprecated_func.__doc__.expandtabs().splitlines()
+    if docstring is None:
+        assert lines[0].startswith(".. version-deprecated::")
+    else:
+        lines_orig = docstring.expandtabs().splitlines()
+        assert lines[0] == lines_orig[0]
+        assert len(lines[1].strip()) == 0
+        assert lines[2].startswith(".. version-deprecated")
+        if msg is None:
+            assert len(lines) == 3 or not lines[3].startswith("   ")
+        else:
+            assert lines[3] == f"   {msg}"

{scverse_misc-0.0.2 → scverse_misc-0.0.4}/tests/test_extensions.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol
 
 import pytest
 
@@ -11,16 +11,20 @@ if TYPE_CHECKING:
     from collections.abc import Generator
 
 
+class Greeter(Protocol):
+    def __init__(self, obj: DummyClass) -> None: ...
+    def greet(self) -> str: ...
+
+
 class DummyClass:
-    foo = []
+    foo: list[object] = []
     bar = None
 
     @property
-    def baz(self):
-        pass
+    def baz(self) -> None: ...
+    def foobar(self) -> None: ...
 
-    def foobar(self):
-        pass
+    dummy: Greeter  # available when using `dummy_namespace` fixture
 
 
 register_dummy_namespace = make_register_namespace_decorator(DummyClass, "obj", "register_dummy_namespace")
@@ -72,16 +76,18 @@ def test_accessor_namespace() -> None:
 
     # Define a dummy namespace class to be used via the descriptor.
     class DummyNamespace:
-        def __init__(self, obj: DummyClass):
+        def __init__(self, obj: Dummy):
             self._obj = obj
 
         def foo(self) -> str:
             return "foo"
 
     class Dummy:
-        pass
+        dummy: DummyNamespace  # just typing, runtime added below
 
-    descriptor = extensions.AccessorNameSpace("dummy", DummyNamespace)
+    descriptor: extensions.AccessorNameSpace[Dummy, DummyNamespace] = extensions.AccessorNameSpace(
+        "dummy", DummyNamespace
+    )
 
     # When accessed on the class, it should return the namespace type.
     ns_class = descriptor.__get__(None, Dummy)
@@ -204,7 +210,7 @@ def test_missing_annotation() -> None:
 
         @register_dummy_namespace("missing_annotation")
         class MissingAnnotationNamespace:
-            def __init__(self, obj) -> None:
+            def __init__(self, obj) -> None:  # type: ignore[no-untyped-def]
                 self.obj = obj
 
 

scverse_misc-0.0.4/tests/test_settings.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Annotated, Literal, cast
+
+import pytest
+from pydantic import Field, ValidationError
+from pydantic.fields import FieldInfo
+from pydantic_settings import SettingsConfigDict
+from sphinx.ext.napoleon import GoogleDocstring, NumpyDocstring  # type: ignore[attr-defined]
+
+from scverse_misc import Settings
+
+if TYPE_CHECKING:
+    # Static version of the class returned by the `settings_class` fixture
+    class DummySettings(Settings, exported_object_name="settings"):
+        field_bool: bool = False
+        field_no_docstring: int = 42
+        field_int_range: int = 1
+
+
+@pytest.fixture
+def docstring_style(request: pytest.FixtureRequest) -> Literal["google", "numpy"]:
+    return getattr(request, "param", "google")
+
+
+@pytest.fixture
+def settings_class(docstring_style: Literal["google", "numpy"]) -> type[DummySettings]:
+    class _DummySettings(Settings, exported_object_name="settings", docstring_style=docstring_style):
+        field_bool: bool = False
+        """Boolean field."""
+
+        field_no_docstring: int = 42
+
+        field_int_range: Annotated[int, Field(ge=0, le=4)] = 1
+        """Integer range field."""
+
+    return cast("type[DummySettings]", _DummySettings)
+
+
+@pytest.fixture
+def settings(settings_class: type[DummySettings]) -> DummySettings:
+    return settings_class()
+
+
+def test_defaults_override() -> None:
+    with (
+        pytest.warns(RuntimeWarning, match="validate_assignment=False"),
+        pytest.warns(RuntimeWarning, match="use_attribute_docstrings=False"),
+        pytest.warns(RuntimeWarning, match="custom env_file location"),
+    ):
+
+        class WarnSettings(Settings, exported_object_name="settings"):
+            model_config = SettingsConfigDict(
+                validate_assignment=False, use_attribute_docstrings=False, env_file="mydotenv"
+            )
+
+            field_bool: bool = False
+
+    settings = WarnSettings()
+    with pytest.raises(ValidationError):
+        settings.field_bool = 2  # type: ignore[assignment]
+
+
+@pytest.mark.parametrize("v", [2, 4])
+def test_env_vars(monkeypatch: pytest.MonkeyPatch, settings_class: type[DummySettings], v: int) -> None:
+    """Test that the env var prefix is derived from the module name."""
+    monkeypatch.setenv("TESTS_FIELD_INT_RANGE", str(v))
+    settings = settings_class()
+    assert settings.field_int_range == v
+
+
+def test_validate_assignment(settings: DummySettings) -> None:
+    with pytest.raises(ValidationError):
+        settings.field_bool = 2  # type: ignore[assignment]
+    with pytest.raises(ValidationError):
+        settings.field_int_range = -1
+
+
+def test_override(settings: DummySettings) -> None:
+    with settings.override(field_bool=True):
+        assert settings.field_bool is True
+    assert settings.field_bool is False
+
+    with pytest.raises(ValidationError):
+        with settings.override(field_int_range=3, field_no_docstring=1.1):
+            pass
+    assert settings.field_no_docstring == 42
+    assert settings.field_int_range == 1
+
+
+@pytest.mark.parametrize("docstring_style", ["google", "numpy"], indirect=True)
+def test_docs(docstring_style: Literal["google", "numpy"], settings: DummySettings) -> None:
+    parser = GoogleDocstring if docstring_style == "google" else NumpyDocstring
+    lines = parser(inspect.getdoc(settings)).lines()  # type: ignore[arg-type]
+
+    assert lines[0].endswith("`tests` package.")
+
+    current_field: FieldInfo | None = None
+    field_iter = iter(type(settings).model_fields.items())
+    for line in lines:
+        if line.startswith(".. attribute::"):
+            current_field_name, current_field = next(field_iter)
+            assert line.endswith(current_field_name)
+        elif current_field is not None:
+            line = line.strip()
+            if line.startswith(":type:"):
+                assert current_field.annotation is not None
+                assert line.endswith(current_field.annotation.__name__)
+            elif line.startswith(":value:"):
+                assert line.endswith(repr(current_field.default))
+            elif len(line) > 0 and current_field.description is not None:
+                assert line == current_field.description
+
+
+@pytest.mark.parametrize("docstring_style", ["google", "numpy"], indirect=True)
+def test_override_docs(docstring_style: Literal["google", "numpy"], settings: DummySettings) -> None:
+    parser = GoogleDocstring if docstring_style == "google" else NumpyDocstring
+    lines = parser(inspect.getdoc(settings.override)).lines()  # type: ignore[arg-type]
+
+    current_field: FieldInfo | None = None
+    field_iter = iter(type(settings).model_fields.items())
+    for line in lines:
+        if line.startswith(":param"):
+            current_field_name, current_field = next(field_iter)
+            description = " " + current_field.description if current_field.description is not None else ""
+            assert line.startswith(f":param {current_field_name}: (default `{current_field.default!r}`){description}")
+        elif current_field is not None and len(line) > 0:
+            assert line == f":type {current_field_name}: {current_field.annotation.__name__}"  # type: ignore[union-attr]

scverse_misc-0.0.2/CHANGELOG.md

@@ -1,15 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog][],
-and this project adheres to [Semantic Versioning][].
-
-[keep a changelog]: https://keepachangelog.com/en/1.0.0/
-[semantic versioning]: https://semver.org/spec/v2.0.0.html
-
-## [Unreleased]
-
-### Added
-
-- Basic tool, preprocessing and plotting functions

scverse_misc-0.0.2/docs/api.md

@@ -1,22 +0,0 @@
-# API
-
-```{eval-rst}
-.. currentmodule:: scverse_misc
-.. toctree::
-```
-
-## Extensions
-
-``` {eval-rst}
-.. autosummary::
-    :toctree: generated
-
-    make_register_namespace_decorator
-```
-Types used by the former:
-``` {eval-rst}
-.. autosummary::
-    :toctree: generated
-
-    ExtensionNamespace
-```

scverse_misc-0.0.2/src/scverse_misc/__init__.py

@@ -1,2 +0,0 @@
-from ._extensions import ExtensionNamespace, make_register_namespace_decorator
-from ._version import __version__, __version_tuple__

scverse_misc-0.0.2/src/scverse_misc/_version.py

@@ -1,34 +0,0 @@
-# file generated by setuptools-scm
-# don't change, don't track in version control
-
-__all__ = [
-    "__version__",
-    "__version_tuple__",
-    "version",
-    "version_tuple",
-    "__commit_id__",
-    "commit_id",
-]
-
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Tuple
-    from typing import Union
-
-    VERSION_TUPLE = Tuple[Union[int, str], ...]
-    COMMIT_ID = Union[str, None]
-else:
-    VERSION_TUPLE = object
-    COMMIT_ID = object
-
-version: str
-__version__: str
-__version_tuple__: VERSION_TUPLE
-version_tuple: VERSION_TUPLE
-commit_id: COMMIT_ID
-__commit_id__: COMMIT_ID
-
-__version__ = version = '0.0.2'
-__version_tuple__ = version_tuple = (0, 0, 2)
-
-__commit_id__ = commit_id = None