Merge remote-tracking branch 'upstream/main' into column-getitem-and-len

Author: MarcoGorelli

requirements.txt

@@ -1,7 +1,7 @@
-sphinx==4.3.0
-sphinx-material==0.0.30
+sphinx==6.2.1
+sphinx-material==0.0.35
 myst-parser
 sphinx_markdown_tables
 sphinx_copybutton
-docutils<0.18
+docutils==0.19
 sphinx-math-dollar

spec/API_specification/column_object.rst

@@ -4,20 +4,9 @@ Column object
 =============
 
 A conforming implementation of the dataframe API standard must provide and
-support a column object having the following attributes and methods.
+support a column object having the following methods, attributes, and
+behavior.
 
--------------------------------------------------
-
-Methods
--------
-TODO
-
-..
-  NOTE: please keep the methods in alphabetical order
-
-    .. currentmodule:: dataframe_api
-
-    .. autosummary::
-       :toctree: generated
-   :template: property.rst
+.. currentmodule:: dataframe_api
 
+.. autoclass:: Column

spec/API_specification/dataframe_api/column_object.py

@@ -1,13 +1,47 @@
 from __future__ import annotations
 
-from typing import NoReturn
+from typing import NoReturn, Sequence
+
+from ._types import dtype
+
+
+__all__ = ['Column']
+
 
 class Column:
+    """
+    Column object
+
+    Note that this column object is not meant to be instantiated directly by
+    users of the library implementing the dataframe API standard. Rather, use
+    constructor functions or an already-created dataframe object retrieved via
+
+    """
+    @classmethod
+    def from_sequence(cls, sequence: Sequence[object], dtype: dtype) -> Column:
+        """
+        Construct Column from sequence of elements.
+
+        Parameters
+        ----------
+        sequence : Sequence[object]
+            Sequence of elements. Each element must be of the specified
+            ``dtype``, the corresponding Python builtin scalar type, or
+            coercible to that Python scalar type.
+        dtype : str
+            Dtype of result. Must be specified.
+        
+        Returns
+        -------
+        Column
+        """
+        ...
+
     def __len__(self) -> int:
         """
         Return the number of rows.
         """
-    
+
     def __getitem__(self, row: int) -> object:
         """
         Get the element at row index `key`.
@@ -33,9 +67,5 @@ def get_rows(self, indices: Column[int]) -> Column:
         ----------
         indices : Column[int]
             Positions of rows to select.
-
-        Returns
-        -------
-        Column
         """
-        ...
+        ...

spec/API_specification/dataframe_api/dataframe_object.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
-from typing import Sequence, Union, TYPE_CHECKING, NoReturn
+
+from typing import Literal, Mapping, Sequence, Union, TYPE_CHECKING, NoReturn
+
 
 if TYPE_CHECKING:
     from .column_object import Column
@@ -11,6 +13,47 @@
 
 
 class DataFrame:
+    """
+    DataFrame object
+
+    Note that this dataframe object is not meant to be instantiated directly by
+    users of the library implementing the dataframe API standard. Rather, use
+    constructor functions or an already-created dataframe object retrieved via
+    
+    **Python operator support**
+
+    All arithmetic operators defined by the Python language, except for
+    ``__matmul__``, ``__neg__`` and ``__pos__``, must be supported for
+    numerical data types.
+
+    All comparison operators defined by the Python language must be supported
+    by the dataframe object for all data types for which those comparisons are
+    supported by the builtin scalar types corresponding to a data type.
+
+    In-place operators must not be supported. All operations on the dataframe
+    object are out-of-place.
+
+    **Methods and Attributes**
+
+    """
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Column]) -> DataFrame:
+        """
+        Construct DataFrame from map of column names to Columns.
+
+        Parameters
+        ----------
+        data : Mapping[str, Column]
+            Column must be of the corresponding type of the DataFrame.
+            For example, it is only supported to build a ``LibraryXDataFrame`` using
+            ``LibraryXColumn`` instances.
+
+        Returns
+        -------
+        DataFrame
+        """
+
     @property
     def dataframe(self) -> object:
         """
@@ -88,24 +131,18 @@ def get_columns_by_name(self, names: Sequence[str], /) -> DataFrame:
         """
         ...
 
-    def get_rows(self, indices: Sequence[int]) -> DataFrame:
+    def get_rows(self, indices: "Column[int]") -> DataFrame:
         """
         Select a subset of rows, similar to `ndarray.take`.
 
         Parameters
         ----------
-        indices : Sequence[int]
+        indices : Column[int]
             Positions of rows to select.
 
         Returns
         -------
         DataFrame
-
-        Notes
-        -----
-        Some discussion participants prefer a stricter type Column[int] for
-        indices in order to make it easier to implement in a performant manner
-        on GPUs.
         """
         ...
 
