add scalar.parent_dataframe (#333)

Author: MarcoGorelli

spec/API_specification/dataframe_api/scalar_object.py

@@ -5,7 +5,7 @@
 if TYPE_CHECKING:
     from typing_extensions import Self
 
-    from dataframe_api.typing import AnyScalar, DType, Namespace
+    from dataframe_api.typing import AnyScalar, DataFrame, DType, Namespace
 
 __all__ = ["Scalar"]
 
@@ -24,8 +24,33 @@ class Scalar(Protocol):
     For example, if `column` is `Column` of dtype `Int64`, then
     `column.get_value(0)` will return a `Scalar` of dtype `Int64`
     (even if it is backed by a null value).
+
+    In binary operations, the comparand's parent DataFrame must be the same as
+    `self`'s - else, the operation is unsupported and may vary across implementations.
     """
 
+    @property
+    def parent_dataframe(self) -> DataFrame | None:
+        """Return parent DataFrame, if present.
+
+        For example, if we have the following
+
+        .. code-block:: python
+
+            df: DataFrame
+            scalar = df.col('a').mean()
+
+        then `scalar.parent_dataframe` should return `df`.
+
+        On the other hand, if we had:
+
+        .. code-block:: python
+
+            scalar = column_from_1d_array(...).mean()
+
+        then `scalar.parent_dataframe` should return `None`.
+        """
+
     def __scalar_namespace__(self) -> Namespace:
         """Return an object that has all the Dataframe Standard API functions on it.