updating df.query and df.eval docstrings. resolves pandas-dev#16283

Author: Laurent Mutricy

pandas/core/frame.py

@@ -4604,6 +4604,14 @@ def query(self, expr: str, *, inplace: bool = False, **kwargs) -> DataFrame | No
         >>> df[df.B == df["C C"]]
            A   B  C C
         0  1  10   10
+
+        Using local variable:
+
+        >>> local_var = 2
+        >>> df.query("A <= @local_var")
+        A   B  C C
+        0  1  10   10
+        1  2   8    9
         """
         inplace = validate_bool_kwarg(inplace, "inplace")
         if not isinstance(expr, str):
@@ -4644,6 +4652,20 @@ def eval(self, expr: str, *, inplace: bool = False, **kwargs) -> Any | None:
         ----------
         expr : str
             The expression string to evaluate.
+
+            You can refer to variables
+            in the environment by prefixing them with an '@' character like
+            ``@a + b``.
+
+            You can refer to column names that are not valid Python variable names
+            by surrounding them in backticks. Thus, column names containing spaces
+            or punctuations (besides underscores) or starting with digits must be
+            surrounded by backticks. (For example, a column named "Area (cm^2)" would
+            be referenced as ```Area (cm^2)```). Column names which are Python keywords
+            (like "list", "for", "import", etc) cannot be used.
+
+            For example, if one of your columns is called ``a a`` and you want
+            to sum it with ``b``, your query should be ```a a` + b``.
         inplace : bool, default False
             If the expression contains an assignment, whether to perform the
             operation inplace and mutate the existing DataFrame. Otherwise,
@@ -4723,6 +4745,17 @@ def eval(self, expr: str, *, inplace: bool = False, **kwargs) -> Any | None:
         2  3   6   9 -3
         3  4   4   8  0
         4  5   2   7  3
+
+        Local variables shall be explicitely referenced using ``@``
+        character in front of the name:
+
+        >>> local_var = 2
+        >>> df.eval("@local_var * A")
+        0     2
+        1     4
+        2     6
+        3     8
+        4    10
         """
         from pandas.core.computation.eval import eval as _eval