sort out null (#320)

spec/API_specification/dataframe_api/__init__.py

@@ -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

spec/API_specification/dataframe_api/typing.py

@@ -23,7 +23,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):
@@ -65,6 +64,11 @@ class Bool:
     class Date:
         ...
 
+    class NullType:
+        ...
+
+    null: NullType
+
     class Datetime:
         def __init__(  # noqa: ANN204
             self,
@@ -127,6 +131,7 @@ def date(self, year: int, month: int, day: int) -> Scalar:
         ...
 
 
+NullType = Namespace.NullType
 DType = Union[
     Namespace.Bool,
     Namespace.Float64,

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")
+    namespace = df.__dataframe_namespace__()
+    df = df.fill_nan(namespace.null)
+    return df.dataframe