From c5f08352e0a1d25387fe1737ffe9cccb36f554f7 Mon Sep 17 00:00:00 2001
From: Marco Edward Gorelli <marcogorelli@protonmail.com>
Date: Tue, 19 Dec 2023 07:48:34 +0000
Subject: [PATCH] add scalar.parent_dataframe (#333)

---
 .../dataframe_api/scalar_object.py            | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/spec/API_specification/dataframe_api/scalar_object.py b/spec/API_specification/dataframe_api/scalar_object.py
index 39ff27ba..32ac3c8a 100644
--- a/spec/API_specification/dataframe_api/scalar_object.py
+++ b/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.