The First Argument:expression

The first argument toeval() is calledexpression. It’s a required argument that holds thestring-based orcompiled-code-based input to the function. When you calleval(), the content ofexpression is evaluated as a Python expression. Check out the following examples that use string-based input:

>>>eval("2 ** 8")256>>>eval("1024 + 1024")2048>>>eval("sum([8, 16, 32])")56>>>x=100>>>eval("x * 2")200

When you calleval() with a string as an argument, the function returns the value that results from evaluating the input string. By default,eval() has access to global names likex in the above example.

To evaluate a string-basedexpression, Python’seval() runs the following steps:

1. Parseexpression
2. Compile it to bytecode
3. Evaluate it as a Python expression
4. Return the result of the evaluation

The nameexpression for the first argument toeval() highlights that the function works only with expressions and not withcompound statements. ThePython documentation definesexpression as follows:

expression

A piece of syntax which can be evaluated to some value. In other words, an expression is an accumulation of expression elements like literals, names, attribute access, operators or function calls which all return a value. In contrast to many other languages, not all language constructs are expressions. There are also statements which cannot be used as expressions, such aswhile. Assignments are also statements, not expressions. (Source)

On the other hand, a Pythonstatement has the following definition:

statement

A statement is part of a suite (a “block” of code). A statement is either an expression or one of several constructs with a keyword, such asif,while orfor. (Source)

If you try to pass a compound statement toeval(), then you’ll get aSyntaxError. Take a look at the following example in which you try to execute anif statement usingeval():

>>>x=100>>>eval("if x: print(x)")Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<string>", line1ifx:print(x)^SyntaxError:invalid syntax

If you try to evaluate a compound statement using Python’seval(), then you’ll get aSyntaxError like in the abovetraceback. That’s becauseeval() only accepts expressions. Any other statement, such asif,for,while,import,def, orclass, will raise an error.

Assignment operations aren’t allowed witheval() either:

>>>eval("pi = 3.1416")Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<string>", line1pi=3.1416^SyntaxError:invalid syntax

If you try to pass an assignment operation as an argument to Python’seval(), then you’ll get aSyntaxError. Assignment operations are statements rather than expressions, and statements aren’t allowed witheval().

You’ll also get aSyntaxError any time the parser doesn’t understand the input expression. Take a look at the following example in which you try to evaluate an expression that violates Python syntax:

>>># Incomplete expression>>>eval("5 + 7 *")Traceback (most recent call last):  File"<input>", line1, in<module>eval("5 + 7 *")  File"<string>", line15+7*^SyntaxError:unexpected EOF while parsing

You can’t pass an expression toeval() that violates Python syntax. In the above example, you try to evaluate an incomplete expression ("5 + 7 *") and get aSyntaxError because the parser doesn’t understand the syntax of the expression.

You can also passcompiled code objects to Python’seval(). To compile the code that you’re going to pass toeval(), you can usecompile(). This is a built-in function that can compile an input string into acode object or anAST object so that you can evaluate it witheval().

The details of how to usecompile() are beyond the scope of this tutorial, but here’s a quick look at its first three required arguments:

1. source holds the source code that you want to compile. This argument accepts normal strings,byte strings, and AST objects.
2. filename gives the file from which the code was read. If you’re going to use a string-based input, then the value for this argument should be"<string>".
3. mode specifies which kind of compiled code you want to get. If you want to process the compiled code witheval(), then this argument should be set to"eval".

You can usecompile() to supply code objects toeval() instead of normal strings. Check out the following examples:

>>># Arithmetic operations>>>code=compile("5 + 4","<string>","eval")>>>eval(code)9>>>code=compile("(5 + 7) * 2","<string>","eval")>>>eval(code)24>>>importmath>>># Volume of a sphere>>>code=compile("4 / 3 * math.pi * math.pow(25, 3)","<string>","eval")>>>eval(code)65449.84694978735

If you usecompile() to compile the expressions that you’re going to pass toeval(), theneval() goes through the following steps:

1. Evaluate the compiled code
2. Return the result of the evaluation

If you call Python’seval() using a compiled-code-based input, then the function performs the evaluation step and immediately returns the result. This can be handy when you need to evaluate the same expression multiple times. In this case, it’s best to precompile the expression and reuse the resulting bytecode on subsequent calls toeval().

