Using and Creating Global Variables in Your Python Functions

Using Global Variables in Python Functions

Global variables are those that you can access and modify from anywhere in your code. In Python, you’ll typically define global variables at the module level. So, the containing module is their scope.

Once you’ve defined a global variable, you can use it from within the module itself or from within other modules in your code. You can also use global variables in your functions. However, those cases can get a bit confusing because of differences between accessing and modifying global variables in functions.

To understand these differences, consider that Python can look for variables in four different scopes:

• The local, or function-level, scope, which exists inside functions
• The enclosing, or non-local, scope, which appears in nested functions
• The global scope, which exists at the module level
• The built-in scope, which is a special scope for Python’s built-in names

To illustrate, say that you’re inside an inner function. In that case, Python can look for names in all four scopes.

When you access a variable in that inner function, Python first looks inside that function. If the variable doesn’t exist there, then Python continues with the enclosing scope of the outer function. If the variable isn’t defined there either, then Python moves to the global and built-in scopes in that order. If Python finds the variable, then you get the value back. Otherwise, you get a NameError:

>>> # Global scope

>>> def outer_func():
...     # Non-local scope
...     def inner_func():
...         # Local scope
...         print(some_variable)
...     inner_func()
...

>>> outer_func()
Traceback (most recent call last):
    ...
NameError: name 'some_variable' is not defined

>>> some_variable = "Hello from global scope!"
>>> outer_func()
Hello from global scope!

When you launch an interactive session, it starts off at the module level of global scope. In this example, you have outer_func(), which defines inner_func() as a nested function. From the perspective of this nested function, its own code block represents the local scope, while the outer_func() code block before the call to inner_func() represents the non-local scope.

If you call outer_func() without defining some_variable in either of your current scopes, then you get a NameError exception because the name isn’t defined.

If you define some_variable in the global scope and then call outer_func(), then you get Hello! on your screen. Internally, Python has searched the local, non-local, and global scopes to find some_variable and print its content. Note that you can define this variable in any of the three scopes, and Python will find it.

This search mechanism makes it possible to use global variables from inside functions. However, while taking advantage of this feature, you can face a few issues. For example, accessing a variable works, but directly modifying a variable doesn’t work:

>>> number = 42

>>> def access_number():
...     return number
...

>>> access_number()
42

>>> def modify_number():
...     number = 7
...

>>> modify_number()
>>> number
42

The access_number() function works fine. It looks for number and finds it in the global scope. In contrast, modify_number() doesn’t work as expected. Why doesn’t this function update the value of your global variable, number? The problem is the scope of the variable. You can’t directly modify a variable from a high-level scope like global in a lower-level scope like local.

Internally, Python assumes that any name directly assigned within a function is local to that function. Therefore, the local name, number, shadows its global sibling.

In this sense, global variables behave as read-only names. You can access their values, but you can’t modify them.

Getting an UnboundLocalError exception is another common issue when you try to modify a global variable inside a function. Consider the following demonstrative function that attempts to use some global variables:

>>> a = 10
>>> b = 20
>>> c = 30

>>> def print_globals():
...     print(a, b, c)
...     c = 100
...     print(c)
...

Inside print_globals(), you first print the global variables a, b, and c. Then you update the value of c directly. Finally, you print the updated version of c. You may be expecting the following output:

>>> # Expected output
>>> print_globals()
10 20 30
100

However, this output never appears on your screen. Instead, you get an error that might surprise you:

>>> print_globals()
Traceback (most recent call last):
    ...
UnboundLocalError: cannot access local variable 'c'
    where it is not associated with a value

The problem is that the assignment c = 100 creates a new local variable that overrides the original global variable, c. So, you have a name conflict. The exception comes from the first call to print() because, at that time, the local version of c isn’t defined yet. So, you get the UnboundLocalError.

In practice, this issue most often occurs in augmented assignment operations with global variables:

>>> counter = 0

>>> def increment():
...     counter += 1
...

>>> increment()
Traceback (most recent call last):
    ...
UnboundLocalError: cannot access local variable 'counter'
    where it is not associated with a value

In Python, if your function simply references a variable from the global scope, then the function assumes that the variable is global. If you assign the variable’s name anywhere within the function’s body, then you define a new local variable with the same name as your original global.

Inside a function, you can’t access a global variable directly if you’ve defined local variables with the same name anywhere in the function.

If you want to modify a global variable inside a function, then you need to explicitly tell Python to use the global variable rather than creating a new local one. To do this, you can use one of the following:

1. The global keyword
2. The built-in globals() function

