Add details to expectations for scalars

spec/API_specification/dataframe_api/__init__.py

@@ -4,12 +4,12 @@
 """
 from __future__ import annotations
 
-from typing import Dict, Sequence, Any, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any, Dict, Sequence
 
 from .column_object import *
 from .dataframe_object import DataFrame
-from .groupby_object import *
 from .dtypes import *
+from .groupby_object import *
 
 if TYPE_CHECKING:
     from .typing import DType, Scalar

spec/API_specification/dataframe_api/column_object.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
-from typing import Any,NoReturn, TYPE_CHECKING, Literal, Protocol
+from typing import TYPE_CHECKING, Any, Literal, NoReturn, Protocol
 
 if TYPE_CHECKING:
-    from .typing import NullType, Scalar, DType, Namespace
     from typing_extensions import Self
 
+    from .scalar_object import Scalar
+    from .typing import DType, Namespace, NullType
+
 
 __all__ = ['Column']
 

spec/API_specification/dataframe_api/dataframe_object.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
-from typing import Any, Literal, Mapping, Sequence, TYPE_CHECKING, NoReturn, Protocol
-
+from typing import TYPE_CHECKING, Any, Literal, Mapping, NoReturn, Protocol, Sequence
 
 if TYPE_CHECKING:
+    from typing_extensions import Self
+
     from .column_object import Column
     from .groupby_object import GroupBy
-    from .typing import NullType, Scalar, Namespace, DType, SupportsDataFrameAPI
-    from typing_extensions import Self
+    from .scalar_object import Scalar
+    from .typing import DType, Namespace, NullType, SupportsDataFrameAPI
 
 
 __all__ = ["DataFrame"]

spec/API_specification/dataframe_api/scalar_object.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+__all__ = ['Scalar']
+
+
+class Scalar(Protocol):
+    """
+    Scalar object
+
+    Not meant to be instantiated directly, but rather created via
+    `:meth:Column.get_value` or one of the column reductions such
+    as `:meth:`Column.sum`.
+    """
+    def __lt__(self, other: Any) -> Scalar:
+        ...
+
+    def __le__(self, other: Any) -> Scalar:
+        ...
+
+    def __eq__(self, other: Any) -> Scalar:  # type: ignore[override]
+        ...
+
+    def __ne__(self, other: Any) -> Scalar:  # type: ignore[override]
+        ...
+
+    def __gt__(self, other: Any) -> Scalar:
+        ...
+
+    def __ge__(self, other: Any) -> Scalar:
+        ...
+
+    def __add__(self, other: Any) -> Scalar:
+        ...
+
+    def __radd__(self, other: Any) -> Scalar:
+        ...
+
+    def __sub__(self, other: Any) -> Scalar:
+        ...
+
+    def __rsub__(self, other: Any) -> Scalar:
+        ...
+
+    def __mul__(self, other: Any) -> Scalar:
+        ...
+
+    def __rmul__(self, other: Any) -> Scalar:
+        ...
+
+    def __mod__(self, other: Any) -> Scalar:
+        ...
+
+    def __rmod__(self, other: Any) -> Scalar:
+        ...
+
+    def __pow__(self, other: Any) -> Scalar:
+        ...
+
+    def __rpow__(self, other: Any) -> Scalar:
+        ...
+
+    def __floordiv__(self, other: Any) -> Scalar:
+        ...
+
+    def __rfloordiv__(self, other: Any) -> Scalar:
+        ...
+
+    def __truediv__(self, other: Any) -> Scalar:
+        ...
+
+    def __rtruediv__(self, other: Any) -> Scalar:
+        ...
+
+    def __neg__(self) -> Scalar:
+        ...
+
+    def __abs__(self) -> Scalar:
+        ...
+
+    def __bool__(self) -> bool:
+        """
+        Note that this return a Python scalar.
+
+        Depending on the implementation, this may raise or trigger computation.
+        """
+        ...

spec/API_specification/dataframe_api/typing.py

@@ -3,38 +3,32 @@
 """
 from __future__ import annotations
 
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Literal,
-    Dict,
-    Protocol,
-    Sequence,
-    Union,
-)
+from typing import TYPE_CHECKING, Any, Dict, Literal, Protocol, Sequence, Union
 
 from dataframe_api.column_object import Column
 from dataframe_api.dataframe_object import DataFrame
-from dataframe_api.groupby_object import GroupBy, Aggregation as AggregationT
+from dataframe_api.groupby_object import Aggregation as AggregationT
+from dataframe_api.groupby_object import GroupBy
 
 if TYPE_CHECKING:
     from .dtypes import (
         Bool,
-        Float64,
-        Float32,
-        Int64,
-        Int32,
-        Int16,
-        Int8,
-        UInt64,
-        UInt32,
-        UInt16,
-        UInt8,
         Date,
         Datetime,
         Duration,
+        Float32,
+        Float64,
+        Int8,
+        Int16,
+        Int32,
+        Int64,
         String,
+        UInt8,
+        UInt16,
+        UInt32,
+        UInt64,
     )
+    from .scalar_object import Scalar
 
     DType = Union[
         Bool,
@@ -54,9 +48,6 @@
         Duration,
     ]
 
-# 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.)
-Scalar = Any
 # null is a special object which represents a missing value.
 # It is not valid as a type.
 NullType = Any