From 4ff2f6a71434ec9069945c00e7b4fd3f660079d6 Mon Sep 17 00:00:00 2001
From: MarcoGorelli <33491632+MarcoGorelli@users.noreply.github.com>
Date: Tue, 21 Nov 2023 14:15:23 +0000
Subject: [PATCH] add scalar.parent_dataframe

---
 .../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 078cf2a4..15512898 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
+    from dataframe_api.typing import AnyScalar, DataFrame, DType
 
 __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 __lt__(self, other: AnyScalar) -> Scalar:
         ...