La lección anterior terminó con tres preguntas sin responder. ¿Por qué pedir_opcion puede leer la constante PRIORIDADES sin que se la pasemos? ¿Qué pasaría si dentro de una función escribiéramos titulo = "otro": cambiaría el titulo del programa principal? ¿Y por qué la variable valor que vive dentro de pedir_texto no existe fuera de ella?

Las tres son la misma pregunta con distinta ropa: dónde vive cada nombre y quién puede verlo. Eso se llama ámbito (scope), y es una de esas ideas que, mientras no se entienden, producen errores desconcertantes: funciones que «no ven» una variable que está claramente escrita más arriba, cambios que se pierden sin dejar rastro, valores que aparecen donde no deberían.

Entender el ámbito no es un lujo teórico: es lo que convierte una función en una caja segura, algo que puedes usar sabiendo que no va a estropear nada de lo que hay fuera. Y es, además, la base de una regla de oro que aplicaremos en la lección siguiente: una función bien hecha depende solo de lo que recibe por parámetros.

1. Ámbito local: nacer y morir con la llamada
2. Ámbito global
3. La regla LEGB
4. Leer una global no es lo mismo que asignarla
5. La palabra global y por qué se desaconseja
6. Sombreado de nombres
7. Cómo se pasan los argumentos en Python
8. Constantes globales: la excepción aceptada
9. Funciones anidadas y nonlocal
10. Ámbito y depuración
11. TareaFácil: auditoría de las funciones
12. Errores comunes y consejos
13. Ejercicios
14. Conclusión

Toda variable creada dentro de una función —sea por asignación, sea por ser un parámetro— es local a esa función: existe mientras la llamada se ejecuta y desaparece en cuanto termina.

La primera línea funciona; la segunda no. subtotal e impuestos existieron, hicieron su trabajo y se esfumaron: fuera de la función Python no tiene ningún nombre llamado subtotal, y por eso responde con el NameError que ya conoces de 04-01. Esto, que parece una limitación, es en realidad la mejor propiedad de las funciones. Significa que puedes escribir una función usando los nombres que te dé la gana —i, valor, total— con la garantía de que no vas a pisar nada de lo que hay fuera. Sin ámbito local, cada nombre que usaras dentro de una función sería una mina para el resto del programa, y no podrías escribir ni cincuenta líneas sin colisionar contigo mismo. Funciona también entre funciones distintas: si pedir_titulo y pedir_prioridad usan las dos una variable llamada valor, no se estorban en absoluto, porque son dos variables distintas que casualmente comparten nombre, cada una en su propia caja.

El ámbito global es el del fichero: todo lo que se define en el margen izquierdo, fuera de cualquier función. Esas variables se llaman globales y son visibles desde cualquier punto del módulo, incluido el interior de las funciones.

Aquí está la respuesta a la primera pregunta de la lección: pedir_opcion podía leer PRIORIDADES porque las constantes son globales y las funciones pueden leer lo global sin pedir permiso.

Ahora bien, que se pueda no significa que convenga: una función que lee variables globales cambiantes deja de ser autónoma, porque su resultado ya no depende solo de lo que recibe sino del estado en que esté el programa en ese momento, lo que la vuelve impredecible al leerla e imposible de probar por separado. Volveremos sobre ello en la sección 8, con la única excepción razonable: las constantes.

Cuando Python encuentra un nombre, lo busca en cuatro sitios y en este orden, quedándose con el primero que encuentre. La regla se conoce por sus iniciales en inglés: LEGB.

Léelo como una búsqueda que baja escalones: si el nombre está en la capa local, se usa ese y no se mira más abajo; si no, se prueba la envolvente; luego la global; luego las funciones integradas; y si tampoco está ahí, NameError. Una consecuencia inmediata y muy útil: el nombre más cercano gana. Si una función tiene una variable local total y además existe una global total, dentro de la función total se refiere siempre a la local. La global sigue existiendo, intacta, pero queda tapada mientras dure la llamada.

Aquí está el punto que más confusión genera de toda la lección. Acabamos de ver que leer una global desde dentro de una función funciona sin más. Cambiemos una sola cosa: asignar en lugar de leer.