In the following sections, you’ll learn how to use both tools in your code to change global variables from inside your functions.

global variable_0, variable_1, ..., variable_n

>>> counter = 0

>>> def increment():
...     global counter
...     counter += 1
...

>>> increment()
>>> counter
1
>>> increment()
>>> counter
2

>>> counter = 0

>>> def increment():
...     counter += 1
...     global counter
...
SyntaxError: name 'counter' is assigned to before global declaration

>>> a = 10
>>> b = 20
>>> c = 30

>>> def print_globals():
...     print(a, b, globals()["c"])
...     c = 100
...     print(c)
...

>>> print_globals()
10 20 30
100

>>> c
30

>>> counter = 0

>>> def increment():
...     globals()["counter"] += 1
...

>>> increment()
>>> counter
1
>>> increment()
>>> counter
2

Understanding How Mutability Affects Global Variables

Python has mutable and immutable data types. Mutable types, such as lists and dictionaries, allow you to change or mutate their values in place. In contrast, immutable types, like numbers, strings, and tuples, don’t allow you to modify their values in place.

To quickly illustrate how mutability and immutability work in Python, consider the following example, where you mutate a list in place, changing the value of its elements or items:

>>> numbers = [1, 2, 3]
>>> id(numbers)
4390329600
>>> numbers[0] = 10
>>> numbers[1] = 20
>>> numbers[2] = 30
>>> numbers
[10, 20, 30]
>>> id(numbers)
4390329600

In this example, you mutate the value of numbers. Because Python lists are mutable objects, this mutation doesn’t change the identity of your list object, only its value. You can confirm this by comparing the output of the built-in id() function before and after the mutations.

Now, what will happen if you try to perform a similar action on an immutable type like a tuple? In this code example, you give it a go:

>>> letters = ("a", "b", "c", "d")
>>> letters[0] = "aa"
Traceback (most recent call last):
    ...
TypeError: 'tuple' object does not support item assignment

Here, you use a tuple to store letters. Python tuples are immutable, so you can’t change their items in place like you did with your list of numbers. If you try to do it, then you get a TypeError.

When it comes to using global variables that point to mutable objects inside your functions, you’ll note that it’s possible to change their values in place directly.

For example, say that you’re creating a REST API application. For convenience, you use a global dictionary to share the API configurations across the app’s code. Also for convenience, you write a short function that allows you to update the configuration parameters:

>>> config = {
...     "base_url": "https://example.com/api",
...     "timeout": 3,
... }

>>> def update_config(**kwargs):
...     for key, value in kwargs.items():
...         if key in {"api_key", "base_url", "timeout"}:
...             config[key] = value
...         else:
...             raise KeyError(key)
...

>>> update_config(api_key="111222333")
>>> config
{
    'api_key': '111222333',
    'base_url': 'https://example.com/api',
    'timeout': 3
}

>>> update_config(timeout=5)
>>> config
{
    'api_key': '111222333',
    'base_url': 'https://example.com/api',
    'timeout': 5
}

In this example, the update_config() function allows you to update the app’s configuration parameters. The function takes keyword-only arguments. Each argument must be a valid configuration parameter with its corresponding value. You check this condition with the in operator in a conditional statement. If the parameter is invalid, then the function raises a KeyError.

Because Python dictionaries are mutable data types, you can change the values of config in place from within update_config() without using global or globals(). You can even add new key-value pairs if they’re valid configuration parameters. For example, the first call to update_config() adds the api_key parameter, while the second call updates the timeout parameter.

It’s important to note that configurations and settings are often an important part of an app or system’s global state. Changing a configuration while that system is running mutates its global state. You should only make this type of change if you’re being very careful. Some apps and software systems ask for a restart or reload after you change some of their configuration parameters. That’s a good way to deal with this kind of state mutation.

Creating Global Variables Inside a Function

As you’ve already learned, you can use the global keyword or the built-in globals() function to access and modify a global variable inside a function. What’s really interesting and probably surprising is that you can also use these tools to create global variables inside a function.

In this example, you create a global variable inside a function using the global keyword:

>>> def set_global_variable():
...     global number
...     number = 7
...

>>> set_global_variable()
>>> number
7

Here, the set_global_variable() function uses the global keyword to define number as a global variable. When you call the function, number is defined, and its value is set to 7. After the call, you can access number from anywhere else in the program.

You can also use the globals() function to define new global variables inside your functions. This tool gives you additional flexibility, allowing you to create global variables dynamically:

>>> def dynamic_global_variable(name, value):
...     globals()[name] = value
...

>>> dynamic_global_variable("number", 42)
>>> number
42

