add eval examples (pandas-dev#31955)

Author: MarcoGorelli

pandas/core/computation/eval.py

@@ -276,6 +276,21 @@ def eval(
 
     See the :ref:`enhancing performance <enhancingperf.eval>` documentation for
     more details.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"animal": ["dog", "pig"], "age": [10, 20]})
+    >>> df
+      animal  age
+    0    dog   10
+    1    pig   20
+
+    We can add a new column using ``pd.eval``:
+
+    >>> pd.eval("double_age = df.age * 2", target=df)
+      animal  age  double_age
+    0    dog   10          20
+    1    pig   20          40
     """
     inplace = validate_bool_kwarg(inplace, "inplace")
 

pandas/core/frame.py

@@ -3319,6 +3319,21 @@ def eval(self, expr, inplace=False, **kwargs):
         2  3   6   9
         3  4   4   8
         4  5   2   7
+
+        Multiple columns can be assigned to using multi-line expressions:
+
+        >>> df.eval(
+        ...     '''
+        ... C = A + B
+        ... D = A - B
+        ... '''
+        ... )
+           A   B   C  D
+        0  1  10  11 -9
+        1  2   8  10 -6
+        2  3   6   9 -3
+        3  4   4   8  0
+        4  5   2   7  3
         """
         from pandas.core.computation.eval import eval as _eval