If you compile the input expression beforehand, then successive calls toeval() will run faster because you won’t be repeating theparsing andcompiling steps. Unneeded repetitions can lead to high CPU times and excessive memory consumption if you’re evaluating complex expressions.

The Second Argument:globals

The second argument toeval() is calledglobals. It’s optional and holds adictionary that provides a globalnamespace toeval(). Withglobals, you can telleval() which global names to use while evaluatingexpression.

Global names are all those names that are available in yourcurrent global scope or namespace. You can access them from anywhere in your code.

All the names passed toglobals in a dictionary will be available toeval() at execution time. Check out the following example, which shows how to use a custom dictionary to supply a globalnamespace toeval():

>>>x=100# A global variable>>>eval("x + 100",{"x":x})200>>>y=200# Another global variable>>>eval("x + y",{"x":x})Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<string>", line1, in<module>NameError:name 'y' is not defined

If you supply a custom dictionary to theglobals argument ofeval(), theneval() will take only those names as globals. Any global names defined outside of this custom dictionary won’t be accessible from insideeval(). That’s why Python raises aNameError when you try to accessy in the above code: The dictionary passed toglobals doesn’t includey.

You can insert names intoglobals by listing them in your dictionary, and then those names will be available during the evaluation process. For example, if you inserty intoglobals, then the evaluation of"x + y" in the above example will work as expected:

>>>eval("x + y",{"x":x,"y":y})300

Since you addy to your customglobals dictionary, the evaluation of"x + y" is successful and you get the expected return value of300.

You can also supply names that don’t exist in your current global scope. For this to work, you need to supply a concrete value for each name.eval() will interpret these names as global names when running:

>>>eval("x + y + z",{"x":x,"y":y,"z":300})600>>>zTraceback (most recent call last):  File"<stdin>", line1, in<module>NameError:name 'z' is not defined

Even thoughz isn’t defined in your current global scope, thevariable is present inglobals with a value of300. In this case,eval() has access toz as though it were aglobal variable.

The mechanism behindglobals is quite flexible. You can pass any visible variable (global,local, ornonlocal) toglobals. You can also pass custom key-value pairs like"z": 300 in the above example.eval() will treat all of them as global variables.

An important point regardingglobals is that if you supply a custom dictionary to it that doesn’t contain a value for the key"__builtins__", then a reference to the dictionary ofbuiltins will be automatically inserted under"__builtins__" beforeexpression gets parsed. This ensures thateval() will have full access to all of Python’s built-in names when evaluatingexpression.

The following examples show that even though you supply an empty dictionary toglobals, the call toeval() will still have access to Python’s built-in names:

>>>eval("sum([2, 2, 2])",{})6>>>eval("min([1, 2, 3])",{})1>>>eval("pow(10, 2)",{})100

In the above code, you supply an empty dictionary ({}) toglobals. Since that dictionary doesn’t contain a key called"__builtins__", Python automatically inserts one with a reference to the names inbuiltins. This way,eval() has full access to all of Python’s built-in names when it parsesexpression.

If you calleval() without passing a custom dictionary toglobals, then the argument will default to the dictionary returned byglobals() in the environment whereeval() is called:

>>>x=100# A global variable>>>y=200# Another global variable>>>eval("x + y")# Access both global variables300

When you calleval() without supplying aglobals argument, the function evaluatesexpression using the dictionary returned byglobals() as its global namespace. So, in the above example, you can freely accessx andy because they’re global variables included in your currentglobal scope.

The Third Argument:locals

Python’seval() takes a third argument calledlocals. This is another optional argument that holds a dictionary. In this case, the dictionary contains the variables thateval() uses as local names when evaluatingexpression.

Local names are those names (variables,functions,classes, and so on) that you define inside a given function. Local names are visible only from inside the enclosing function. You define these kinds of names when you’re writing a function.

Sinceeval() is already written, you can’t add local names to its code orlocal scope. However, you can pass a dictionary tolocals, andeval() will treat those names as local names:

>>>eval("x + 100",{},{"x":100})200>>>eval("x + y",{},{"x":100})Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<string>", line1, in<module>NameError:name 'y' is not defined

