feat(DRAFT): Add get_supertype

.gitignore

@@ -20,6 +20,7 @@ site/
 todo.md
 docs/this.md
 docs/api-completeness/*.md
+docs/concepts/promotion-rules.md
 !docs/api-completeness/index.md
 
 # Lock files

mkdocs.yml

@@ -19,6 +19,7 @@ nav:
     - concepts/column_names.md
     - concepts/boolean.md
     - concepts/null_handling.md
+    - concepts/promotion-rules.md
   - Overhead: overhead.md
   - Perfect backwards compatibility policy: backcompat.md
   - Extensions and Plugins: extending.md
@@ -81,8 +82,9 @@ theme:
   favicon: assets/logo.svg
   logo: assets/logo.svg
   features:
-    - content.code.copy
     - content.code.annotate
+    - content.code.copy
+    - content.footnote.tooltips
     - navigation.footer
     - navigation.indexes
     - navigation.top
@@ -126,13 +128,14 @@ plugins:
 
 hooks:
 - utils/generate_backend_completeness.py
+- utils/generate_supertyping.py
 - utils/generate_zen_content.py
 
-
 markdown_extensions:
 - admonition
 - md_in_html
 - pymdownx.details
+- footnotes
 - pymdownx.tabbed:
     alternate_style: true
 - pymdownx.superfences:

narwhals/_dispatch.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import partial
+from typing import TYPE_CHECKING, Any, Generic, Protocol, TypeVar, overload
+
+if TYPE_CHECKING:
+
+    class Deferred(Protocol):
+        def __call__(self, f: Callable[..., R], /) -> JustDispatch[R]: ...
+
+
+__all__ = ["just_dispatch"]
+
+R = TypeVar("R")
+R_co = TypeVar("R_co", covariant=True)
+PassthroughFn = TypeVar("PassthroughFn", bound=Callable[..., Any])
+"""Original function is passed-through unchanged."""
+
+
+class JustDispatch(Generic[R_co]):
+    """Single-dispatch wrapper produced by decorating a function with `@just_dispatch`."""
+
+    __slots__ = ("_registry", "_upper_bound")
+
+    def __init__(self, function: Callable[..., R_co], /, upper_bound: type[Any]) -> None:
+        self._upper_bound: type[Any] = upper_bound
+        self._registry: dict[type[Any], Callable[..., R_co]] = {upper_bound: function}
+
+    def dispatch(self, tp: type[Any], /) -> Callable[..., R_co]:
+        """Get the implementation for a given type."""
+        if f := self._registry.get(tp):
+            return f
+        if issubclass(tp, self._upper_bound):
+            f = self._registry[tp] = self._registry[self._upper_bound]
+            return f
+        msg = f"{self._registry[self._upper_bound].__name__!r} does not support {tp.__name__!r}"
+        raise TypeError(msg)
+
+    def register(
+        self, tp: type[Any], *tps: type[Any]
+    ) -> Callable[[PassthroughFn], PassthroughFn]:
+        """Register types to dispatch via the decorated function."""
+
+        def decorate(f: PassthroughFn, /) -> PassthroughFn:
+            self._registry.update((tp_, f) for tp_ in (tp, *tps))
+            return f
+
+        return decorate
+
+    def __call__(self, arg: object, *args: Any, **kwds: Any) -> R_co:
+        """Dispatch on the type of the first argument, passing through all arguments."""
+        return self.dispatch(arg.__class__)(arg, *args, **kwds)
+
+
+@overload
+def just_dispatch(function: Callable[..., R], /) -> JustDispatch[R]: ...
+@overload
+def just_dispatch(*, upper_bound: type[Any] = object) -> Deferred: ...
+def just_dispatch(
+    function: Callable[..., R] | None = None, /, *, upper_bound: type[Any] = object
+) -> JustDispatch[R] | Deferred:
+    """Transform a function into a single-dispatch generic function.
+
+    An alternative take on [`@functools.singledispatch`]:
+    - without [MRO] fallback
+    - allows [*just*] the types registered and optionally an `upper_bound`
+
+    Arguments:
+        function: Function to decorate, where the body serves as the default implementation.
+        upper_bound: When there is no registered implementation for a specific type, it must
+            be a subclass of `upper_bound` to use the default implementation.
+
+    Tip:
+        `@just_dispatch` should only be used to decorate **internal functions** as we lose the docstring.
+
+    [`@functools.singledispatch`]: https://docs.python.org/3/library/functools.html#functools.singledispatch
+    [MRO]: https://docs.python.org/3/howto/mro.html#python-2-3-mro
+    [*just*]: https://github.com/jorenham/optype/blob/e7221ed1d3d02989d5d01873323bac9f88459f26/README.md#just
+    """
+    if function is not None:
+        return JustDispatch(function, upper_bound)
+    return partial(JustDispatch[Any], upper_bound=upper_bound)

narwhals/dtypes/__init__.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from narwhals.dtypes._classes import (
+    Array,
+    Binary,
+    Boolean,
+    Categorical,
+    Date,
+    Datetime,
+    Decimal,
+    DType,
+    Duration,
+    Enum,
+    Field,
+    Float32,
+    Float64,
+    FloatType,
+    Int8,
+    Int16,
+    Int32,
+    Int64,
+    Int128,
+    IntegerType,
+    List,
+    NestedType,
+    NumericType,
+    Object,
+    SignedIntegerType,
+    String,
+    Struct,
+    TemporalType,
+    Time,
+    UInt8,
+    UInt16,
+    UInt32,
+    UInt64,
+    UInt128,
+    Unknown,
+    UnsignedIntegerType,
+)
+
+__all__ = [
+    "Array",
+    "Binary",
+    "Boolean",
+    "Categorical",
+    "DType",
+    "Date",
+    "Datetime",
+    "Decimal",
+    "Duration",
+    "Enum",
+    "Field",
+    "Float32",
+    "Float64",
+    "FloatType",
+    "Int8",
+    "Int16",
+    "Int32",
+    "Int64",
+    "Int128",
+    "IntegerType",
+    "List",
+    "NestedType",
+    "NumericType",
+    "Object",
+    "SignedIntegerType",
+    "String",
+    "Struct",
+    "TemporalType",
+    "Time",
+    "UInt8",
+    "UInt16",
+    "UInt32",
+    "UInt64",
+    "UInt128",
+    "Unknown",
+    "UnsignedIntegerType",
+]

narwhals/dtypes.py → narwhals/dtypes/_classes.py

@@ -2,61 +2,24 @@
 
 import enum
 from collections import OrderedDict
-from collections.abc import Iterable, Mapping
+from collections.abc import Mapping
 from datetime import timezone
 from itertools import starmap
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, ClassVar
 
-from narwhals._utils import (
-    _DeferredIterable,
-    isinstance_or_issubclass,
-    qualified_type_name,
-)
+from narwhals._utils import _DeferredIterable, isinstance_or_issubclass
 from narwhals.exceptions import InvalidOperationError
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator, Sequence
-    from typing import Any
+    from collections.abc import Iterable, Iterator, Sequence
+    from typing import Any, Literal
 
     import _typeshed
-    from typing_extensions import Self, TypeIs
+    from typing_extensions import Self, TypeAlias
 
     from narwhals.typing import IntoDType, TimeUnit
 
-
-def _validate_dtype(dtype: DType | type[DType]) -> None:
-    if not isinstance_or_issubclass(dtype, DType):
-        msg = (
-            f"Expected Narwhals dtype, got: {type(dtype)}.\n\n"
-            "Hint: if you were trying to cast to a type, use e.g. nw.Int64 instead of 'int64'."
-        )
-        raise TypeError(msg)
-
-
-def _is_into_dtype(obj: Any) -> TypeIs[IntoDType]:
-    return isinstance(obj, DType) or (
-        isinstance(obj, DTypeClass) and not issubclass(obj, NestedType)
-    )
-
-
-def _is_nested_type(obj: Any) -> TypeIs[type[NestedType]]:
-    return isinstance(obj, DTypeClass) and issubclass(obj, NestedType)
-
-
-def _validate_into_dtype(dtype: Any) -> None:
-    if not _is_into_dtype(dtype):
-        if _is_nested_type(dtype):
-            name = f"nw.{dtype.__name__}"
-            msg = (
-                f"{name!r} is not valid in this context.\n\n"
-                f"Hint: instead of:\n\n"
-                f"    {name}\n\n"
-                "use:\n\n"
-                f"    {name}(...)"
-            )
-        else:
-            msg = f"Expected Narwhals dtype, got: {qualified_type_name(dtype)!r}."
-        raise TypeError(msg)
+    _Bits: TypeAlias = Literal[8, 16, 32, 64, 128]
 
 
 class DTypeClass(type):
@@ -176,6 +139,9 @@ def __eq__(self, other: DType | type[DType]) -> bool:  # type: ignore[override]
     def __hash__(self) -> int:
         return hash(self.__class__)
 
+    def __call__(self) -> Self:
+        return self
+
 
 class NumericType(DType):
     """Base class for numeric data types."""
@@ -184,12 +150,19 @@ class NumericType(DType):
 class IntegerType(NumericType):
     """Base class for integer data types."""
 
+    # NOTE: Likely going to need an `Integer` metaclass, to be able to use `Final` or a class property
+    _bits: ClassVar[_Bits]
+
+    def __init_subclass__(cls, *args: Any, bits: _Bits, **kwds: Any) -> None:
+        super().__init_subclass__(*args, **kwds)
+        cls._bits = bits
+
 
-class SignedIntegerType(IntegerType):
+class SignedIntegerType(IntegerType, bits=128):
     """Base class for signed integer data types."""
 
 
-class UnsignedIntegerType(IntegerType):
+class UnsignedIntegerType(IntegerType, bits=128):
     """Base class for unsigned integer data types."""
 
 
@@ -261,7 +234,7 @@ def __repr__(self) -> str:  # pragma: no cover
         return f"{class_name}(precision={self.precision!r}, scale={self.scale!r})"
 
 
-class Int128(SignedIntegerType):
+class Int128(SignedIntegerType, bits=128):
     """128-bit signed integer type.
 
     Examples:
@@ -281,7 +254,7 @@ class Int128(SignedIntegerType):
     """
 
 
-class Int64(SignedIntegerType):
+class Int64(SignedIntegerType, bits=64):
     """64-bit signed integer type.
 
     Examples:
@@ -294,7 +267,7 @@ class Int64(SignedIntegerType):
     """
 
 
-class Int32(SignedIntegerType):
+class Int32(SignedIntegerType, bits=32):
     """32-bit signed integer type.
 
     Examples:
@@ -307,7 +280,7 @@ class Int32(SignedIntegerType):
     """
 
 
-class Int16(SignedIntegerType):
+class Int16(SignedIntegerType, bits=16):
     """16-bit signed integer type.
 
     Examples:
@@ -320,7 +293,7 @@ class Int16(SignedIntegerType):
     """
 
 
-class Int8(SignedIntegerType):
+class Int8(SignedIntegerType, bits=8):
     """8-bit signed integer type.
 
     Examples:
@@ -333,7 +306,7 @@ class Int8(SignedIntegerType):
     """
 
 
-class UInt128(UnsignedIntegerType):
+class UInt128(UnsignedIntegerType, bits=128):
     """128-bit unsigned integer type.
 
     Examples:
@@ -347,7 +320,7 @@ class UInt128(UnsignedIntegerType):
     """
 
 
-class UInt64(UnsignedIntegerType):
+class UInt64(UnsignedIntegerType, bits=64):
     """64-bit unsigned integer type.
 
     Examples:
@@ -360,7 +333,7 @@ class UInt64(UnsignedIntegerType):
     """
 
 
-class UInt32(UnsignedIntegerType):
+class UInt32(UnsignedIntegerType, bits=32):
     """32-bit unsigned integer type.
 
     Examples:
@@ -373,7 +346,7 @@ class UInt32(UnsignedIntegerType):
     """
 
 
-class UInt16(UnsignedIntegerType):
+class UInt16(UnsignedIntegerType, bits=16):
     """16-bit unsigned integer type.
 
     Examples:
@@ -386,7 +359,7 @@ class UInt16(UnsignedIntegerType):
     """
 
 
-class UInt8(UnsignedIntegerType):
+class UInt8(UnsignedIntegerType, bits=8):
     """8-bit unsigned integer type.
 
     Examples: