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.