add Column.dtype (data-apis#166)

Author: MarcoGorelli

spec/API_specification/dataframe_api/__init__.py

@@ -9,7 +9,7 @@
 from .dataframe_object import *
 from .groupby_object import *
 
-from ._types import dtype
+from ._types import DType
 
 
 __dataframe_api_version__: str = "YYYY.MM"
@@ -38,7 +38,7 @@ def concat(dataframes: Sequence[DataFrame]) -> DataFrame:
     """
     ...
 
-def column_from_sequence(sequence: Sequence[object], *, dtype: dtype) -> Column:
+def column_from_sequence(sequence: Sequence[object], *, dtype: DType) -> Column:
     """
     Construct Column from sequence of elements.
 
@@ -48,7 +48,7 @@ def column_from_sequence(sequence: Sequence[object], *, dtype: dtype) -> Column:
         Sequence of elements. Each element must be of the specified
         ``dtype``, the corresponding Python builtin scalar type, or
         coercible to that Python scalar type.
-    dtype : str
+    dtype : DType
         Dtype of result. Must be specified.
 
     Returns

spec/API_specification/dataframe_api/_types.py

@@ -23,7 +23,7 @@
 array = TypeVar("array")
 Scalar = TypeVar("Scalar")
 device = TypeVar("device")
-dtype = TypeVar("dtype")
+DType = TypeVar("DType")
 SupportsDLPack = TypeVar("SupportsDLPack")
 SupportsBufferProtocol = TypeVar("SupportsBufferProtocol")
 PyCapsule = TypeVar("PyCapsule")
@@ -57,7 +57,7 @@ def __len__(self, /) -> int:
     "Sequence",
     "array",
     "device",
-    "dtype",
+    "DType",
     "ellipsis",
     "Enum",
 ]

spec/API_specification/dataframe_api/column_object.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from typing import NoReturn, Sequence
+from typing import NoReturn, Sequence, TYPE_CHECKING
 
-from ._types import Scalar, dtype
+if TYPE_CHECKING:
+    from ._types import Scalar, DType
 
 
 __all__ = ['Column']
@@ -34,6 +35,12 @@ def __iter__(self) -> NoReturn:
         """
         raise NotImplementedError("'__iter__' is intentionally not implemented.")
 
+    @property
+    def dtype(self) -> DType:
+        """
+        Return data type of column.
+        """
+
     def get_rows(self, indices: Column[int]) -> Column:
         """
         Select a subset of rows, similar to `ndarray.take`.
@@ -45,7 +52,7 @@ def get_rows(self, indices: Column[int]) -> Column:
         """
         ...
 
-    def get_value(self, row_number: int) -> dtype:
+    def get_value(self, row_number: int) -> DType:
         """
         Select the value at a row number, similar to `ndarray.__getitem__(<int>)`.
 
@@ -316,56 +323,56 @@ def all(self, *, skip_nulls: bool = True) -> bool:
             If column is not boolean.
         """
 
-    def min(self, *, skip_nulls: bool = True) -> dtype:
+    def min(self, *, skip_nulls: bool = True) -> DType:
         """
         Reduction returns a scalar. Any data type that supports comparisons
         must be supported. The returned value has the same dtype as the column.
         """
 
-    def max(self, *, skip_nulls: bool = True) -> dtype:
+    def max(self, *, skip_nulls: bool = True) -> DType:
         """
         Reduction returns a scalar. Any data type that supports comparisons
         must be supported. The returned value has the same dtype as the column.
         """
 
-    def sum(self, *, skip_nulls: bool = True) -> dtype:
+    def sum(self, *, skip_nulls: bool = True) -> DType:
         """
         Reduction returns a scalar. Must be supported for numerical and
         datetime data types. The returned value has the same dtype as the
         column.
         """
 
-    def prod(self, *, skip_nulls: bool = True) -> dtype:
+    def prod(self, *, skip_nulls: bool = True) -> DType:
         """
         Reduction returns a scalar. Must be supported for numerical data types.
         The returned value has the same dtype as the column.
         """
 
-    def median(self, *, skip_nulls: bool = True) -> dtype:
+    def median(self, *, skip_nulls: bool = True) -> DType:
         """
         Reduction returns a scalar. Must be supported for numerical and
         datetime data types. Returns a float for numerical data types, and
         datetime (with the appropriate timedelta format string) for datetime
         dtypes.
         """
 
-    def mean(self, *, skip_nulls: bool = True) -> dtype:
+    def mean(self, *, skip_nulls: bool = True) -> DType:
         """
         Reduction returns a scalar. Must be supported for numerical and
         datetime data types. Returns a float for numerical data types, and
         datetime (with the appropriate timedelta format string) for datetime
         dtypes.
         """
 
-    def std(self, *, skip_nulls: bool = True) -> dtype:
+    def std(self, *, skip_nulls: bool = True) -> DType:
         """
         Reduction returns a scalar. Must be supported for numerical and
         datetime data types. Returns a float for numerical data types, and
         datetime (with the appropriate timedelta format string) for datetime
         dtypes.
         """
 
-    def var(self, *, skip_nulls: bool = True) -> dtype:
+    def var(self, *, skip_nulls: bool = True) -> DType:
         """
         Reduction returns a scalar. Must be supported for numerical and
         datetime data types. Returns a float for numerical data types, and

spec/conf.py

@@ -75,7 +75,7 @@
     ('py:class', 'array'),
     ('py:class', 'DataFrame'),
     ('py:class', 'device'),
-    ('py:class', 'dtype'),
+    ('py:class', 'DType'),
     ('py:class', 'NestedSequence'),
     ('py:class', 'collections.abc.Sequence'),
     ('py:class', 'PyCapsule'),