chore: document Expr.__getitem__ (get a field of a struct array)

Signed-off-by: Daniel King <[email protected]>

Author: danking

docs/api/python/expr.rst

@@ -32,3 +32,36 @@ the following expression represents the set of rows for which the `age` column l
 .. autofunction:: vortex.expr.literal
 
 .. autoclass:: vortex.expr.Expr
+   :members:
+
+   .. py:method:: __getitem__(name, /)
+
+      Extract a field of a struct array.
+
+      :parameters:
+
+          - **name** (:class:`.str`) -- The name of the field.
+
+      :return type:
+
+          :class:`.vortex.Expr`
+
+      .. rubric:: Examples
+
+      >>> import vortex as vx
+      >>> import vortex.expr as ve
+      >>> import pyarrow as pa
+      >>>
+      >>> array = pa.array([
+      ...     {"x": 1, "y": {"yy": "a"}},
+      ...     {"x": 2, "y": {"yy": "b"}},
+      ... ])
+      >>>
+      >>> vx.io.write(vx.array(array), '/tmp/foo.vortex')
+      >>> (vx.file.open('/tmp/foo.vortex')
+      ...    .scan(expr=vx.expr.column("y")["yy"] == "a")
+      ...    .read_all()
+      ...    .to_pylist()
+      ... )
+      [{'x': 1, 'y': {'yy': 'a'}}]
+

vortex-python/src/expr/mod.rs

@@ -159,6 +159,8 @@ impl PyExpr {
         py_binary_operator(self_, Operator::Or, coerce_expr(right)?)
     }
 
+    // Special methods docstrings cannot be defined in Rust. Write a docstring in the corresponding
+    // rST file. https://github.com/PyO3/pyo3/issues/4326
     fn __getitem__(self_: PyRef<'_, Self>, field: String) -> PyResult<PyExpr> {
         get_item(field, self_.clone())
     }