In this example, the dynamic_global_variable() function uses the globals() function to define a new global variable using a name as a string and a value. The call to your function creates a new global variable called number with a value of 42.

For a more realistic example, say that you have a configuration file in JSON format. You want to process the file and load all the configuration parameters directly into your global namespace so that you can use these parameters in other parts of your code as global variables.

Your config.json file may look something like this:

{
    "database": {
      "host": "localhost",
      "port": 5432,
      "name": "database.db",
      "user": "username",
      "password": "secret"
    },
    "api_key": "111222333",
    "base_url": "https://example.com/api",
    "timeout": 60
}

This file defines a "database" key, whose value is a dictionary of keys and values. You’ll use this dictionary as the initial setting for your application’s database. The file also defines an API key, a base URL, and a timeout for connecting to an API.

The following code takes care of loading the JSON file and creating the required set of global variables for you:

>>> import json

>>> def set_config_key(key, value):
...     globals()[key] = value
...

>>> with open("config.json") as json_config:
...     for key, value in json.load(json_config).items():
...         set_config_key(key, value)
...

>>> database
{
    'host': 'localhost',
    'port': 5432,
    'name': 'database.db',
    'user': 'username',
    'password': 'secret'
}
>>> api_key
'000111222333'
>>> base_url
'https://example.com/api'
>>> timeout
60

In this code snippet, you define set_config_key(), which takes key and value as arguments. Then you use globals() to create a global variable using key as the variable name and value as its value.

In the with statement, you open the configuration file for reading and assign the file object to the json_config variable. Then you use a for loop to process the loaded configuration and create new global variables for each key-value pair.

After you’ve completed this process, you can access all your configuration parameters as global variables in your code.

Even though defining global variables within your functions using either the global keyword or the globals() function is perfectly possible in Python, it’s not a best practice. You must be careful when defining global variables in this way. Those variables become available to your entire program, so other pieces of your code can modify them. Because of this, you can end up with code that’s difficult to understand, test, maintain, and debug.

Maybe you’re noticing a bit of a pattern. There are plenty of ways to use and define global variables in your functions, but does that mean you should? In the next section, you’ll explore this question.

Deciding When to Use Global Variables

In your programming journey, you’ll find some situations where using a global variable may be appropriate or even necessary. For example, you may use global variables to handle:

• Configurations and settings: If you have settings that apply to your entire program, then using global variables can be a quick solution that will allow you to access these settings from anywhere in your code.
• Small utility scripts: If you’re writing small scripts to automate parts of your workflow or complete tiny tasks, then using global variables can help you get up and running faster, stopping you from overengineering your solutions.
• Caching data: If you need to cache data for performance reasons, then you can take advantage of global variables to store the cached data.

It’s important to note that you should use global variables sparingly and only when absolutely necessary. If you decide to use global variables in your code, then make sure to document their use, especially noting why you’re relying on them.

In practice, using global variables in your code may have some drawbacks. For example, global variables can:

• Make it difficult to keep track of changes to the variable because you can change the variable from anywhere in your code
• Generate unwanted side effects because changes to a global variable can impact the behavior of other parts of your code
• Make your code difficult to test and debug because the behavior and result of your functions will depend on the global variable’s current value
• Affect your code’s reusability because functions that rely on global variables are tightly coupled to those variables
• Cause naming conflicts because you might accidentally reuse a global name in different parts of your code, causing unexpected results
• Break encapsulation because global variables introduce hidden dependencies between different parts of your code
• Make your code hard to refactor because changes in one part of the code can affect other parts

While you can take advantage of global variables to solve specific problems, you’ll be better off minimizing their use in your code. If you still need to use them, then you can avoid some of their downsides by making them constants. That’s because most of the problems with using global variables come from changing their value during your code’s execution.

In the following sections, you’ll learn about some commonly used strategies and techniques to avoid using global variables in your functions.

Avoiding Global Variables in Your Code and Functions

As you learned in the previous section, relying on global variables in your functions and in your code can cause a few undesirable effects. These variables can make your code harder to understand, test, and debug. They can also lead to less maintainable and reusable code. So, you must use global variables with care and control.

Fortunately, there are some neat strategies that you can use to minimize the need for global variables in your code.

API_KEY = "111222333"
BASE_URL = "https://example.com/api"
TIMEOUT = 3

# nasa.py

import webbrowser

import requests

API_KEY = "DEMO_KEY"
BASE_URL = "https://api.nasa.gov/planetary"
TIMEOUT = 3

