add namespace protocol

Author: MarcoGorelli

spec/API_specification/dataframe_api/_types.py

@@ -6,19 +6,22 @@
 """
 from __future__ import annotations
 
-from dataclasses import dataclass
 from typing import (
+    TYPE_CHECKING,
     Any,
     List,
     Literal,
+    Mapping,
     Optional,
+    Protocol,
     Sequence,
     Tuple,
     TypeVar,
     Union,
-    Protocol,
 )
-from enum import Enum
+
+if TYPE_CHECKING:
+    from .dataframe_object import DataFrame
 
 # Type alias: Mypy needs Any, but for readability we need to make clear this
 # is a Python scalar (i.e., an instance of `bool`, `int`, `float`, `str`, etc.)
@@ -48,6 +51,100 @@ def __len__(self, /) -> int:
         ...
 
 
+class Namespace(Protocol):
+    __dataframe_api_version__: str
+
+    class DataFrame:
+        ...
+
+    class Column:
+        ...
+
+    class Int64:
+        ...
+
+    class Int32:
+        ...
+
+    class Int16:
+        ...
+
+    class Int8:
+        ...
+
+    class UInt64:
+        ...
+
+    class UInt32:
+        ...
+
+    class UInt16:
+        ...
+
+    class UInt8:
+        ...
+
+    class Float64:
+        ...
+
+    class Float32:
+        ...
+
+    class Bool:
+        ...
+
+    @staticmethod
+    def concat(dataframes: Sequence[DataFrame]) -> DataFrame:
+        ...
+
+    @staticmethod
+    def column_from_sequence(
+        sequence: Sequence[Any],
+        *,
+        dtype: Any,
+        name: str = "",
+        api_version: str | None = None,
+    ) -> Column:
+        ...
+
+    @staticmethod
+    def dataframe_from_dict(
+        data: Mapping[str, Column], *, api_version: str | None = None
+    ) -> DataFrame:
+        ...
+
+    @staticmethod
+    def column_from_1d_array(
+        array: Any, *, dtype: Any, name: str = "", api_version: str | None = None
+    ) -> Column:
+        ...
+
+    @staticmethod
+    def dataframe_from_2d_array(
+        array: Any,
+        *,
+        names: Sequence[str],
+        dtypes: Mapping[str, Any],
+        api_version: str | None = None,
+    ) -> DataFrame:
+        ...
+
+    @staticmethod
+    def is_null(value: object, /) -> bool:
+        ...
+
+    @staticmethod
+    def is_dtype(dtype: Any, kind: str | tuple[str, ...]) -> bool:
+        ...
+
+
+class SupportsDataFrameAPI(Protocol):
+    def __dataframe_consortium_standard__(
+        self, *, api_version: str | None = None
+    ) -> DataFrame:
+        ...
+
+
 __all__ = [
     "Any",
     "DataFrame",
@@ -65,5 +162,4 @@ def __len__(self, /) -> int:
     "device",
     "DType",
     "ellipsis",
-    "Enum",
 ]

spec/API_specification/dataframe_api/dataframe_object.py

@@ -7,7 +7,7 @@
     from .column_object import Column
     from .groupby_object import GroupBy
     from . import Bool
-    from ._types import NullType, Scalar
+    from ._types import NullType, Scalar, Namespace
 
 
 __all__ = ["DataFrame"]
@@ -37,7 +37,7 @@ class DataFrame:
     **Methods and Attributes**
 
     """
-    def __dataframe_namespace__(self) -> Any:
+    def __dataframe_namespace__(self) -> Namespace:
         """
         Returns an object that has all the top-level dataframe API functions on it.