Parece contradictorio, pero la regla es sencilla y no tiene excepciones: si en algún punto del cuerpo de una función hay una asignación a un nombre, ese nombre es local en toda la función. Python decide eso al compilar la función, antes de ejecutar nada. Así que contador es local dentro de incrementar, y la línea contador = contador + 1 intenta leer una local que todavía no tiene valor. De ahí el UnboundLocalError, que es un NameError especializado.

Y ojo con la variante que no da error, aún más peligrosa:

La función parece haber cambiado el contador, e incluso lo imprime cambiado, pero fuera todo sigue igual. Este es el error del que hablábamos: no falla, no avisa, y no hace lo que parece. Si alguna vez te preguntas «he asignado la variable dentro de la función y fuera no cambia», esta es la explicación.

Python ofrece una manera de forzar que la asignación afecte a la variable global: declararla con global al principio del cuerpo.

Funciona. Y aun así, la recomendación de prácticamente toda la comunidad Python es no usarlo salvo en casos muy contados. La razón se entiende mejor viendo lo que rompe:

calcular_media tenía un nombre inocente —«calcular»— y ha modificado el estado compartido. A partir de ahí, total_horas ya no son horas totales ni una media: es un número sin significado, y el programa seguirá funcionando sin quejarse. Imagina esto en un fichero de mil líneas con quince funciones que escriben la misma global: para saber cuánto vale una variable en un punto tendrías que leerte el programa entero.

La alternativa siempre es la misma: recibir por parámetro y devolver con return. La versión sana sería def registrar_jornada(total, horas): return total + horas, y que el programa principal guarde el resultado. Una línea más y un problema menos.

Sombrear (shadowing) es declarar un nombre que tapa otro de una capa más externa. Ocurre continuamente y muchas veces es inofensivo, pero tiene una versión que hace daño de verdad: sombrear un built-in.

Al asignar a list, la capa global se ha quedado con ese nombre y la búsqueda LEGB ya no llega nunca a la capa built-in. El error, además, aparece lejos del punto donde se causó, a veces cientos de líneas después. Estos son los nombres que más se sombrean por accidente:

Sombrear input es especialmente cruel en un programa como TareaFácil: escribes input = input("Titulo: ") una vez y la siguiente llamada a input(...) da TypeError: 'str' object is not callable, porque input ya no es la función sino la cadena que tecleaste. La defensa es simple: si tu editor colorea un nombre como si fuera especial, no lo uses para una variable.

Ya sabes que un argumento se asigna al parámetro. Pero ¿qué se asigna exactamente, el valor o «la variable»? En Python, lo que se pasa es la referencia al objeto: el parámetro pasa a apuntar al mismo objeto que el argumento. La consecuencia práctica, con los tipos que conoces —números, cadenas, booleanos, todos inmutables—, es tranquilizadora: reasignar el parámetro dentro no afecta a la variable de fuera.

Traza de lo ocurrido: al llamar, el parámetro dias apunta al mismo objeto 4 que plazo. La línea dias = dias + 5 crea un objeto nuevo, 9, y hace que el nombre local dias apunte a él; plazo sigue apuntando a 4, porque el número 4 no ha cambiado —no puede: los enteros son inmutables. La única forma de que el exterior se entere del nuevo valor es el return.

Lo mismo pasa con las cadenas. Si una función normalizar(texto) hace texto = texto.strip().capitalize() y devuelve el resultado, la variable que pasaste desde fuera sigue con sus espacios y sus minúsculas intactos: es lo que viste en 02-01 sobre la inmutabilidad de las cadenas, ahora en el contexto de una llamada. Los métodos de cadena devuelven una cadena nueva; no modifican la original.

Un adelanto honesto: con objetos mutables —las listas del módulo 5— la historia tiene un capítulo más, porque una función sí puede modificar el contenido del objeto recibido y que el cambio se vea fuera. Lo que acabas de aprender sigue siendo cierto (reasignar el nombre nunca afecta al exterior), pero habrá que distinguir entre reasignar y modificar. Hoy, con números y cadenas, no hay ambigüedad posible.