def load_earth_image(date):
    endpoint = f"{BASE_URL}/apod"
    try:
        response = requests.get(
            endpoint,
            params={
                "api_key": API_KEY,
                "date": date,
            },
            timeout=TIMEOUT,
        )
    except requests.exceptions.RequestException as e:
        print(f"Error connecting to API: {e}")
        return

    try:
        url = response.json()["url"]
    except KeyError:
        print(f"No image available on {date}")
        return

    webbrowser.open(url)

>>> from nasa import load_earth_image

>>> load_earth_image("2023-04-21")

>>> def increment(value=0):
...     return value + 1
...

>>> counter = increment()
>>> counter
1
>>> counter = increment(counter)
>>> counter
2
>>> counter = increment(counter)
>>> counter
3

# account_global.py

balance = 0

def deposit(amount):
    global balance
    balance += amount
    print(f"Successful deposit: +${amount:,.2f}")

def withdraw(amount):
    global balance
    if balance - amount > 0:
        balance -= amount
        print(f"Successful withdrawal: -${amount:,.2f}")
    else:
        print("Not enough funds for this transaction")

def get_balance():
    return balance

def main():
    while True:
        operation = input(
            "What would you like to do?\n"
            " d) deposit  "
            " w) withdraw  "
            " b) balance  "
            " q) quit\n"
            "> "
        )
        if operation in "dD":
            amount = float(input("Enter the deposit amount: "))
            deposit(amount)
        elif operation in "wW":
            amount = float(input("Enter the withdrawal amount: "))
            withdraw(amount)
        elif operation in "bB":
            print(f"Current balance: ${get_balance():,.2f}")
        elif operation in "qQ":
            print("Goodbye!")
            break
        else:
            print("Invalid operation. Please try again.")

main()

$ python account_global.py
What would you like to do?
 d) deposit   w) withdraw   b) balance   q) quit
> d
Enter the deposit amount: 6000
Successful deposit: +$6,000.00
What would you like to do?
 d) deposit   w) withdraw   b) balance   q) quit
> w
Enter the withdrawal amount: 2380
Successful withdrawal: -$2,380.00
What would you like to do?
 d) deposit   w) withdraw   b) balance   q) quit
> b
Current balance: $3,620.00
What would you like to do?
 d) deposit   w) withdraw   b) balance   q) quit
> q
Goodbye!

# account_class.py

class Account:
    def __init__(self, balance=0):
        self.balance = balance

    def deposit(self, amount):
        self.balance += amount
        print(f"Successful deposit: +${amount:,.2f}")

    def withdraw(self, amount):
        if self.balance - amount > 0:
            self.balance -= amount
            print(f"Successful withdrawal: -${amount:,.2f}")
        else:
            print("Not enough funds for this transaction")

def main():
    account = Account()
    while True:
        operation = input(
            "What would you like to do?\n"
            " d) deposit  "
            " w) withdraw  "
            " b) balance  "
            " q) quit\n"
            "> "
        )
        if operation in "dD":
            amount = float(input("Enter the deposit amount: "))
            account.deposit(amount)
        elif operation in "wW":
            amount = float(input("Enter the withdrawal amount: "))
            account.withdraw(amount)
        elif operation in "bB":
            print(f"Current balance: ${account.balance:,.2f}")
        elif operation in "qQ":
            print("Goodbye!")
            break
        else:
            print("Invalid operation. Please try again.")

main()

Conclusion

You’ve learned a lot about using global variables, especially inside your Python functions. You’ve learned that you can access global variables directly in your functions. However, to modify a global variable in a function, you must use either the global keyword or the globals() function.

Global variables allow you to share data across multiple functions, which can be useful in some situations. However, you should use this type of variable carefully and sparingly to avoid writing code that’s difficult to understand, debug, test, and maintain.

In this tutorial, you’ve learned how to:

• Work with global variables in Python
• Directly access global variables within your Python functions
• Modify and create global variables within functions using the global keyword
• Access, create, and modify global variables within your functions with the globals() function
• Use strategies to avoid using global variables in Python code

Now you know what it takes to correctly use global variables inside functions in Python, so you can use them effectively where appropriate. You also know that avoiding global variables is the best way to go most of the time. This will allow you to write more modular, maintainable, and reusable code.

Take the Quiz: Test your knowledge with our interactive “Using and Creating Global Variables in Your Python Functions” quiz. Upon completion you will receive a score so you can track your learning progress over time:

---

Interactive Quiz

Using and Creating Global Variables in Your Python Functions

In this quiz, you'll test your understanding of how to use global variables in Python functions. With this knowledge, you'll be able to share data across an entire program, modify and create global variables within functions, and understand when to avoid using global variables.