The second dictionary in the first call toeval() holds the variablex. This variable is interpreted byeval() as a local variable. In other words, it’s seen as a variable defined in the body ofeval().

You can usex inexpression, andeval() will have access to it. In contrast, if you try to usey, then you’ll get aNameError becausey isn’t defined in either theglobals namespace or thelocals namespace.

Like withglobals, you can pass any visible variable (global, local, or nonlocal) tolocals. You can also pass custom key-value pairs like"x": 100 in the above example.eval() will treat all of them as local variables.

Note that to supply a dictionary tolocals, you first need to supply a dictionary toglobals. It’s not possible to use keyword arguments witheval():

>>>eval("x + 100",locals={"x":100})Traceback (most recent call last):  File"<stdin>", line1, in<module>TypeError:eval() takes no keyword arguments

If you try to use keyword arguments when callingeval(), then you’ll get aTypeError explaining thateval() takes no keyword arguments. So, you need to supply aglobals dictionary before you can supply alocals dictionary.

If you don’t pass a dictionary tolocals, then it defaults to the dictionary passed toglobals. Here’s an example in which you pass an empty dictionary toglobals and nothing tolocals:

>>>x=100>>>eval("x + 100",{})Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<string>", line1, in<module>NameError:name 'x' is not defined

Given that you don’t provide a custom dictionary tolocals, the argument defaults to the dictionary passed toglobals. In this case,eval() doesn’t have access tox becauseglobals holds an empty dictionary.

The main practical difference betweenglobals andlocals is that Python will automatically insert a"__builtins__" key intoglobals if that key doesn’t already exist. This happens whether or not you supply a custom dictionary toglobals. On the other hand, if you supply a custom dictionary tolocals, then that dictionary will remain unchanged during the execution ofeval().

Boolean Expressions

Boolean expressions are Python expressions that return a truth value (True orFalse) when the interpreter evaluates them. They’re commonly used inif statements to check if some condition is true or false. Since Boolean expressions aren’t compound statements, you can useeval() to evaluate them:

>>>x=100>>>y=100>>>eval("x != y")False>>>eval("x < 200 and y > 100")False>>>eval("x is y")True>>>eval("x in {50, 100, 150, 200}")True

You can useeval() with Boolean expressions that use any of the following Python operators:

• Value comparison operators:<,>,<=,>=,==,!=
• Logical (Boolean) operators:and,or,not
• Membership test operators:in,not in
• Identity operators:is,is not

In all cases, the function returns the truth value of the expression that you’re evaluating.

Now, you may be thinking, why should I useeval() instead of using the Boolean expression directly? Well, suppose you need to implement a conditional statement, but you want to change the condition on the fly:

>>>deffunc(a,b,condition):...ifeval(condition):...returna+b...returna-b...>>>func(2,4,"a > b")-2>>>func(2,4,"a < b")6>>>func(2,2,"a is b")4

Insidefunc(), you useeval() to evaluate the suppliedcondition and return eithera + b ora - b according to the result of the evaluation. You use just a few different conditions in the above example, but you could use any number of others provided that you stick with the namesa andb that you defined infunc().

Now imagine how you would implement something like this without the use of Python’seval(). Would that take less code and time? No way!

Math Expressions

One common use case of Python’seval() is to evaluate math expressions from a string-based input. For example, if you want to create aPython calculator, then you can useeval() to evaluate theuser’s input and return the result of the calculations.

The following examples show how you can useeval() along withmath to perform math operations:

>>># Arithmetic operations>>>eval("5 + 7")12>>>eval("5 * 7")35>>>eval("5 ** 7")78125>>>eval("(5 + 7) / 2")6.0>>>importmath>>># Area of a circle>>>eval("math.pi * pow(25, 2)")1963.4954084936207>>># Volume of a sphere>>>eval("4 / 3 * math.pi * math.pow(25, 3)")65449.84694978735>>># Hypotenuse of a right triangle>>>eval("math.sqrt(math.pow(10, 2) + math.pow(15, 2))")18.027756377319946

When you useeval() to evaluate math expressions, you can pass in expressions of any kind or complexity.eval() will parse them, evaluate them and, if everything is okay, give you the expected result.

