sort out null

Author: MarcoGorelli

spec/API_specification/dataframe_api/__init__.py

@@ -28,7 +28,7 @@
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
-    from .typing import DType, Scalar
+    from .typing import DType, NullType, Scalar
 
 __all__ = [
     "GroupBy",
@@ -197,8 +197,10 @@ def dataframe_from_2d_array(array: Any, *, schema: dict[str, DType]) -> DataFram
 class null:  # noqa: N801
     """A `null` object to represent missing data.
 
+    Not meant to be instantiated, use ``null`` directly.
+
     ``null`` is a scalar, and may be used when constructing a `Column` from a
-    Python sequence with `column_from_sequence`. It does not support ``is``,
+    Python sequence with :func:`column_from_sequence`. It does not support ``is``,
     ``==`` or ``bool``.
 
     Raises
@@ -221,7 +223,7 @@ class null:  # noqa: N801
     """
 
 
-def is_null(value: object, /) -> bool:
+def is_null(value: NullType, /) -> bool:
     """Check if an object is a `null` scalar.
 
     Parameters

spec/API_specification/dataframe_api/typing.py

@@ -58,7 +58,6 @@
 Scalar = Any
 # null is a special object which represents a missing value.
 # It is not valid as a type.
-NullType = Any
 
 
 class Namespace(Protocol):
@@ -100,6 +99,11 @@ class Bool:
     class Date:
         ...
 
+    class NullType:
+        ...
+
+    null: NullType
+
     class Datetime:
         def __init__(  # noqa: ANN204
             self,
@@ -145,7 +149,7 @@ def dataframe_from_2d_array(
     ) -> DataFrame:
         ...
 
-    def is_null(self, value: object, /) -> bool:
+    def is_null(self, value: NullType, /) -> bool:
         ...
 
     def is_dtype(self, dtype: DType, kind: str | tuple[str, ...]) -> bool:
@@ -155,6 +159,9 @@ def date(self, year: int, month: int, day: int) -> Scalar:
         ...
 
 
+NullType = Namespace.NullType
+
+
 class SupportsDataFrameAPI(Protocol):
     def __dataframe_consortium_standard__(
         self,

spec/API_specification/examples/03_working_with_nulls.py

@@ -0,0 +1,14 @@
+"""Fill a column's NaN values with the implemenation's null value."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dataframe_api.typing import SupportsDataFrameAPI
+
+
+def main(df_raw: SupportsDataFrameAPI) -> SupportsDataFrameAPI:
+    df = df_raw.__dataframe_consortium_standard__(api_version="2023-11.beta")
+    ns = df.__dataframe_namespace__()
+    df = df.fill_nan(ns.null)
+    return df.dataframe