scverse-misc 0.0.1__py3-none-any.whl

scverse_misc/__init__.py

@@ -0,0 +1,3 @@
+from ._extensions import ExtensionNamespace, make_register_namespace_decorator
+from ._pandas_utils import try_convert_dataframe_to_numpy_dtypes, try_convert_series_to_numpy_dtype
+from ._version import __version__, __version_tuple__

scverse_misc/_extensions.py

@@ -0,0 +1,265 @@
+from __future__ import annotations
+
+import inspect
+import warnings
+from itertools import islice
+from typing import TYPE_CHECKING, Generic, Literal, Protocol, TypeVar, get_type_hints, overload, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Set
+
+
+@runtime_checkable
+class ExtensionNamespace(Protocol):
+    """Protocol for extension namespaces.
+
+    Enforces that the namespace initializer accepts a class with the proper `__init__` method.
+    Protocol's can't enforce that the `__init__` accepts the correct types. See
+    `_check_namespace_signature` for that. This is mainly useful for static type
+    checking with mypy and IDEs.
+    """
+
+    def __init__(self, instance) -> 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]):
+    """Establish property-like namespace object for user-defined functionality."""
+
+    def __init__(self, name: str, namespace: type[NameSpT]) -> None:
+        self._accessor = name
+        self._ns = namespace
+
+    @overload
+    def __get__(self, instance: None, cls: type[T]) -> type[NameSpT]: ...
+
+    @overload
+    def __get__(self, instance: T, cls: type[T]) -> NameSpT: ...
+
+    def __get__(self, instance: T | None, cls: type[T]) -> NameSpT | type[NameSpT]:
+        if instance is None:
+            return self._ns
+
+        ns_instance = self._ns(instance)  # type: ignore[call-arg]
+        setattr(instance, self._accessor, ns_instance)
+        return ns_instance
+
+
+def _check_namespace_signature(ns_class: type, cls: type, canonical_instance_name: str) -> None:
+    """Validate the signature of a namespace class for extensions.
+
+    This function ensures that any class intended to be used as an extension namespace
+    has a properly formatted `__init__` method such that:
+
+    1. Accepts at least two parameters (self and the instance of the extended class)
+    2. Has `canonical_instance_name` as the name of the second parameter
+    3. Has the second parameter properly type-annotated as `ns_class` or any equivalent import alias
+
+    The function performs runtime validation of these requirements before a namespace
+    can be registered through the `register_namespace` decorator.
+
+    Args:
+        ns_class: The namespace class to validate.
+        cls: The class that is being extended.
+        canonical_instance_name: The name of the `ns_class` constructor argument.
+
+    Raises:
+        TypeError: If the `__init__` method has fewer than 2 parameters (missing the instance parameter).
+        AttributeError: If the second parameter of `__init__` lacks a type annotation.
+        TypeError: If the second parameter of `__init__` is not named `canonical_instance_name`.
+        TypeError: If the second parameter of `__init__` is not annotated as the `ns_class` class.
+        TypeError: If both the name and type annotation of the second parameter are incorrect.
+
+    """
+    sig = inspect.signature(ns_class.__init__)
+    params = sig.parameters
+
+    # Ensure there are at least two parameters (self and mdata)
+    if len(params) < 2:
+        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)
+    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."
+        )
+
+    name_ok = param.name == canonical_instance_name
+
+    # Resolve the annotation using get_type_hints to handle forward references and aliases.
+    try:
+        type_hints = get_type_hints(ns_class.__init__)
+        resolved_type = type_hints.get(param.name, param.annotation)
+    except NameError as e:
+        raise NameError(
+            f"Namespace initializer's second parameter must be named {canonical_instance_name!r}, got '{param.name}'."
+        ) from e
+
+    type_ok = resolved_type is cls
+
+    match (name_ok, type_ok):
+        case (True, True):
+            return  # Signature is correct.
+        case (False, True):
+            raise TypeError(
+                f"Namespace initializer's second parameter must be named {canonical_instance_name!r}, got {param.name!r}."
+            )
+        case (True, False):
+            type_repr = getattr(resolved_type, "__name__", str(resolved_type))
+            raise TypeError(
+                f"Namespace initializer's second parameter must be annotated as the {cls.__name__!r} class, got {type_repr!r}."
+            )
+        case _:
+            type_repr = getattr(resolved_type, "__name__", str(resolved_type))
+            raise TypeError(
+                f"Namespace initializer's second parameter must be named {canonical_instance_name!r}, got {param.name!r}. "
+                f"And must be annotated as {cls.__name__!r}, got {type_repr!r}."
+            )
+
+
+def _create_namespace(
+    name: str, cls: type, reserved_namespaces: Set[str], canonical_instance_name: str
+) -> Callable[[type[NameSpT]], type[NameSpT]]:
+    """Register custom namespace against the underlying class."""
+
+    def namespace(ns_class: type[NameSpT]) -> type[NameSpT]:
+        _check_namespace_signature(ns_class, cls, canonical_instance_name)  # Perform the runtime signature check
+        if name in reserved_namespaces:
+            raise AttributeError(f"cannot override reserved attribute {name!r}")
+        elif hasattr(cls, name):
+            warnings.warn(
+                f"Overriding existing custom namespace {name!r} (on {cls.__name__!r})", UserWarning, stacklevel=2
+            )
+        setattr(cls, name, AccessorNameSpace(name, ns_class))
+        return ns_class
+
+    return namespace
+
+
+def _indent_string_lines(string: str, indentation_level: int, skip_lines: int = 0):
+    minspace = 1e6
+    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
+        minspace = 0
+    return "\n".join(
+        " " * 4 * indentation_level + sline if i >= skip_lines else sline
+        for i, line in enumerate(string.splitlines())
+        if (sline := (line[minspace:] if i > 0 else line)) or True
+    )
+
+
+def make_register_namespace_decorator(
+    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.
+
+    The decorator will allow your users to extend `cls` objects with custom methods and properties
+    organized under a namespace. The namespace becomes accessible as an attribute on `cls` instances,
+    providing a clean way for users to add domain-specific functionality without modifying the `cls`
+    class itself.
+
+    The return decorator will have a docstring describing how to use it along with examples.
+
+    Args:
+        cls: The class to be made extensible.
+        canonical_instance_name: The typical name of an instance of `cls`, e.g. `adata` for `AnnData`. This
+            is used for run-time checking of constructor signatures of the namespace classes.
+        decorator_name: The name under which the decorator is accessible in your package. This is used for
+            the examples in the decorator docstring.
+        docstring_style: Whether the docstring of the generated decorator should conform to NumPy or Google
+            style.
+    """
+    # Reserved namespaces include accessors built into cls and all current attributes of cls
+    reserved_namespaces = set(dir(cls))
+
+    def decorator(name: str) -> Callable[[type[NameSpT]], type[NameSpT]]:
+        return _create_namespace(name, cls, reserved_namespaces, canonical_instance_name)
+
+    decorator_arg_description = f"""Name under which the accessor should be registered. This will be the attribute name
+            used to access your namespace's functionality on {cls.__name__} objects (e.g., `instance.name`).
+            Cannot conflict with existing {cls.__name__} attributes. The list of reserved attributes includes
+            everything outputted by `dir({cls.__name__})`."""
+    decorator_return_description = "A decorator that registers the decorated class as a custom namespace."
+    decorator_notes = f"""Implementation requirements:
+
+        1. The decorated class must have an `__init__` method that accepts exactly one parameter
+           (besides `self`) named `{canonical_instance_name}` and annotated with type :class:`~{cls.__module__}.{cls.__name__}`.
+        2. The namespace will be initialized with the {cls.__name__} 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 {cls.__name__} attribute, an AttributeError is raised."""
+    decorator_examples = f""">>> @{decorator_name}("do_something")
+        ... class DoSomething:
+        ...     def __init__(self, {canonical_instance_name}: {cls.__name__}):
+        ...         self._obj = {canonical_instance_name}
+        ...
+        ...     def has_foo(self) -> bool:
+        ...         return hasattr(self._obj, "foo")
+        >>>
+        >>> # Create a {cls.__name__} object
+        >>> obj = {cls.__name__}()
+        >>>
+        >>> # use the registered namespace
+        >>> obj.do_something.has_foo()
+        False"""
+
+    decorator.__doc__ = f"""Decorator for registering custom functionality with a :class:`~{cls.__module__}.{cls.__name__}` object.
+
+    This decorator allows you to extend {cls.__name__} objects with custom methods and properties
+    organized under a namespace. The namespace becomes accessible as an attribute on {cls.__name__}
+    instances, providing a clean way to you to add domain-specific functionality without modifying
+    the {cls.__name__} class itself, or extending the class with additional methods as you see fit in your workflow.
+    """
+
+    if docstring_style == "google":
+        decorator.__doc__ += f"""
+    Args:
+        name: {_indent_string_lines(decorator_arg_description, 3, 1)}
+
+    Returns:
+        {_indent_string_lines(decorator_return_description, 2, 1)}
+
+    Notes:
+        {_indent_string_lines(decorator_notes, 2, 1)}
+
+    Examples:
+        {_indent_string_lines(decorator_examples, 2, 1)}
+    """
+    else:
+        decorator.__doc__ += f"""
+    Parameters
+    ----------
+    name
+        {_indent_string_lines(decorator_arg_description, 2, 1)}
+
+    Returns
+    -------
+    {_indent_string_lines(decorator_return_description, 1, 1)}
+
+    Notes
+    -----
+    {_indent_string_lines(decorator_notes, 1, 1)}
+
+    Examples
+    --------
+    {_indent_string_lines(decorator_examples, 1, 1)}
+    """
+
+    return decorator

scverse_misc/_pandas_utils.py

@@ -0,0 +1,38 @@
+from collections.abc import Mapping
+from contextlib import suppress
+
+import pandas as pd
+
+
+def try_convert_series_to_numpy_dtype(col: pd.Series) -> pd.Series:
+    """Attempt to convert a :class:`~pandas.Series` to a non-nullable dtype.
+
+    Args:
+        col: The series to be converted.
+
+    Returns:
+        The converted series, `col` did not contain any :data:`~pandas.NA` values, the unmodified `col` otherwise.
+    """
+    with suppress(ValueError):
+        match col.dtype:
+            case pd.BooleanDtype():
+                col = col.astype(bool)
+            case pd.core.arrays.integer.IntegerDtype(type=dtype) | pd.core.arrays.floating.FloatingDtype(type=dtype):
+                col = col.astype(dtype)
+    return col
+
+
+def try_convert_dataframe_to_numpy_dtypes(df: pd.DataFrame | Mapping[str, pd.Series]) -> pd.DataFrame:
+    """Attempt to convert all columns of a :class:`~pandas.DataFrame` to their respective non-nullable dtype.
+
+    Args:
+        df: The dataframe to be converted.
+
+    Returns:
+        A new dataframe with each column of `df` that had a nullable dtype but did not contain any :data:`~pandas.NA`
+        values converted to the corresponding non-nullable dtype.
+    """
+    new_cols = {}
+    for colname, col in df.items():
+        new_cols[colname] = try_convert_series_to_numpy_dtype(col)
+    return pd.DataFrame(new_cols)

scverse_misc/_version.py

@@ -0,0 +1,34 @@
+# 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.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

scverse_misc-0.0.1.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: scverse-misc
+Version: 0.0.1
+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
+Project-URL: Source, https://github.com/scverse/scverse-misc
+Author: Ilia Kats
+Maintainer-email: Ilia Kats <i.kats@dkfz.de>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, Ilia Kats
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice, this
+           list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of the copyright holder nor the names of its
+           contributors may be used to endorse or promote products derived from
+           this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        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-Dist: session-info2
+Description-Content-Type: text/markdown
+
+# scverse-misc
+
+[![Tests][badge-tests]][tests]
+[![codecov][badge-codecov]][codecov]
+[![Documentation][badge-docs]][documentation]
+
+[badge-tests]: https://github.com/scverse/scverse-misc/actions/workflows/test.yaml/badge.svg
+[badge-codecov]: https://codecov.io/gh/scverse/scverse-misc/graph/badge.svg?token=EUH9BZZK7T
+[badge-docs]: https://img.shields.io/readthedocs/scverse-misc
+
+Miscellaneous utility code used by scverse packages
+
+## Getting started
+
+Please refer to the [documentation][],
+in particular, the [API documentation][].
+
+## Installation
+
+You need to have Python 3.11 or newer installed on your system.
+If you don't have Python installed, we recommend installing [uv][].
+
+There are several alternative options to install scverse-misc:
+
+<!--
+1) Install the latest release of `scverse-misc` from [PyPI][]:
+
+```bash
+pip install scverse-misc
+```
+-->
+
+1. Install the latest development version:
+
+```bash
+pip install git+https://github.com/scverse/scverse-misc.git@main
+```
+
+## Release notes
+
+See the [changelog][].
+
+## Contact
+
+For questions and help requests, you can reach out in the [scverse discourse][].
+If you found a bug, please use the [issue tracker][].
+
+
+[uv]: https://github.com/astral-sh/uv
+[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
+[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
+[pypi]: https://pypi.org/project/scverse-misc

scverse_misc-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+scverse_misc/__init__.py,sha256=xAuMYz1eRg2x5oruK1Jps-OwDUnoIapCGUWMQwaF_AQ,232
+scverse_misc/_extensions.py,sha256=Rjss5vJe9nmwwBZWtL56qsIQ1vjr6ZtxZXJbYoLfWx4,11294
+scverse_misc/_pandas_utils.py,sha256=rZ_POYn0bxb6FnIl418T1vzxEEFtarwt1TR5KEf94Sg,1359
+scverse_misc/_version.py,sha256=qf6R-J7-UyuABBo8c0HgaquJ8bejVbf07HodXgwAwgQ,704
+scverse_misc-0.0.1.dist-info/METADATA,sha256=NFbv_M2qoiMvoSYeirAxw4MYdl4pft1zDthJ19psRYk,4219
+scverse_misc-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+scverse_misc-0.0.1.dist-info/licenses/LICENSE,sha256=gjAb5KNAlstoHZ6PFN5lH7j_DUpda5-FfdwxlIqjDt0,1517
+scverse_misc-0.0.1.dist-info/RECORD,,

scverse_misc-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

scverse_misc-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Ilia Kats
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.