General-Purpose Expressions

So far, you’ve learned how to useeval() with Boolean and math expressions. However, you can useeval() with more complex Python expressions that incorporate function calls, object creation, attribute access,comprehensions, and so on.

For example, you can call a built-in function or one that you’ve imported with a standard or third-party module:

>>># Run the echo command>>>importsubprocess>>>eval("subprocess.getoutput('echo Hello, World')")'Hello, World'>>># Launch Firefox (if available)>>>eval("subprocess.getoutput('firefox')")''

In this example, you use Python’seval() to execute a few system commands. As you can imagine, you can do aton of useful things with this feature. However,eval() can also expose you to serious security risks, like allowing a malicious user to run system commands or any arbitrary piece of code in your machine.

In the next section, you’ll look at ways to address some of the security risks associated with eval().

Restrictingglobals andlocals

You can restrict the execution environment ofeval() by passing custom dictionaries to theglobals andlocals arguments. For example, you can pass empty dictionaries to both arguments to preventeval() from accessing names in the caller’scurrent scope or namespace:

>>># Avoid access to names in the caller's current scope>>>x=100>>>eval("x * 5",{},{})Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<string>", line1, in<module>NameError:name 'x' is not defined

If you pass empty dictionaries ({}) toglobals andlocals, theneval() won’t find the namex in either its global namespace or its local namespace when evaluating the string"x * 5". As a result,eval() will throw aNameError.

Unfortunately, restricting theglobals andlocals arguments like this doesn’t eliminate all the security risks associated with the use of Python’seval(), because you can still access all of Python’s built-in names.

Restricting the Use of Built-In Names

As you saw earlier, Python’seval() automatically inserts a reference to the dictionary ofbuiltins intoglobals before parsingexpression. A malicious user could exploit this behavior by using the built-in function__import__() to get access to the standard library and any third-party module that you’ve installed on your system.

The following examples show that you can use any built-in function and any standard module likemath orsubprocess even after you’ve restrictedglobals andlocals:

>>>eval("sum([5, 5, 5])",{},{})15>>>eval("__import__('math').sqrt(25)",{},{})5.0>>>eval("__import__('subprocess').getoutput('echo Hello, World')",{},{})'Hello, World'

Even though you restrictglobals andlocals using empty dictionaries, you can still use any built-in function like you did withsum() and__import__() in the above code.

You can use__import__() to import any standard or third-party module just like you did above withmath andsubprocess. With this technique, you can access any function or class defined inmath,subprocess, or any other module. Now imagine what a malicious user could do to your system usingsubprocess or any other powerful module in the standard library.

To minimize this risk, you can restrict access to Python’s built-in functions by overriding the"__builtins__" key inglobals. Good practice recommends using a custom dictionary containing the key-value pair"__builtins__": {}. Check out the following example:

>>>eval("__import__('math').sqrt(25)",{"__builtins__":{}},{})Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<string>", line1, in<module>NameError:name '__import__' is not defined

If you pass a dictionary containing the key-value pair"__builtins__": {} toglobals, theneval() won’t have direct access to Python’s built-in functions like__import__(). However, as you’ll see in the next section, this approach still doesn’t makeeval() completely secure.

Restricting Names in the Input

Even though you can restrict the execution environment of Python’seval() using customglobals andlocals dictionaries, the function will still be vulnerable to a few fancy tricks. For example, you can access the classobject using atype literal like"",[],{}, or() along with some special attributes:

>>>"".__class__.__base__<class 'object'>>>>[].__class__.__base__<class 'object'>>>>{}.__class__.__base__<class 'object'>>>>().__class__.__base__<class 'object'>

Once you have access toobject, you can use aspecial method,.__subclasses__(), to get access to all of the classes that inherit fromobject. Here’s how it works:

>>>forsub_classin().__class__.__base__.__subclasses__():...print(sub_class.__name__)...typeweakrefweakcallableproxyweakproxyint...

This code willprint a large list of classes to your screen. Some of these classes are quite powerful and can be extremely dangerous in the wrong hands. This opens up another important security hole that you can’t close by simply restricting the execution environment ofeval():