Después de tanta advertencia contra las globales, ¿por qué PRIORIDADES y EQUIPO viven en el nivel global y las leemos desde cualquier función sin remordimiento? Porque son constantes, y una constante no tiene los defectos de una global cambiante: no cambia nunca durante la ejecución, así que el resultado de la función sigue siendo predecible; se declara en un solo sitio, arriba del fichero, donde cualquiera la encuentra; se distingue a simple vista por el convenio de MAYÚSCULAS de 02-01; y documenta el dominio del problema, porque PRIORIDADES = ("alta", "media", "baja") dice qué prioridades existen en Estudio Alba, y eso es información del negocio, no estado del programa.

Un matiz de estilo: aunque leer una constante global sea legítimo, a veces conviene pasarla igualmente por parámetro. Es lo que hicimos con pedir_opcion(mensaje, opciones): pasándole las opciones, la función sirve para prioridades, para responsables y para lo que venga; leyendo PRIORIDADES directamente, solo serviría para prioridades. Regla práctica: si la constante forma parte de lo que la función hace, pásala; si es un detalle de presentación compartido por todo el programa, como ANCHO, léela.

Falta explicar la E de LEGB. En Python puedes definir una función dentro de otra, y la de dentro ve los nombres de la de fuera, que forman su ámbito envolvente (enclosing).

Y si la función interna necesitara asignar a un nombre de la envolvente, existe la palabra nonlocal, hermana de global pero apuntando una capa más arriba en vez de al fichero entero. No la usaremos en el curso: con lo que sabes hoy, la solución limpia sigue siendo pasar el dato por parámetro y devolverlo. Basta con que reconozcas nonlocal cuando lo veas y sepas que se refiere a la capa envolvente. Las funciones anidadas sí volverán a aparecer, con un propósito muy concreto, en Funciones como valores.

Hay una razón muy práctica para tomarse el ámbito en serio: el estado global disperso multiplica el tiempo que tardas en encontrar un error. Cuando una función depende solo de sus parámetros, diagnosticar un fallo es un problema cerrado: miras los argumentos, miras el valor devuelto y el error está dentro o no está. Cuando depende de globales que cualquiera puede modificar, la pregunta «¿por qué aquí total_horas vale 12?» no se responde mirando la función: hay que reconstruir toda la historia de la ejecución. Es la diferencia entre revisar una habitación y registrar un edificio.

Por eso, cuando algo no cuadre, la primera pregunta útil es: ¿de qué depende esta función? Si la respuesta es «solo de lo que recibe», ya has acotado el problema. Las técnicas concretas para investigar —trazas, puntos de interrupción, lectura de un traceback— son el tema de Depuración y manejo de errores; lo que el ámbito te da es un programa en el que esas técnicas funcionan rápido.

Toca revisar lo escrito en 04-02 con la pregunta de la sección anterior: ¿de qué depende cada función? Además de las cuatro que ya conoces, habíamos esbozado una quinta, mostrar_resumen(), para pintar la línea de estado de la tarea.

Los cuatro primeros están limpios: puedes copiarlos a otro fichero y funcionan tal cual. mostrar_resumen() no: fuera de TareaFácil no sirve para nada, no se puede probar con datos inventados y, si mañana el programa gestionara dos tareas, no habría manera de decirle cuál pintar. La corrección es mecánica —convertir cada global leída en un parámetro:

Fíjate en las dos llamadas seguidas con datos distintos: eso, que ahora parece trivial, era imposible con la versión que leía globales. Y observa que mostrar_resumen sí llama a clasificar_urgencia, que es una función global: eso no es un problema de ámbito, porque las funciones, como las constantes, se definen una vez y no cambian. Con esto, tareafacil.py queda en un estado saneado: constantes globales arriba, funciones que dependen solo de sus parámetros, y el estado de la tarea todavía en variables sueltas del programa principal. Ese estado suelto es el último cabo que queda, y lo ataremos en la lección siguiente.

Usar fuera una variable local. NameError. Lo que nace dentro de una función muere con ella: si necesitas ese valor fuera, devuélvelo con return.

