Add null object, and update top-level API specification

Author: rgommers

spec/API_specification/dataframe_api/__init__.py

@@ -14,8 +14,9 @@
 
 __dataframe_api_version__: str = "YYYY.MM"
 """
-String representing the version of the DataFrame API specification to which the
-conforming implementation adheres.
+String representing the version of the DataFrame API specification to which
+the conforming implementation adheres. Set to a concrete value for a stable
+implementation of the dataframe API standard.
 """
 
 def concat(dataframes: Sequence[DataFrame]) -> DataFrame:
@@ -73,3 +74,36 @@ def dataframe_from_dict(data: Mapping[str, Column]) -> DataFrame:
     DataFrame
     """
     ...
+
+class null:
+    """
+    A `null` singleton object to represent missing data.
+
+    ``null`` may be used when constructing a `Column` from a Python sequence.
+    It supports ``is``, and does not support ``==`` and ``bool``.
+
+    Methods
+    -------
+    __bool__
+    __eq__
+
+    """
+    def __eq__(self):
+        """
+        Raises
+        ------
+        RuntimeError
+            A missing value must not be compared for equality. Use ``is`` to check
+            if an object *is* this ``null`` object, and `DataFrame.isnull` or
+            `Column.isnull` to check for presence of missing values.
+        """
+        ...
+
+    def __bool__(self):
+        """
+        Raises
+        ------
+        TypeError
+            Truthiness of a missing value is ambiguous
+        """
+        ...

spec/API_specification/index.rst

@@ -5,6 +5,20 @@ API specification
 
 .. currentmodule:: dataframe_api
 
+The API consists of dataframe, column and groupby classes, plus a small number
+of objects and functions in the top-level namespace. The latter are:
+
+.. autosummary::
+   :toctree: generated
+   :template: attribute.rst
+   :nosignatures:
+
+   __dataframe_api_version__
+   null
+
+The ``DataFrame``, ``Column`` and ``GroupBy`` objects have the following
+methods and attributes:
+
 .. toctree::
    :maxdepth: 3