wip

Author: MarcoGorelli

spec/API_specification/dataframe_api/column_object.py

@@ -5,6 +5,7 @@
 if TYPE_CHECKING:
     from .typing import NullType, Scalar, DType, Namespace
     from typing_extensions import Self
+    from dataframe_api.dataframe_object import DataFrame
 
 
 __all__ = ['Column']
@@ -17,8 +18,30 @@ class Column(Protocol):
     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
-
+    :meth:`DataFrame.col`.
     """
+    @property
+    def dataframe(self) -> DataFrame | None:
+        """
+        Return parent DataFrame, if present.
+
+        For example, if we have the following
+
+        .. code-block:: python
+
+            df: DataFrame
+            column = df.col('a')
+        
+        then `column.dataframe` should return `df`.
+
+        On the other hand, if we had:
+
+        .. code-block:: python
+
+            column = column_from_1d_array(...)
+        
+        then `column.dataframe` should return `None`.
+        """
 
     def __column_namespace__(self) -> Namespace:
         """

spec/API_specification/dataframe_api/dataframe_object.py

@@ -142,6 +142,11 @@ def get_rows(self, indices: Column) -> Self:
         Returns
         -------
         DataFrame
+
+        Notes
+        -----
+        `indices`'s parent DataFrame must be `self` - else,
+        the operation is unsupported and may vary across implementations.
         """
         ...
 
@@ -177,8 +182,8 @@ def filter(self, mask: Column) -> Self:
 
         Notes
         -----
-        Some participants preferred a weaker type Arraylike[bool] for mask,
-        where 'Arraylike' denotes an object adhering to the Array API standard.
+        `mask`'s parent DataFrame must be `self` - else,
+        the operation is unsupported and may vary across implementations.
         """
         ...
 
@@ -207,6 +212,11 @@ def assign(self, *columns: Column) -> Self:
         Returns
         -------
         DataFrame
+
+        Notes
+        -----
+        All of `columns`'s parent DataFrame must be `self` - else,
+        the operation is unsupported and may vary across implementations.
         """
         ...