Skip to main content
`Ctrl`+`K`

# pandas.eval

pandas.eval(expr, parser='pandas', engine=None, local_dict=None, global_dict=None, resolvers=(), level=0, target=None, inplace=False)

  Evaluate a Python expression as a string using various backends.

  Warning

  This function can run arbitrary code which can make you vulnerable to code injection if you pass user input to this function.

  Parameters:
    expr str

      The expression to evaluate. This string cannot contain any Python statements, only Python expressions.

      By default, with the numexpr engine, the following operations are supported:

      - Arithmetic operations: `+`, `-`, `*`, `/`, `**`, `%`

      - Boolean operations: `|` (or), `&` (and), and `~` (not)

      - Comparison operators: `<`, `<=`, `==`, `!=`, `>=`, `>`

      Furthermore, the following mathematical functions are supported:

      - Trigonometric: `sin`, `cos`, `tan`, `arcsin`, `arccos`, `arctan`, `arctan2`, `sinh`, `cosh`, `tanh`, `arcsinh`, `arccosh` and `arctanh`

      - Logarithms: `log` natural, `log10` base 10, `log1p` log(1+x)

      - Absolute Value `abs`

      - Square root `sqrt`

      - Exponential `exp` and Exponential minus one `expm1`

      See the numexpr engine documentation for further function support details.

      Using the `'python'` engine allows the use of native Python operators such as floor division `//`, in addition to built-in and user-defined Python functions.

      Additionally, the `'pandas'` parser allows the use of `and`, `or`, and `not` with the same semantics as the corresponding bitwise operators.

    parser{‘pandas’, ‘python’}, default ‘pandas’

      The parser to use to construct the syntax tree from the expression. The default of `'pandas'` parses code slightly different than standard Python. Alternatively, you can parse an expression using the `'python'` parser to retain strict Python semantics. See the enhancing performance documentation for more details.

    engine{‘python’, ‘numexpr’}, optional, default None

      The engine used to evaluate the expression. Supported engines are

      - None : tries to use `numexpr`, falls back to `python`

      - `'numexpr'` : This is the default engine when `numexpr` is installed. Evaluates pandas objects using numexpr for large speed ups in complex expressions with large frames.

      - `'python'` : Performs operations as if you had `eval`’d in top level python. This engine is generally not that useful.

      More backends may be available in the future.

    local_dict dict or None, optional

      A dictionary of local variables, taken from locals() by default.

    global_dict dict or None, optional

      A dictionary of global variables, taken from globals() by default.

    resolvers list of dict-like or None, optional

      A list of objects implementing the `__getitem__` special method that you can use to inject an additional collection of namespaces to use for variable lookup. For example, this is used in the `query()` method to inject the `DataFrame.index` and `DataFrame.columns` variables that refer to their respective `DataFrame` instance attributes.

    level int, optional

      The number of prior stack frames to traverse and add to the current scope. Most users will not need to change this parameter.

    target object, optional, default None

      This is the target object for assignment. It is used when there is variable assignment in the expression. If so, then target must support item assignment with string keys, and if a copy is being returned, it must also support .copy().

    inplace bool, default False

      If target is provided, and the expression mutates target, whether to modify target inplace. Otherwise, return a copy of target with the mutation.

  Returns:
    ndarray, numeric scalar, DataFrame, Series, or None

      The completion value of evaluating the given code or None if `inplace=True`.

  Raises:
    ValueError

      There are many instances where such an error can be raised:

      - target=None, but the expression is multiline.

      - The expression is multiline, but not all them have item assignment. An example of such an arrangement is this:

        a = b + 1 a + 2

        Here, there are expressions on different lines, making it multiline, but the last line has no variable assigned to the output of a + 2.

      - inplace=True, but the expression is missing item assignment.

      - Item assignment is provided, but the target does not support string item assignment.

      - Item assignment is provided and inplace=False, but the target does not support the .copy() method

  See also

  `DataFrame.query`

    Evaluates a boolean expression to query the columns of a frame.

  `DataFrame.eval`

    Evaluate a string describing operations on DataFrame columns.

  Notes

  The `dtype` of any objects involved in an arithmetic `%` operation are recursively cast to `float64`.

  See the enhancing performance 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