{"record":{"id":"3ae9cc93364f6012","repo":"pandas-dev/pandas","slug":"the-prefix-is-not-allowed-in-top-level-eval-ca","errorCode":null,"errorMessage":"The '@' prefix is not allowed in top-level eval calls.\nplease refer to your variables by name without the '@' prefix.","messagePattern":"The '@' prefix is not allowed in top-level eval calls\\.\nplease refer to your variables by name without the '@' prefix\\.","errorType":"exception","errorClass":"SyntaxError","httpStatus":null,"severity":"error","filePath":"pandas/core/computation/eval.py","lineNumber":175,"sourceCode":"    return s\n\n\ndef _check_for_locals(expr: str, stack_level: int, parser: str) -> None:\n    at_top_of_stack = stack_level == 0\n    not_pandas_parser = parser != \"pandas\"\n\n    if not_pandas_parser:\n        msg = \"The '@' prefix is only supported by the pandas parser\"\n    elif at_top_of_stack:\n        msg = (\n            \"The '@' prefix is not allowed in top-level eval calls.\\n\"\n            \"please refer to your variables by name without the '@' prefix.\"\n        )\n\n    if at_top_of_stack or not_pandas_parser:\n        for toknum, tokval in tokenize_string(expr):\n            if toknum == tokenize.OP and tokval == \"@\":\n                raise SyntaxError(msg)\n\n\n@set_module(\"pandas\")\ndef eval(\n    expr: str | BinOp,  # we leave BinOp out of the docstr bc it isn't for users\n    parser: str = \"pandas\",\n    engine: str | None = None,\n    local_dict=None,\n    global_dict=None,\n    resolvers=(),\n    level: int = 0,\n    target=None,\n    inplace: bool = False,\n) -> Any:\n    \"\"\"\n    Evaluate a Python expression as a string using various backends.\n\n    .. warning::","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/computation/eval.py#L157-L193","documentation":"Raised by _check_for_locals() when the '@' prefix appears in an expression at the top level of the eval stack (level==0) or when using the non-pandas parser. The '@' prefix references local/python-space variables and is only supported inside DataFrame.eval / DataFrame.query (which call eval at a non-zero stack level with the pandas parser). At the top-level pd.eval, there is no meaningful local scope to bind, so it is rejected as a SyntaxError.","triggerScenarios":"Calling pd.eval('@x + 1') directly instead of df.eval('@x + 1'); calling pd.eval('@x + 1', parser='python') which triggers the 'only supported by the pandas parser' message variant.","commonSituations":"Confusing top-level pd.eval with DataFrame.eval — users want to reference a Python variable and reach for pd.eval instead of df.eval; tutorials that show df.eval('@var') being copy-pasted into a pd.eval call.","solutions":["Use DataFrame.eval or DataFrame.query instead of pd.eval when you need '@' variable references: df.eval('@x + col').","If you must use pd.eval, reference variables by name without '@' and pass them via local_dict: pd.eval('x + 1', local_dict={'x': val}).","Switch to the pandas parser if you were on parser='python' and need '@' inside a non-top-level call."],"exampleFix":"// before\nx = 5\npd.eval('@x + 1')\n\n// after (option A)\ndf.eval('@x + col')\n\n// after (option B)\npd.eval('x + 1', local_dict={'x': x})","handlingStrategy":"validation","validationCode":"def safe_eval(expr, **kw):\n    if '@' in expr:\n        # use DataFrame.eval with the frame in scope, or pass local_dict\n        raise ValueError('Use df.eval for @-prefixed variables')\n    return pd.eval(expr, **kw)","typeGuard":null,"tryCatchPattern":"try:\n    pd.eval(expr)\nexcept SyntaxError as e:\n    if '@' in str(e):\n        # switch to DataFrame.eval\n        ...","preventionTips":["Reserve '@' references for DataFrame.eval/df.query, never pd.eval.","Document clearly which eval flavor supports '@'.","Use local_dict for top-level variable injection."],"tags":["pandas","eval","locals","syntax-error","scope"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}