feat(DRAFT): Add get_supertype

docs/concepts/promotion-rules.md

@@ -0,0 +1,29 @@
+|             | Array   | Binary  | Boolean | Categorical | Date     | Datetime | Decimal | Duration | Enum    | Float32 | Float64 | Int128  | Int16   | Int32   | Int64   | Int8    | List    | Object  | String  | Struct  | Time    | UInt128 | UInt16  | UInt32  | UInt64  | UInt8   | Unknown |
+|-------------|---------|---------|---------|-------------|----------|----------|---------|----------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|
+| Array       | Array   |         |         |             |          |          |         |          |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         | Unknown |
+| Binary      |         | Binary  |         |             |          |          |         |          |         |         |         |         |         |         |         |         |         |         | Binary  |         |         |         |         |         |         |         | Unknown |
+| Boolean     |         |         | Boolean |             |          |          | Decimal |          |         | Float32 | Float64 | Int128  | Int16   | Int32   | Int64   | Int8    |         |         |         |         |         | UInt128 | UInt16  | UInt32  | UInt64  | UInt8   | Unknown |
+| Categorical |         |         |         | Categorical |          |          |         |          |         |         |         |         |         |         |         |         |         |         | String  |         |         |         |         |         |         |         | Unknown |
+| Date        |         |         |         |             | Date     | Datetime |         |          |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         | Unknown |
+| Datetime    |         |         |         |             | Datetime | Datetime |         |          |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         | Unknown |
+| Decimal     |         |         | Decimal |             |          |          | Decimal |          |         | Float64 | Float64 | Decimal | Decimal | Decimal | Decimal | Decimal |         |         |         |         |         | Decimal | Decimal | Decimal | Decimal | Decimal | Unknown |
+| Duration    |         |         |         |             |          |          |         | Duration |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         |         | Unknown |
+| Enum        |         |         |         |             |          |          |         |          | Enum    |         |         |         |         |         |         |         |         |         | String  |         |         |         |         |         |         |         | Unknown |
+| Float32     |         |         | Float32 |             |          |          | Float64 |          |         | Float32 | Float64 | Float64 | Float32 | Float64 | Float64 | Float32 |         |         |         |         |         | Float64 | Float32 | Float64 | Float64 | Float32 | Unknown |
+| Float64     |         |         | Float64 |             |          |          | Float64 |          |         | Float64 | Float64 | Float64 | Float64 | Float64 | Float64 | Float64 |         |         |         |         |         | Float64 | Float64 | Float64 | Float64 | Float64 | Unknown |
+| Int128      |         |         | Int128  |             |          |          | Decimal |          |         | Float64 | Float64 | Int128  | Int128  | Int128  | Int128  | Int128  |         |         |         |         |         | Float64 | Int128  | Int128  | Int128  | Int128  | Unknown |
+| Int16       |         |         | Int16   |             |          |          | Decimal |          |         | Float32 | Float64 | Int128  | Int16   | Int32   | Int64   | Int16   |         |         |         |         |         | Float64 | Int32   | Int64   | Float64 | Int16   | Unknown |
+| Int32       |         |         | Int32   |             |          |          | Decimal |          |         | Float64 | Float64 | Int128  | Int32   | Int32   | Int64   | Int32   |         |         |         |         |         | Float64 | Int32   | Int64   | Float64 | Int32   | Unknown |
+| Int64       |         |         | Int64   |             |          |          | Decimal |          |         | Float64 | Float64 | Int128  | Int64   | Int64   | Int64   | Int64   |         |         |         |         |         | Float64 | Int64   | Int64   | Float64 | Int64   | Unknown |
+| Int8        |         |         | Int8    |             |          |          | Decimal |          |         | Float32 | Float64 | Int128  | Int16   | Int32   | Int64   | Int8    |         |         |         |         |         | Float64 | Int32   | Int64   | Float64 | Int16   | Unknown |
+| List        |         |         |         |             |          |          |         |          |         |         |         |         |         |         |         |         | List    |         |         |         |         |         |         |         |         |         | Unknown |
+| Object      |         |         |         |             |          |          |         |          |         |         |         |         |         |         |         |         |         | Object  |         |         |         |         |         |         |         |         | Unknown |
+| String      |         | Binary  |         | String      |          |          |         |          | String  |         |         |         |         |         |         |         |         |         | String  |         |         |         |         |         |         |         | Unknown |
+| Struct      |         |         |         |             |          |          |         |          |         |         |         |         |         |         |         |         |         |         |         | Struct  |         |         |         |         |         |         | Unknown |
+| Time        |         |         |         |             |          |          |         |          |         |         |         |         |         |         |         |         |         |         |         |         | Time    |         |         |         |         |         | Unknown |
+| UInt128     |         |         | UInt128 |             |          |          | Decimal |          |         | Float64 | Float64 | Float64 | Float64 | Float64 | Float64 | Float64 |         |         |         |         |         | UInt128 | UInt128 | UInt128 | UInt128 | UInt128 | Unknown |
+| UInt16      |         |         | UInt16  |             |          |          | Decimal |          |         | Float32 | Float64 | Int128  | Int32   | Int32   | Int64   | Int32   |         |         |         |         |         | UInt128 | UInt16  | UInt32  | UInt64  | UInt16  | Unknown |
+| UInt32      |         |         | UInt32  |             |          |          | Decimal |          |         | Float64 | Float64 | Int128  | Int64   | Int64   | Int64   | Int64   |         |         |         |         |         | UInt128 | UInt32  | UInt32  | UInt64  | UInt32  | Unknown |
+| UInt64      |         |         | UInt64  |             |          |          | Decimal |          |         | Float64 | Float64 | Int128  | Float64 | Float64 | Float64 | Float64 |         |         |         |         |         | UInt128 | UInt64  | UInt64  | UInt64  | UInt64  | Unknown |
+| UInt8       |         |         | UInt8   |             |          |          | Decimal |          |         | Float32 | Float64 | Int128  | Int16   | Int32   | Int64   | Int16   |         |         |         |         |         | UInt128 | UInt16  | UInt32  | UInt64  | UInt8   | Unknown |
+| Unknown     | Unknown | Unknown | Unknown | Unknown     | Unknown  | Unknown  | Unknown | Unknown  | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown | Unknown |

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,60 +2,23 @@
 
 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
 
 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):
