Add some more dtypes: Date, Datetime, Duration, String (#197)

* add some more dtypes

* add Date

* remove notes on nbits

* remove Date, note lack of guarantees

* fixup

* put Date back

* fixup

* postmerge fixup

* add future annotations import

---------

Co-authored-by: Ralf Gommers <[email protected]>

Author: MarcoGorelli

spec/API_specification/dataframe_api/__init__.py

@@ -3,7 +3,7 @@
 """
 from __future__ import annotations
 
-from typing import Mapping, Sequence, Any, TYPE_CHECKING
+from typing import Mapping, Sequence, Any, Literal, TYPE_CHECKING
 
 from .column_object import *
 from .dataframe_object import DataFrame
@@ -35,6 +35,10 @@
     "Float64",
     "Float32",
     "Bool",
+    "Date",
+    "Datetime",
+    "Duration",
+    "String",
     "is_dtype",
 ]
 

spec/API_specification/dataframe_api/_types.py

@@ -33,6 +33,9 @@
         UInt32,
         UInt16,
         UInt8,
+        Date,
+        Datetime,
+        String,
     )
 
     DType = Union[Bool, Float64, Float32, Int64, Int32, Int16, Int8, UInt64, UInt32, UInt16, UInt8]
@@ -57,14 +60,16 @@ def Column() -> ColumnType:
         ...
 
     @staticmethod
-    def Int64() -> Int64:...
-    @staticmethod
-    def Int16() -> Int16:...
+    def Int64() -> Int64:
+        ...
 
     @staticmethod
     def Int32() -> Int32:
         ...
 
+    @staticmethod
+    def Int16() -> Int16:
+        ...
 
     @staticmethod
     def Int8() -> Int8:
@@ -98,6 +103,18 @@ def Float32() -> Float32:
     def Bool() -> Bool:
         ...
 
+    @staticmethod
+    def Date() -> Date:
+        ...
+
+    @staticmethod
+    def Datetime(time_unit: Literal['ms', 'us'], time_zone: str | None) -> Datetime:
+        ...
+
+    @staticmethod
+    def String() -> String:
+        ...
+
     @staticmethod
     def concat(dataframes: Sequence[DataFrameType]) -> DataFrameType:
         ...

spec/API_specification/dataframe_api/dtypes.py

@@ -1,3 +1,8 @@
+from __future__ import annotations
+
+from typing import Literal
+
+
 class Int64:
     """Integer type with 64 bits of precision."""
 
@@ -31,3 +36,35 @@ class Float32:
 class Bool:
     """Boolean type with 8 bits of precision."""
 
+class Date:
+    """
+    Date type.
+
+    There is no guarantee about the range of dates available.
+    """
+
+class Datetime:
+    """
+    Datetime type.
+
+    Attributes
+    ----------
+    time_unit : Literal['ms', 'us']
+        Precision of the datetime type. There is no guarantee that the full
+        range of dates available for the specified precision is supported.
+    time_zone : str | None
+        Time zone of the datetime type. Only IANA time zones are supported.
+        `None` indicates time-zone-naive data.
+    """
+    def __init__(self, *, time_unit: Literal['ms', 'us'], time_zone: str | None):
+        ...
+
+    time_unit: Literal['ms', 'us']
+    time_zone: str | None  # Only IANA time zones are supported
+
+class Duration:
+    """Duration type."""
+    time_unit: Literal['ms', 'us']
+
+class String:
+    """String type."""

spec/API_specification/index.rst

@@ -27,6 +27,10 @@ of objects and functions in the top-level namespace. The latter are:
    Float64
    Float32
    Bool
+   Date
+   Datetime
+   Duration
+   String
    is_dtype
    column_from_sequence
    column_from_1d_array