This is an automated email from the ASF dual-hosted git repository.
alenka pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 8c7b291fec GH-41985: [Python][Docs] Clarify docstring of
pyarrow.compute.scalar() (#45668)
8c7b291fec is described below
commit 8c7b291feccdfc48f524dc8049d670d015ee1ca6
Author: ChiLin Chiu <[email protected]>
AuthorDate: Mon Mar 31 03:59:41 2025 +0800
GH-41985: [Python][Docs] Clarify docstring of pyarrow.compute.scalar()
(#45668)
### Rationale for this change
The current docstring for `pyarrow.compute.scalar()` is incomplete and
potentially misleading. It states that it only accepts "a subset of types" when
in reality it accepts any value that can be converted to a `pyarrow.Scalar`.
Additionally, there's no clear explanation of the difference between
`pyarrow.scalar()` and `pyarrow.compute.scalar()`, which can be confusing for
users since both functions have the same name but serve different purposes.
### What changes are included in this PR?
This PR updates the docstring for `pyarrow.compute.scalar()` to clarify
that it accepts any value convertible to a `pyarrow.Scalar` and add a detailed
explanation of the difference between `pyarrow.scalar()` and
`pyarrow.compute.scalar()`
### Are these changes tested?
via CI.
### Are there any user-facing changes?
No.
* GitHub Issue: #41985
Lead-authored-by: Chilin Chiou <[email protected]>
Co-authored-by: ChiLin Chiu <[email protected]>
Co-authored-by: Alenka Frim <[email protected]>
Co-authored-by: Joris Van den Bossche <[email protected]>
Signed-off-by: AlenkaF <[email protected]>
---
docs/source/python/api/compute.rst | 9 +++++++++
python/pyarrow/compute.py | 17 +++++++++++++++--
2 files changed, 24 insertions(+), 2 deletions(-)
diff --git a/docs/source/python/api/compute.rst
b/docs/source/python/api/compute.rst
index 0205457fec..11144baa5d 100644
--- a/docs/source/python/api/compute.rst
+++ b/docs/source/python/api/compute.rst
@@ -590,3 +590,12 @@ User-Defined Functions
register_scalar_function
UdfContext
+
+Expression Functions
+--------------------
+
+.. autosummary::
+ :toctree: ../generated/
+
+ field
+ scalar
diff --git a/python/pyarrow/compute.py b/python/pyarrow/compute.py
index 2daf12dec4..60361b811c 100644
--- a/python/pyarrow/compute.py
+++ b/python/pyarrow/compute.py
@@ -735,11 +735,24 @@ def field(*name_or_index):
def scalar(value):
"""Expression representing a scalar value.
+ Creates an Expression object representing a scalar value that can be used
+ in compute expressions and predicates.
+
Parameters
----------
value : bool, int, float or string
- Python value of the scalar. Note that only a subset of types are
- currently supported.
+ Python value of the scalar. This function accepts any value that can be
+ converted to a ``pyarrow.Scalar`` using ``pa.scalar()``.
+
+ Notes
+ -----
+ This function differs from ``pyarrow.scalar()`` in the following way:
+
+ * ``pyarrow.scalar()`` creates a ``pyarrow.Scalar`` object that represents
+ a single value in Arrow's memory model.
+ * ``pyarrow.compute.scalar()`` creates an ``Expression`` object
representing
+ a scalar value that can be used in compute expressions, predicates, and
+ dataset filtering operations.
Returns
-------