Asignar a una global creyendo que la cambias. contador = 10 dentro de una función crea una local nueva y deja la global intacta, sin dar ningún error. Si el valor de fuera «no se actualiza», es esto.

UnboundLocalError. Aparece cuando lees un nombre que también asignas dentro de la función: la asignación lo ha hecho local en todo el cuerpo. Solución: recíbelo por parámetro y devuélvelo.

Sombrear un built-in. Llamar list, input, str o sum a una variable rompe el programa mucho después y en otro sitio. Añade una palabra: lista_tareas, texto_entrada. Y no abuses de global: funciona, y por eso tienta, pero cada global que escribes es una función que ya no puedes razonar por separado.

Consejo: haz la prueba del recorte. Copia una función a un fichero vacío. Si funciona sin arrastrar nada más, es autónoma; si le faltan nombres, esos nombres deberían ser parámetros. Y pon las constantes arriba y en MAYÚSCULAS: es la señal visual de «esto es global a propósito», y hace que cualquier otra global salte a la vista como sospechosa.

Di qué imprime cada bloque, y en su caso qué error se produce y por qué.

Reescribe este programa para que ninguna función dependa de variables globales cambiantes, usando parámetros y return. Las constantes en MAYÚSCULAS pueden quedarse donde están.

Este programa imprime Hola y luego se rompe. Explica exactamente qué ocurre, en qué línea se causa el daño y en cuál se manifiesta, y arréglalo.

Solución 1.

El bloque C es el más instructivo: la línea que falla (print(z)) es anterior a la línea culpable (z = 99). Python decide qué nombres son locales al compilar la función, no al ejecutarla línea a línea.

Solución 2.

El acumulador sigue existiendo, pero ahora vive en el programa principal y viaja explícitamente por parámetros y valores devueltos: en cada línea se ve quién cambia qué. Además, facturar acepta una tarifa distinta si algún día hace falta, sin tocar la constante.

Solución 3. La línea str = "Cartel feria del libro" sombrea la función integrada str, dejando ese nombre apuntando a una cadena. Nada falla todavía: print(str) imprime el texto sin problema. El daño se manifiesta dos líneas después, en str(2026), que intenta llamar a una cadena como si fuera una función y produce TypeError: 'str' object is not callable. La corrección es renombrar la variable:

La moraleja es la distancia entre la causa y el síntoma: en un fichero largo, esas dos líneas podrían estar separadas por doscientas, y el mensaje de error apuntaría a la inocente.

Ya sabes dónde vive cada nombre. Las variables creadas dentro de una función son locales: nacen con la llamada, mueren al terminar y no existen fuera, lo que garantiza que una función no pise nada del resto del programa. Los nombres se buscan siguiendo la regla LEGB —local, envolvente, global, integrado—, y gana siempre el más cercano. Desde dentro de una función se puede leer una global sin más, pero asignarla crea una variable local nueva; forzar lo contrario con global funciona y casi nunca conviene, porque convierte cada función en algo que solo se entiende leyendo el programa entero. Sombrear nombres integrados como list o input produce errores lejos de donde se causaron. Y al pasar argumentos, Python entrega la referencia al objeto: con números y cadenas, inmutables, reasignar dentro nunca afecta a lo de fuera, así que la única vía de comunicación hacia el exterior es el return.

La regla que resume todo esto cabe en una línea: una función debería depender solo de sus parámetros, y comunicarse con el exterior solo por su valor devuelto. Las constantes en MAYÚSCULAS son la excepción aceptada, porque no cambian. Aplicándola, la auditoría de TareaFácil ha dejado limpias las cuatro funciones de validación y ha corregido mostrar_resumen(), que leía el estado global y ahora recibe lo que necesita. Tienes ya las tres piezas de la ingeniería de funciones: definir y llamar (04-01), parámetros y return (04-02) y ámbito (04-03). Lo que falta es el criterio para usarlas a escala: cómo partir un programa entero de cien líneas en funciones del tamaño adecuado, cómo decidir qué va en cada una y en qué orden escribirlas. Eso es Descomponer un programa en funciones, donde TareaFácil pasará por fin de la v0.6 a la v0.7.