@@ -204,6 +241,47 @@ def get_column_names(self) -> Sequence[str]:
         """
         ...
 
+    def sorted_indices(
+        self,
+        keys: Sequence[str],
+        *,
+        ascending: Sequence[bool] | bool = True,
+        nulls_position: Literal['first', 'last'] = 'last',
+    ) -> Column[int]:
+        """
+        Return row numbers which would sort according to given columns.
+
+        If you need to sort the DataFrame, you can simply do::
+
+            df.get_rows(df.sorted_indices(keys))
+
+        Parameters
+        ----------
+        keys : Sequence[str]
+            Names of columns to sort by.
+        ascending : Sequence[bool] or bool
+            If `True`, sort by all keys in ascending order.
+            If `False`, sort by all keys in descending order.
+            If a sequence, it must be the same length as `keys`,
+            and determines the direction with which to use each
+            key to sort by.
+        nulls_position : {'first', 'last'}
+            Whether null values should be placed at the beginning
+            or at the end of the result.
+            Note that the position of NaNs is unspecified and may
+            vary based on the implementation.
+
+        Returns
+        -------
+        Column[int]
+    
+        Raises
+        ------
+        ValueError
+            If `keys` and `ascending` are sequences of different lengths.
+        """
+        ...
+
     def __eq__(self, other: DataFrame | Scalar) -> DataFrame:
         """
         Compare for equality.
@@ -465,7 +543,7 @@ def __iter__(self) -> NoReturn:
         """
         raise NotImplementedError("'__iter__' is intentionally not implemented.")
 
-    def any(self, skipna: bool = True) -> DataFrame:
+    def any(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
 
@@ -476,7 +554,7 @@ def any(self, skipna: bool = True) -> DataFrame:
         """
         ...
 
-    def all(self, skipna: bool = True) -> DataFrame:
+    def all(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
 
@@ -515,49 +593,49 @@ def all_rowwise(self, skipna: bool = True) -> Column:
         """
         ...
 
-    def min(self, skipna: bool = True) -> DataFrame:
+    def min(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
         """
         ...
 
-    def max(self, skipna: bool = True) -> DataFrame:
+    def max(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
         """
         ...
 
-    def sum(self, skipna: bool = True) -> DataFrame:
+    def sum(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
         """
         ...
 
-    def prod(self, skipna: bool = True) -> DataFrame:
+    def prod(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
         """
         ...
 
-    def median(self, skipna: bool = True) -> DataFrame:
+    def median(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
         """
         ...
 
-    def mean(self, skipna: bool = True) -> DataFrame:
+    def mean(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
         """
         ...
 
-    def std(self, skipna: bool = True) -> DataFrame:
+    def std(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
         """
         ...
 
-    def var(self, skipna: bool = True) -> DataFrame:
+    def var(self, skip_nulls: bool = True) -> DataFrame:
         """
         Reduction returns a 1-row DataFrame.
         """
@@ -578,12 +656,14 @@ def isnull(self) -> DataFrame:
         Notes
         -----
         Does *not* include NaN-like entries.
+        May optionally include 'NaT' values (if present in an implementation),
+        but note that the Standard makes no guarantees about them.
         """
         ...
 
     def isnan(self) -> DataFrame:
         """
-        Check for nan-like entries.
+        Check for nan entries.
 
         Returns
         -------
@@ -595,7 +675,8 @@ def isnan(self) -> DataFrame:
 
         Notes
         -----
-        Includes anything with NaN-like semantics, e.g. np.datetime64("NaT").
+        This only checks for 'NaN'.
         Does *not* include 'missing' or 'null' entries.
+        In particular, does not check for `np.timedelta64('NaT')`.
         """
         ...

spec/API_specification/dataframe_api/groupby_object.py

@@ -4,35 +4,47 @@
     from .dataframe_object import DataFrame
 
 
+__all__ = ['GroupBy']
+
+
 class GroupBy:
-    def any(self, skipna: bool = True) -> "DataFrame":
+    """
+    GroupBy object.
+
+    Note that this class is not meant to be constructed by users.
+    It is returned from `DataFrame.groupby`.
+
+    **Methods**
+
+    """
+    def any(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def all(self, skipna: bool = True) -> "DataFrame":
+    def all(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def min(self, skipna: bool = True) -> "DataFrame":
+    def min(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def max(self, skipna: bool = True) -> "DataFrame":
+    def max(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def sum(self, skipna: bool = True) -> "DataFrame":
+    def sum(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def prod(self, skipna: bool = True) -> "DataFrame":
+    def prod(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def median(self, skipna: bool = True) -> "DataFrame":
+    def median(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def mean(self, skipna: bool = True) -> "DataFrame":
+    def mean(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def std(self, skipna: bool = True) -> "DataFrame":
+    def std(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
-    def var(self, skipna: bool = True) -> "DataFrame":
+    def var(self, skip_nulls: bool = True) -> "DataFrame":
         ...
 
     def size(self) -> "DataFrame":