>>>input_string="""[...    c for c in ().__class__.__base__.__subclasses__()...    if c.__name__ == "range"...][0](10)""">>>list(eval(input_string,{"__builtins__":{}},{}))[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

The list comprehension in the above code filters the classes that inherit fromobject to return alist containing the classrange. The first index ([0]) returns the classrange. Once you have access torange, you call it to generate arange object. Then you calllist() on therange object to generate a list of ten integers.

In this example, you userange to illustrate a security hole ineval(). Now imagine what a malicious user could do if your system exposed classes likesubprocess.Popen.

A possible solution to this vulnerability is to restrict the use of names in the input, either to a bunch ofsafe names or tono names at all. To implement this technique, you need to go through the following steps:

1. Create a dictionary containing the names that you want to use witheval().
2. Compile the input string to bytecode usingcompile() in mode"eval".
3. Check.co_names on the bytecode object to make sure it contains only allowed names.
4. Raise aNameError if the user tries to enter a name that’s not allowed.

Take a look at the following function in which you implement all these steps:

>>>defeval_expression(input_string):...# Step 1...allowed_names={"sum":sum}...# Step 2...code=compile(input_string,"<string>","eval")...# Step 3...fornameincode.co_names:...ifnamenotinallowed_names:...# Step 4...raiseNameError(f"Use of{name} not allowed")...returneval(code,{"__builtins__":{}},allowed_names)

Ineval_expression(), you implement all of the steps you saw before. This function restricts the names that you can use witheval() to only those names in the dictionaryallowed_names. To do this, the function uses.co_names, which is an attribute of a code object that returns atuple containing the names in the code object.

The following examples show howeval_expression() works in practice:

>>>eval_expression("3 + 4 * 5 + 25 / 2")35.5>>>eval_expression("sum([1, 2, 3])")6>>>eval_expression("len([1, 2, 3])")Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<stdin>", line10, ineval_expressionNameError:Use of len not allowed>>>eval_expression("pow(10, 2)")Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<stdin>", line10, ineval_expressionNameError:Use of pow not allowed

If you calleval_expression() to evaluate arithmetic operations, or if you use expressions that include allowed names, then you’ll get the expected result. Otherwise, you’ll get aNameError. In the above examples, the only name you’ve allowed issum(). Other names likelen() andpow() are not allowed, so the function raises aNameError when you try to use them.

If you want to completely disallow the use of names, then you can rewriteeval_expression() as follows:

>>>defeval_expression(input_string):...code=compile(input_string,"<string>","eval")...ifcode.co_names:...raiseNameError(f"Use of names not allowed")...returneval(code,{"__builtins__":{}},{})...>>>eval_expression("3 + 4 * 5 + 25 / 2")35.5>>>eval_expression("sum([1, 2, 3])")Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"<stdin>", line4, ineval_expressionNameError:Use of names not allowed

Now your function doesn’t allowany names in the input string. To accomplish this, you check for names in.co_names and raise aNameError if one is found. Otherwise, you evaluateinput_string and return the result of the evaluation. In this case, you use an empty dictionary to restrictlocals as well.

You can use this technique to minimize the security issues ofeval() and strengthen your armor against malicious attacks.

Restricting the Input to Only Literals

A common use case for Python’seval() is to evaluate strings that contain standard Python literals and turn them into concrete objects.

The standard library provides a function calledliteral_eval() that can help achieve this goal. The function doesn’t support operators, but it does supportlists,tuples,numbers, strings, and so on:

>>>fromastimportliteral_eval>>># Evaluating literals>>>literal_eval("15.02")15.02>>>literal_eval("[1, 15]")[1, 15]>>>literal_eval("(1, 15)")(1, 15)>>>literal_eval("{'one': 1, 'two': 2}"){'one': 1, 'two': 2}>>># Trying to evaluate an expression>>>literal_eval("sum([1, 15]) + 5 + 8 * 2")Traceback (most recent call last):...ValueError:malformed node or string: <_ast.BinOp object at 0x7faedecd7668>

Notice thatliteral_eval() only works with standard type literals. It doesn’t support the use of operators or names. If you try to feed an expression toliteral_eval(), then you’ll get aValueError. This function can also help you minimize the security risks associated with the use of Python’seval().