@@ -175,6 +138,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."""
@@ -183,12 +149,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."""
 
 
@@ -216,7 +189,7 @@ class Decimal(NumericType):
     """
 
 
-class Int128(SignedIntegerType):
+class Int128(SignedIntegerType, bits=128):
     """128-bit signed integer type.
 
     Examples:
@@ -236,7 +209,7 @@ class Int128(SignedIntegerType):
     """
 
 
-class Int64(SignedIntegerType):
+class Int64(SignedIntegerType, bits=64):
     """64-bit signed integer type.
 
     Examples:
@@ -249,7 +222,7 @@ class Int64(SignedIntegerType):
     """
 
 
-class Int32(SignedIntegerType):
+class Int32(SignedIntegerType, bits=32):
     """32-bit signed integer type.
 
     Examples:
@@ -262,7 +235,7 @@ class Int32(SignedIntegerType):
     """
 
 
-class Int16(SignedIntegerType):
+class Int16(SignedIntegerType, bits=16):
     """16-bit signed integer type.
 
     Examples:
@@ -275,7 +248,7 @@ class Int16(SignedIntegerType):
     """
 
 
-class Int8(SignedIntegerType):
+class Int8(SignedIntegerType, bits=8):
     """8-bit signed integer type.
 
     Examples:
@@ -288,7 +261,7 @@ class Int8(SignedIntegerType):
     """
 
 
-class UInt128(UnsignedIntegerType):
+class UInt128(UnsignedIntegerType, bits=128):
     """128-bit unsigned integer type.
 
     Examples:
@@ -302,7 +275,7 @@ class UInt128(UnsignedIntegerType):
     """
 
 
-class UInt64(UnsignedIntegerType):
+class UInt64(UnsignedIntegerType, bits=64):
     """64-bit unsigned integer type.
 
     Examples:
@@ -315,7 +288,7 @@ class UInt64(UnsignedIntegerType):
     """
 
 
-class UInt32(UnsignedIntegerType):
+class UInt32(UnsignedIntegerType, bits=32):
     """32-bit unsigned integer type.
 
     Examples:
@@ -328,7 +301,7 @@ class UInt32(UnsignedIntegerType):
     """
 
 
-class UInt16(UnsignedIntegerType):
+class UInt16(UnsignedIntegerType, bits=16):
     """16-bit unsigned integer type.
 
     Examples:
@@ -341,7 +314,7 @@ class UInt16(UnsignedIntegerType):
     """
 
 
-class UInt8(UnsignedIntegerType):
+class UInt8(UnsignedIntegerType, bits=8):
     """8-bit unsigned integer type.
 
     Examples:

narwhals/stable/v1/_dtypes.py → narwhals/dtypes/_classes_v1.py

@@ -12,7 +12,6 @@
     Datetime as NwDatetime,
     Decimal,
     DType,
-    DTypeClass,
     Duration as NwDuration,
     Enum as NwEnum,
     Field,
@@ -41,6 +40,7 @@
     Unknown,
     UnsignedIntegerType,
 )
+from narwhals.dtypes._classes import DTypeClass
 
 if TYPE_CHECKING:
     from datetime import timezone