Por qué entender el alcance de las variables en Python
Casi todos los programadores que empiezan con Python se topan, tarde o temprano, con un mensaje de error que parece absurdo: una variable que claramente existe al principio del archivo resulta que “no está definida” dentro de una función, o peor, que “se usa antes de ser asignada”. Detrás de esa confusión hay una sola idea que conviene dominar desde pronto: el alcance (scope) de un nombre, es decir, la región del programa donde ese nombre es visible y puede utilizarse.
En este tutorial recorremos el tema completo con ejemplos propios, pensados para Python 3.14, que es la serie estable actual del lenguaje. Verás qué diferencia hay entre una variable local y una global, cómo decide el intérprete a cuál de ellas te refieres, por qué una asignación dentro de una función cambia las reglas del juego, y cómo usar global y nonlocal cuando de verdad hacen falta. También hablaremos de las alternativas más sanas al estado global, porque saber modificar una variable global no significa que debas hacerlo con frecuencia.
Si todavía estás afianzando los fundamentos del lenguaje, te vendrá bien repasar antes la guía completa para aprender Python pensando en tipos de datos, porque buena parte de lo que sigue depende de entender qué es un objeto mutable y qué es uno inmutable. Todo el código de este artículo funciona sin librerías externas, así que puedes pegarlo en un archivo y ejecutarlo con python3 ejemplo.py.
Nombres, objetos y espacios de nombres
Antes de hablar de variables globales conviene corregir un modelo mental muy extendido. En Python una variable no es una caja con un valor dentro, como ocurre en lenguajes de tipado estático como C. Es un nombre que apunta a un objeto. Escribir contador = 5 no reserva memoria con ese rótulo: crea (o reutiliza) un objeto entero y enlaza el nombre contador con él. Si después escribes contador = "hola", el nombre simplemente pasa a apuntar a otro objeto, de otro tipo, sin que el lenguaje proteste.
Los enlaces entre nombres y objetos viven en estructuras llamadas espacios de nombres (namespaces), que funcionan de forma parecida a diccionarios. Cada módulo tiene el suyo, cada llamada a una función crea uno nuevo y temporal, y el intérprete mantiene además uno con los nombres predefinidos del lenguaje. El alcance de un nombre no es otra cosa que la regla que determina en qué espacios de nombres se busca y en qué orden.
Un detalle que explica casi todos los errores de este tema: Python decide si un nombre es local o no al compilar la función, no mientras la ejecuta. Esa decisión se toma mirando el cuerpo completo de la función antes de que se ejecute la primera línea. Volveremos a ello cuando veamos UnboundLocalError, porque es la clave de todo.
La regla LEGB explicada con calma
Cuando el intérprete encuentra un nombre en una expresión, lo busca en cuatro niveles, siempre en este orden:
- Local: los nombres creados dentro de la función que se está ejecutando.
- Enclosing (envolvente): los nombres de las funciones externas, si la función actual está anidada dentro de otra.
- Global: los nombres definidos en el nivel superior del módulo.
- Built-in (integrado): los nombres que Python ofrece siempre, como
len,print,rangeoValueError.
La búsqueda se detiene en el primer nivel donde aparece el nombre. Si recorre los cuatro y no lo encuentra, lanza NameError. Este esquema se llama la regla LEGB por las iniciales en inglés, y es la columna vertebral de todo lo que vamos a ver. Quien conozca otros lenguajes notará que se trata de alcance léxico: lo que importa es dónde está escrito el código, no desde dónde se llama.
Una buena forma de verlo es con un ejemplo que toca los cuatro niveles a la vez:
umbral = 10 # global
def exterior():
descuento = 3 # envolvente para interior()
def interior():
total = 7 # local
return len([total, descuento, umbral]) # len es integrado
return interior()
print(exterior())
3
Dentro de interior el nombre total se resuelve como local, descuento como envolvente, umbral como global y len como integrado. Ninguna de esas búsquedas necesitó palabras clave especiales, porque solo estamos leyendo.
Variables locales: nacen y mueren con la función
Una variable local es la que se crea mediante una asignación dentro del cuerpo de una función. Existe únicamente mientras la función se ejecuta y solo es visible desde dentro. Cada llamada obtiene su propio espacio de nombres, por lo que dos llamadas simultáneas o sucesivas no comparten sus variables locales.
def calcular_iva(precio):
tasa = 0.21
impuesto = precio * tasa
return round(impuesto, 2)
print(calcular_iva(80))
print(tasa)
16.8
Traceback (most recent call last):
File "iva.py", line 7, in <module>
print(tasa)
NameError: name 'tasa' is not defined
La primera llamada funciona sin problema. La segunda instrucción falla porque tasa solo existió durante la ejecución de calcular_iva. Al terminar la función, su espacio de nombres se descarta y el nombre desaparece con él. Observa que los parámetros de una función también son locales: precio tampoco es accesible fuera.
Esta limpieza automática es una ventaja enorme. Te permite reutilizar nombres cortos como i, total o resultado en cientos de funciones sin que se pisen entre sí. Es también la razón por la que el código bien estructurado en funciones pequeñas resulta fácil de razonar: lo que ocurre dentro no contamina lo de fuera.
Variables globales: las del nivel superior del módulo
Una variable global es la que se define fuera de cualquier función, en el nivel superior del archivo. Su alcance es todo el módulo: cualquier función definida allí puede leerla. Cuando decimos “global” en Python, lo correcto sería decir “global al módulo”, porque no existe un espacio de nombres compartido por todo el programa. Si importas otro módulo, sus variables globales viven en su propio espacio de nombres y las accedes a través de él.
idioma = "es"
version_app = "2.4"
def saludo(nombre):
if idioma == "es":
return f"Hola, {nombre} (v{version_app})"
return f"Hello, {nombre} (v{version_app})"
print(saludo("Lucía"))
print(idioma)
Hola, Lucía (v2.4)
es
La función saludo lee idioma y version_app sin declararlos de ninguna manera. Al no encontrarlos como locales ni envolventes, el intérprete sube hasta el módulo y los halla. Fuera de la función, esas mismas variables también están disponibles, como demuestra el segundo print.
Leer una global es completamente inocuo. Los problemas empiezan cuando intentas escribir en ella, como veremos en un momento. Antes, un caso intermedio que suele confundir: qué pasa cuando local y global comparten nombre.
Cuando dos variables comparten nombre: el sombreado
Si dentro de una función asignas un valor a un nombre que también existe como global, no estás modificando la global: estás creando una variable local nueva con el mismo nombre. Mientras la función se ejecuta, esa local “tapa” a la global. A este fenómeno se le llama sombreado (shadowing).
ciudad = "Valencia"
def cambiar_ciudad():
ciudad = "Sevilla"
print("Dentro:", ciudad)
cambiar_ciudad()
print("Fuera:", ciudad)
Dentro: Sevilla
Fuera: Valencia
La global sigue valiendo “Valencia” después de la llamada. Para muchos principiantes este resultado es una sorpresa, porque esperaban que la función hubiera cambiado la ciudad. Lo que pasó es que la asignación convirtió ciudad en un nombre local de la función, de manera que nunca tocó el del módulo.
El sombreado no es un error, pero casi siempre es una señal de peligro. Es una fuente clásica de bugs silenciosos: el programa no falla, simplemente hace algo distinto de lo que querías. Dar nombres distintos a las variables locales y globales, o mejor aún, evitar depender de las globales, elimina el problema de raíz. Lo mismo se aplica a los nombres integrados: llamar list, max o id a una variable local oculta la función original dentro de ese alcance y provoca fallos desconcertantes.
Por qué asignar a una global dentro de una función falla
Veamos el caso que más tropiezos causa. Supongamos un contador de visitas guardado como variable global, y una función que intenta incrementarlo:
visitas = 0
def registrar_visita():
visitas = visitas + 1
return visitas
registrar_visita()
Traceback (most recent call last):
File "visitas.py", line 7, in <module>
registrar_visita()
File "visitas.py", line 4, in registrar_visita
visitas = visitas + 1
UnboundLocalError: cannot access local variable 'visitas' where it is not associated with a value
El mensaje puede desconcertar: la variable visitas existe y vale cero. ¿Por qué dice que no tiene valor asociado? Por lo que adelantamos antes. Al compilar la función, Python ve una asignación a visitas en su cuerpo y concluye que ese nombre es local en toda la función, incluso en las líneas anteriores a la asignación. Cuando se ejecuta la parte derecha, visitas + 1, intenta leer una variable local que todavía no ha recibido ningún valor, y de ahí el error.
Fíjate en que la lectura sola funcionaría. Si la función se limitara a devolver visitas, el nombre se resolvería como global. Es la presencia de una asignación (con =, con +=, en un bucle for, en un import, en un with ... as, etc.) lo que reclasifica el nombre como local. Entenderlo evita horas de depuración.
La palabra clave global
Para decirle a Python que una asignación dentro de la función debe afectar al nombre del módulo, se usa la declaración global. La escribes al principio de la función, antes de usar el nombre, y a partir de ahí todas las lecturas y escrituras de ese nombre se refieren a la variable del módulo.
visitas = 0
def registrar_visita():
global visitas
visitas += 1
return visitas
registrar_visita()
registrar_visita()
print(visitas)
2
Con global visitas el nombre deja de ser local. Ahora visitas += 1 lee el valor del módulo, le suma uno y lo vuelve a guardar en el módulo. Tras dos llamadas, el contador vale 2 y ese valor es visible desde cualquier parte.
Hay unas cuantas reglas que conviene recordar sobre esta declaración:
- Debe aparecer antes de cualquier uso del nombre en esa función. Si usas el nombre y después lo declaras global, Python lanza
SyntaxError. - No puedes combinar la declaración con la asignación en una sola línea. Escribir
global visitas = 5es un error de sintaxis; hay que declarar primero y asignar después. - Un parámetro de la función no puede declararse global, porque ya es un nombre local por definición.
- La declaración solo vale para la función donde aparece, no para las funciones anidadas dentro ni para las de afuera.
Un ejemplo del error de orden, para que reconozcas el mensaje cuando te lo encuentres:
nivel = 1
def subir():
nivel = 2
global nivel
File "nivel.py", line 5
global nivel
^^^^^^^^^^^^
SyntaxError: name 'nivel' is assigned to before global declaration
Crear una global desde dentro de una función
La declaración global tiene otro efecto menos conocido: si el nombre no existe todavía en el módulo, la asignación dentro de la función lo crea. Eso significa que, después de ejecutar la función, el nombre queda disponible en el resto del programa.
def iniciar_sesion(usuario):
global usuario_activo
usuario_activo = usuario
iniciar_sesion("marta")
print(usuario_activo)
marta
Funciona, pero es una práctica que debes tratar con desconfianza. Quien lea el módulo de arriba abajo no verá nunca la definición de usuario_activo hasta que se ejecute iniciar_sesion, y si por error se consulta antes, obtendrá un NameError. Es mucho más claro declarar siempre la variable en el nivel superior, con un valor inicial como None, y dejar que la función solo la actualice:
usuario_activo = None
def iniciar_sesion(usuario):
global usuario_activo
usuario_activo = usuario
Así el lector sabe desde el principio que existe un estado compartido y cuál es su valor por defecto.
Reasignar no es lo mismo que mutar
Existe una sutileza que desconcierta incluso a quienes ya conocen global: la declaración solo es necesaria cuando reasignas el nombre a otro objeto. Si lo que haces es modificar el objeto al que ya apunta, mediante un método que lo cambia in situ, no hay asignación al nombre y, por tanto, no hace falta declarar nada.
pendientes = []
def anotar(tarea):
pendientes.append(tarea)
anotar("revisar logs")
anotar("actualizar dependencias")
print(pendientes)
['revisar logs', 'actualizar dependencias']
Aquí pendientes es una lista global y la función la modifica sin global, porque append cambia el objeto lista sin reasignar el nombre. En cambio, esta versión sí exige la declaración:
pendientes = []
def vaciar():
global pendientes
pendientes = [] # reasignación: otro objeto lista
vaciar()
Sin la línea global, la función crearía una lista local vacía y la dejaría morir al terminar, sin afectar a la del módulo. Esta diferencia entre mutabilidad y reasignación es central en Python. Si quieres afianzarla, el repaso de objetos mutables e inmutables de la guía sobre tipos de datos que enlazamos arriba es el complemento ideal: los enteros, cadenas y tuplas son inmutables, así que con ellos casi siempre te verás obligado a usar global para cambiarlos, mientras que con listas, diccionarios y conjuntos puedes mutarlos sin declararlo.
Es también un riesgo, porque la facilidad de mutar un objeto compartido desde cualquier función hace que los efectos secundarios se esparzan sin dejar rastro visible. Una función que no declara nada y aun así altera el estado del programa es más difícil de detectar en una revisión de código que otra con un global explícito.
Funciones anidadas y nonlocal
El nivel E de LEGB, el envolvente, aparece cuando defines una función dentro de otra. La función interna puede leer las variables de la externa, y eso es lo que sustenta los cierres (closures). Pero si la interna intenta reasignar una de esas variables, vuelve a ocurrir lo mismo que con las globales: Python la trata como local y falla.
def crear_contador():
cuenta = 0
def incrementar():
cuenta += 1
return cuenta
return incrementar
siguiente = crear_contador()
siguiente()
Traceback (most recent call last):
File "contador.py", line 10, in <module>
siguiente()
File "contador.py", line 5, in incrementar
cuenta += 1
UnboundLocalError: cannot access local variable 'cuenta' where it is not associated with a value
Aquí global no sirve, porque cuenta no es una variable del módulo sino de la función externa. Para eso existe nonlocal, que indica que el nombre pertenece al alcance envolvente más cercano:
def crear_contador():
cuenta = 0
def incrementar():
nonlocal cuenta
cuenta += 1
return cuenta
return incrementar
siguiente = crear_contador()
print(siguiente())
print(siguiente())
print(siguiente())
1
2
3
Cada llamada a crear_contador genera un estado propio e independiente. Si creas dos contadores, cada uno cuenta por su lado, lo cual es exactamente lo contrario de una variable global compartida. Este patrón permite conservar estado entre llamadas sin ensuciar el espacio de nombres del módulo, y es una alternativa mucho más limpia cuando necesitas memoria entre invocaciones.
A diferencia de global, la declaración nonlocal exige que el nombre ya exista en algún alcance envolvente. Si no lo encuentra, Python lanza un SyntaxError al compilar, lo que evita crear variables por accidente.
Comparación con el alcance en JavaScript
Si vienes del desarrollo web, notarás similitudes y diferencias con JavaScript. En ambos lenguajes el alcance es léxico y las funciones internas capturan variables de las externas. Pero JavaScript decide a qué ámbito pertenece una variable según cómo la declares (var, let o const), mientras que Python no tiene declaración de variables: la mera asignación crea un nombre local, y de ahí la necesidad de global y nonlocal para indicar lo contrario.
En JavaScript, una función interna puede asignar directamente a la variable de la función externa, sin ninguna palabra especial, porque la variable ya fue declarada en el ámbito exterior. En Python esa misma intención exige nonlocal. Además, los bloques if, for y while de Python no crean un alcance propio, mientras que en JavaScript moderno las variables declaradas con let y const sí quedan confinadas al bloque. Para profundizar en el modelo del otro lado, puedes leer sobre el alcance léxico en JavaScript, la cadena de alcance y los closures, y comparar cómo cada lenguaje resuelve el mismo problema con herramientas distintas.
Qué estructuras sí crean alcance y cuáles no
Un malentendido frecuente es creer que cualquier bloque con sangría abre un alcance nuevo. En Python solo lo hacen las funciones (incluidas las lambdas), las clases y los módulos, además de las comprensiones y expresiones generadoras, cuya variable de iteración no se filtra al exterior. Los bloques if, for, while, try y with no crean alcance:
for indice in range(3):
mensaje = f"vuelta {indice}"
print(indice)
print(mensaje)
if True:
valor_temporal = 99
print(valor_temporal)
2
vuelta 2
99
Las variables creadas dentro de esos bloques siguen vivas en el alcance que los contiene. Esto es cómodo, pero también peligroso: puedes reutilizar sin querer un nombre del bucle más adelante en el programa y arrastrar un valor viejo. Compáralo con una comprensión de lista:
cuadrados = [n * n for n in range(4)]
print(cuadrados)
print(n)
[0, 1, 4, 9]
Traceback (most recent call last):
File "comp.py", line 3, in <module>
print(n)
NameError: name 'n' is not defined
La variable n de la comprensión es privada de la propia expresión. En versiones recientes del lenguaje la implementación interna de las comprensiones cambió para ganar velocidad, pero la regla visible para ti permanece igual: su variable de iteración no se escapa.
Las clases merecen una advertencia aparte. El cuerpo de una clase tiene su propio espacio de nombres, pero los métodos definidos dentro no pueden ver las variables de clase como si fueran envolventes; deben acceder a ellas mediante self o el nombre de la clase. Es una excepción a la intuición de “lo de afuera se ve desde adentro” y una causa habitual de NameError en código orientado a objetos.
Inspeccionar el estado con globals() y locals()
Python ofrece dos funciones integradas para ver los espacios de nombres como diccionarios. globals() devuelve el espacio de nombres del módulo actual, y locals() el del punto donde se invoca. Son útiles para depurar y para entender cómo funciona el lenguaje por dentro:
tema = "oscuro"
zoom = 125
def mostrar():
local_demo = "solo aquí"
print("tema" in globals())
print("local_demo" in locals())
print("local_demo" in globals())
mostrar()
True
True
False
Con globals() también puedes modificar variables del módulo sin la declaración global, escribiendo en el diccionario que devuelve: globals()["zoom"] = 150. Es una técnica legítima en casos muy concretos, como generar nombres dinámicamente, pero resulta más opaca que global y rompe las herramientas de análisis estático, así que no la uses como atajo.
En cambio, escribir en el diccionario que devuelve locals() dentro de una función no es una forma fiable de cambiar variables locales. Desde Python 3.13 su comportamiento está definido con precisión: en una función devuelve una instantánea independiente, y modificarla no altera las variables reales. Úsala solo para leer.
Estado global en la práctica: configuración y constantes
No todo uso de variables globales es problemático. Hay dos casos donde son perfectamente razonables y habituales.
El primero son las constantes del módulo: valores que se definen una vez y no cambian. Por convención se escriben en mayúsculas, y puedes leerlas desde cualquier función sin preocupación porque nadie las reasigna:
MAX_REINTENTOS = 3
TIEMPO_ESPERA_SEG = 2.5
FORMATO_FECHA = "%Y-%m-%d"
def esperar_y_reintentar(accion):
for intento in range(1, MAX_REINTENTOS + 1):
try:
return accion()
except ConnectionError:
print(f"Intento {intento} fallido")
raise RuntimeError("Se agotaron los reintentos")
Python no impide reasignarlas, pues no existe una palabra clave de constante; la mayúscula es solo un acuerdo entre quienes leen el código. Aun así, es un acuerdo muy sólido y las herramientas de análisis lo respetan. Si necesitas documentar bien qué significa cada una, repasa cómo comentar código en Python con líneas, bloques y docstrings: un breve comentario junto a cada constante ahorra muchas preguntas al equipo.
El segundo caso son los recursos que se crean una sola vez para todo el módulo, como un registrador de eventos (logger) o una expresión regular compilada. Se inicializan en el nivel superior y las funciones solo los usan, sin reasignarlos jamás:
import logging
import re
logger = logging.getLogger(__name__)
PATRON_CORREO = re.compile(r"^[\w.+-]+@[\w-]+\.[\w.]+$")
def es_correo_valido(texto):
valido = bool(PATRON_CORREO.match(texto))
logger.debug("Validando %s: %s", texto, valido)
return valido
Lo que distingue estos usos aceptables de los problemáticos es la mutabilidad del estado: se lee mucho y se escribe nunca, o muy rara vez y en un único lugar.
Por qué el estado global mutable da problemas
Cuando una variable global cambia durante la ejecución, cualquier función que dependa de ella pasa a depender también del orden en que se hayan llamado las demás. Esto trae varias consecuencias prácticas:
- Las funciones dejan de ser predecibles: la misma llamada con los mismos argumentos puede devolver resultados distintos según el estado oculto.
- Las pruebas automáticas se vuelven frágiles. Una prueba deja el contador modificado y la siguiente falla, o pasa solo cuando se ejecuta en cierto orden.
- Depurar cuesta más, porque cualquier línea de cualquier función podría haber cambiado el valor, y no hay una única fuente que revisar.
- En programas concurrentes, dos hilos que incrementan el mismo contador sin sincronización pueden perder actualizaciones. La operación
visitas += 1no es atómica: lee, suma y escribe en pasos separados que pueden intercalarse. - La reutilización se resiente: un módulo que depende de globales de otro queda acoplado a él y es difícil de extraer.
Veamos la fragilidad en las pruebas con un ejemplo concreto:
saldo = 100
def retirar(cantidad):
global saldo
if cantidad > saldo:
raise ValueError("Fondos insuficientes")
saldo -= cantidad
return saldo
Si una prueba retira 60 y otra, independiente, retira 60 más, la segunda fallará aunque cada una por separado sea correcta. Para solucionarlo habría que reiniciar saldo manualmente antes de cada prueba, algo que se olvida con facilidad.
Alternativas más limpias al estado global
La mayoría de las veces puedes evitar global con alguna de estas estrategias, que además hacen el código más fácil de probar.
La primera, y la más sencilla, es pasar datos por parámetros y devolver resultados. La función recibe lo que necesita y entrega lo que calcula, sin tocar nada fuera:
def retirar(saldo, cantidad):
if cantidad > saldo:
raise ValueError("Fondos insuficientes")
return saldo - cantidad
saldo_actual = 100
saldo_actual = retirar(saldo_actual, 60)
print(saldo_actual)
40
Cada llamada es independiente y su resultado depende solo de sus argumentos. Probarla es trivial.
La segunda es encapsular el estado en una clase. Si varias operaciones comparten datos que cambian, una clase con atributos de instancia expresa esa relación con claridad, y puedes crear tantas instancias independientes como necesites:
class Cuenta:
def __init__(self, saldo_inicial=0):
self.saldo = saldo_inicial
def retirar(self, cantidad):
if cantidad > self.saldo:
raise ValueError("Fondos insuficientes")
self.saldo -= cantidad
return self.saldo
cuenta_a = Cuenta(100)
cuenta_b = Cuenta(500)
cuenta_a.retirar(60)
print(cuenta_a.saldo, cuenta_b.saldo)
40 500
La tercera es el cierre con nonlocal, que vimos antes, ideal cuando el estado es pequeño y solo una función lo necesita. La cuarta, en programas asíncronos o con muchos hilos, es el módulo contextvars, que ofrece variables cuyo valor es independiente por contexto de ejecución, algo que una global ordinaria no puede garantizar. Y para configuración que sí debe ser única, puedes agruparla en un objeto inmutable, por ejemplo una dataclass con frozen=True, que se crea al arrancar y se pasa a quien lo necesite.
Errores comunes y cómo resolverlos
Resumimos los fallos más habituales relacionados con el alcance, con su causa y su arreglo:
UnboundLocalErroral incrementar un contador: asignaste al nombre dentro de la función sin declararlo. Arréglalo conglobal(si es del módulo), connonlocal(si es de una función envolvente) o, mejor, pasando el valor por parámetro y devolviendo el resultado.NameErroral usar una variable fuera de la función donde se creó: era local. Devuélvela conreturnen lugar de depender de que sobreviva.SyntaxErrorpor declararglobaldespués de usar el nombre: mueve la declaración al comienzo de la función.- La global “no cambia” tras llamar a la función: casi siempre es sombreado; la función creó una local con el mismo nombre. Revisa si falta la declaración.
- Una lista o diccionario global acumula datos entre llamadas inesperadamente: se está mutando un objeto compartido. Es un problema parecido al de los valores por defecto mutables en parámetros, como
def f(lista=[]), que se evalúan una sola vez y persisten entre llamadas. - Nombres integrados ocultos: si defines
sum = 0en el módulo, la funciónsum()deja de estar disponible en todo el archivo. Evita nombrar variables como funciones integradas. - Importar una variable con
from modulo import contadory esperar que se actualice: elimportcopia el enlace en ese momento. Si el módulo original reasigna su variable después, tu nombre sigue apuntando al objeto antiguo. Para ver cambios, accede conmodulo.contador.
Este último punto merece su ejemplo, porque sorprende incluso a programadores con experiencia:
# estado.py
total = 0
def sumar(n):
global total
total += n
# principal.py
import estado
from estado import total
estado.sumar(5)
print(total) # sigue siendo 0
print(estado.total) # 5
0
5
Buenas prácticas para trabajar con alcances
Después de todo lo anterior, estas son las pautas que más valor aportan en proyectos reales:
- Prefiere parámetros y valores de retorno. Una función que solo depende de sus entradas es la más fácil de entender, probar y reutilizar.
- Usa
globalsolo cuando no exista alternativa razonable, y limítalo a unos pocos puntos bien documentados del programa. - Declara siempre las variables globales en el nivel superior del módulo, con un valor inicial, aunque sea
None, nunca las crees desde dentro de una función. - Nombra las constantes en mayúsculas y no las reasignes; trata el resto del estado global como sospechoso por defecto.
- Evita reutilizar nombres entre alcances: un nombre distinto para cada cosa elimina el sombreado y facilita la lectura.
- Prefiere
nonlocalo clases para el estado que debe sobrevivir entre llamadas, en lugar de una variable de módulo. - Activa un linter (Ruff, Pylint o Flake8) en tu proyecto. Detectan sombreado de nombres integrados, uso de
globaly variables sin usar, y te avisan antes de que el error llegue a producción. - Documenta el estado compartido: una breve nota sobre qué módulos lo modifican y por qué ahorra mucho tiempo a quien mantenga el código después.
- Añade anotaciones de tipo a las variables globales, por ejemplo
visitas: int = 0, para que los verificadores estáticos detecten asignaciones incoherentes.
Un ejemplo completo: refactorizar un script con estado global
Para cerrar la parte práctica, veamos cómo se transforma un script típico. Esta es la versión inicial, con tres variables globales y funciones que dependen de ellas:
inventario = {}
total_articulos = 0
ultima_operacion = None
def agregar(nombre, cantidad):
global total_articulos, ultima_operacion
inventario[nombre] = inventario.get(nombre, 0) + cantidad
total_articulos += cantidad
ultima_operacion = f"agregar {nombre}"
def quitar(nombre, cantidad):
global total_articulos, ultima_operacion
if inventario.get(nombre, 0) < cantidad:
raise ValueError("No hay existencias suficientes")
inventario[nombre] -= cantidad
total_articulos -= cantidad
ultima_operacion = f"quitar {nombre}"
Funciona, pero hay tres variables acopladas que deben mantenerse sincronizadas a mano. Si alguien modifica inventario directamente, total_articulos quedará desfasado. Al llevarlo a una clase, el estado queda agrupado y el total se calcula en lugar de duplicarse:
class Inventario:
def __init__(self):
self._existencias = {}
self.ultima_operacion = None
@property
def total_articulos(self):
return sum(self._existencias.values())
def agregar(self, nombre, cantidad):
self._existencias[nombre] = self._existencias.get(nombre, 0) + cantidad
self.ultima_operacion = f"agregar {nombre}"
def quitar(self, nombre, cantidad):
if self._existencias.get(nombre, 0) < cantidad:
raise ValueError("No hay existencias suficientes")
self._existencias[nombre] -= cantidad
self.ultima_operacion = f"quitar {nombre}"
almacen = Inventario()
almacen.agregar("tornillos", 200)
almacen.quitar("tornillos", 50)
print(almacen.total_articulos, almacen.ultima_operacion)
150 quitar tornillos
No hay ninguna palabra global, el total no puede desincronizarse porque se deriva de los datos, y puedes crear un inventario nuevo y limpio en cada prueba. Esa es la dirección natural de casi todos los scripts que crecen.
Dónde profundizar
El alcance de variables es uno de esos temas que parecen menores y terminan explicando la mitad de los comportamientos extraños del lenguaje: los cierres, los decoradores, los argumentos por defecto mutables, los módulos que se comportan raro al importarlos. Dominarlo te hace más rápido leyendo código ajeno y más seguro escribiendo el tuyo.
Si prefieres apoyarte en un libro que recorra Python desde cero con proyectos prácticos, Python Crash Course, 3rd Edition de Eric Matthes cubre funciones, módulos y clases con un enfoque muy orientado a la práctica. Y como ejercicio personal, te propongo tomar un script tuyo con variables globales, listar cada una con la pregunta “¿realmente cambia?”, convertir en constantes las que no cambian y reemplazar el resto por parámetros o por una clase.
Conclusiones
Las variables globales de Python no son complicadas, pero obedecen a reglas que conviene tener claras. El intérprete resuelve los nombres siguiendo la regla LEGB: primero el nivel local, luego los envolventes, después el módulo y por último los integrados. Leer una variable de un nivel superior siempre es posible, pero asignar a un nombre dentro de una función lo convierte en local a menos que declares lo contrario.
Esa es la causa del famoso UnboundLocalError y del sombreado que hace que una función “no cambie” la variable que esperabas. La declaración global redirige las asignaciones al módulo, y nonlocal hace lo mismo con el alcance de una función envolvente, lo que permite construir cierres con memoria. Recuerda también que reasignar y mutar son cosas distintas: una lista global se puede modificar sin declaración, pero un entero o una cadena exigen global para cambiar de valor.
Con todo, saber hacerlo no implica que debas hacerlo. Las constantes y los recursos de módulo son usos sanos de las globales; el estado mutable compartido, en cambio, complica las pruebas, la depuración y la concurrencia. Si pasas datos por parámetros, devuelves resultados y encapsulas el estado en clases o cierres, tendrás un código más predecible y fácil de mantener. Aplica global como herramienta puntual y no como hábito, y tus programas en Python 3.14 y versiones futuras serán más claros y robustos.
