Variables Globales en Python

Las variables globales en Python son variables declaradas fuera de cualquier función. Existen durante toda la vida del programa y pueden leerse desde cualquier lugar, pero modificarlas dentro de una función requiere la palabra clave global. Esta página explica cómo funcionan las variables globales, los errores que debes evitar y cuándo optar por mejores alternativas.

¿Qué Son las Variables Globales?

Una variable global se crea en el ámbito del módulo (nivel superior) — fuera de cualquier función o clase. Cualquier código del mismo módulo puede leerla sin ninguna declaración especial.

Python utiliza la regla LEGB para resolver nombres: busca en los ámbitos Local → Envolvente (Enclosing) → Global → Integrado (Built-in) en ese orden. Una variable global se encuentra en el nivel "G", por lo que cualquier función puede encontrarla después de agotar sus propios ámbitos local y envolvente. Consulta Python Scope para una explicación completa de los cuatro niveles.

Leer vs. Modificar Variables Globales

Leer una variable global (siempre funciona)

Por defecto, una función puede leer cualquier variable global sin ninguna sintaxis especial:

language = "Python"

def print_language():
    print(language)  # reads the global

print_language()  # Output: Python

La palabra clave global — necesaria para modificar

Si intentas asignar un valor a una variable dentro de una función, Python crea una nueva variable local en lugar de actualizar la global. Para modificar la global, debes declararla con la palabra clave global:

counter = 0

def increment():
    global counter   # tell Python we mean the global 'counter'
    counter += 1
    print("Counter:", counter)

increment()  # Output: Counter: 1
increment()  # Output: Counter: 2
print(counter)  # Output: 2

Sin global counter, la línea counter += 1 generaría un UnboundLocalError porque Python intentaría leer una variable local llamada counter antes de que fuera asignada.

El Error UnboundLocalError

Este es el error más común con las variables globales. En el momento en que Python detecta cualquier asignación a un nombre dentro de una función, trata ese nombre como local en toda la función — incluso en las líneas anteriores a la asignación:

x = 10

def broken():
    print(x)   # ERROR — Python sees the assignment below and marks x as local
    x = 20

broken()
# UnboundLocalError: local variable 'x' referenced before assignment

Corrígelo añadiendo global x al principio de la función si realmente necesitas modificar la global, o renombrando la variable local si quieres una copia independiente.

Sombreado de Variables

Asignar un valor a un nombre dentro de una función sin la palabra clave global crea una variable local que sombrea la global — la global no se modifica:

count = 100

def show_count():
    count = 5   # local variable — shadows the global 'count'
    print("Inside function:", count)   # 5

show_count()
print("Outside function:", count)  # 100 — global is unchanged

El sombreado no es un error, pero puede resultar confuso. Usa nombres distintos para que la intención quede clara.

global Dentro de Funciones Anidadas

Si necesitas acceder a una global a nivel de módulo desde una función interna (anidada), usa global — no nonlocal. nonlocal solo alcanza el ámbito de la función envolvente inmediata, no el nivel del módulo:

total = 0

def outer():
    def inner():
        global total   # reaches module scope
        total += 10
    inner()

outer()
outer()
print("total:", total)  # Output: total: 20

Compara esto con nonlocal, que modifica la variable de la función envolvente pero deja la global a nivel de módulo sin cambios:

x = "global"

def outer():
    x = "outer"
    def inner():
        nonlocal x   # modifies outer()'s x, not the module-level x
        x = "inner"
    inner()
    print("outer x after inner():", x)  # inner

outer()
print("global x after outer():", x)   # global — unchanged

Para un análisis más profundo de nonlocal, consulta Python Scope.

Constantes a Nivel de Módulo — El Caso de Uso Correcto

El uso más legítimo de las variables globales a nivel de módulo es para constantes — valores que se establecen una vez y nunca cambian en tiempo de ejecución. Por convención, escríbelas en UPPER_SNAKE_CASE:

MAX_RETRIES = 3
DEFAULT_TIMEOUT = 30

def connect(host, retries=MAX_RETRIES, timeout=DEFAULT_TIMEOUT):
    print(f"Connecting to {host} with {retries} retries, timeout={timeout}s")

connect("db.example.com")
# Output: Connecting to db.example.com with 3 retries, timeout=30s

Las constantes nunca necesitan la palabra clave global porque solo se leen, nunca se reasignan.

Buenas Prácticas

1. Prefiere argumentos de función y valores de retorno

Pasar datos a través de las firmas de función hace que el código sea más fácil de probar y comprender. Esta función pura es más sencilla que usar un counter global mutable:

def increment(counter):
    return counter + 1

counter = 0
counter = increment(counter)
counter = increment(counter)
print("counter:", counter)  # Output: counter: 2

2. Reserva las globales para verdaderas constantes de módulo

Usa las globales para valores que realmente son fijos durante toda la ejecución del programa (MAX_CONNECTIONS, APP_VERSION, configuración cargada una sola vez al inicio). Evita las globales mutables que cambian con el tiempo.

3. Usa nombres descriptivos en UPPER_SNAKE_CASE para las constantes

Un nombre como MAX_RETRIES se reconoce inmediatamente como una constante de módulo. Un nombre como r no lo es.

4. Inicializa antes de usar

Declara todas las variables globales al principio del módulo, antes de cualquier función que las utilice. Esto evita un NameError si una función se llama antes de que la variable estuviera definida de otro modo.

5. Ten cuidado con los hilos (threads)

Si múltiples hilos llaman a funciones que modifican la misma variable global, se produce una condición de carrera. Protege el estado mutable compartido con un threading.Lock, o rediseña el código para evitar el estado compartido por completo. Consulta Python Variables para una visión general más amplia de los tipos de variables en Python.

Resumen

Práctica