В Python разрешение области видимости переменной выполняется статически на этапе компиляции, а не динамически во время выполнения. Когда компилятор CPython встречает определение функции, он проходит дерево абстрактного синтаксиса, чтобы построить таблицу символов, которая классифицирует каждое имя как локальное, глобальное или ячейка. Если компилятор обнаруживает любое действие привязки — такое как присвоение, увеличенное присвоение или импорт — для имени где-либо в теле функции, он помечает это имя как локальную переменную на всем протяжении функции. Эта схема позволяет виртуальной машине использовать оптимизированные опкоды LOAD_FAST, которые работают с массивом фиксированного размера, а не выполняют более медленные операции поиска в хеш-таблицах. Эта оптимизация является основополагающей для производительности вызовов функций в Python, но вводит строгие требования по привязке.
Когда имя классифицируется как локальное, компилятор выдает байт-код LOAD_FAST для всех операций чтения этого имени. Во время выполнения LOAD_FAST пытается извлечь ссылку на объект из соответствующего индекса в массиве локальных переменных кадра. Если слот содержит нулевой указатель, указывающий на то, что значение еще не присвоено, во время выполнения возникает ошибка UnboundLocalError. Это происходит даже если глобальная переменная с таким же именем существует, потому что компилятор специально избегает выдачи LOAD_GLOBAL. Ошибка четко указывает на это статическое решение области видимости, отличая её от NameError.
Для решения этой проблемы вам нужно явно сообщить компилятору, что имя ссылается на глобальное пространство имен, объявив global <имя_переменной>. Это объявление заставляет компилятор переключаться на опкоды LOAD_GLOBAL и STORE_GLOBAL, которые динамически ищут имя в глобальном словаре модуля. В качестве альтернативы перестроить код так, чтобы все локальные переменные были инициализированы в начале функции перед любой логикой условий, читающей их. Для вложенных областей видимости ключевое слово nonlocal заставляет компилятор использовать LOAD_DEREF для доступа к ячейкам замыкания. Эти объявления изменяют решение компилятора о привязке на этапе компиляции, предотвращая ситуацию с необъязанной локальной переменной.
threshold = 100 def analyze(data): # Компилятор видит 'threshold = ...' ниже и помечает его как локальную if data > threshold: # Вызывает UnboundLocalError return "high" threshold = 50 # Присвоение делает его локальным # Решение с использованием 'global' def analyze_fixed(data): global threshold if data > threshold: # LOAD_GLOBAL успешно return "high" threshold = 50 # Обновляет глобальную переменную
Команда по обработке данных строила ETL-пайплайн с использованием Apache Airflow. Они определили словарь конфигурации по умолчанию CONFIG = {"batch_size": 1000} на уровне модуля, чтобы упростить настройку параметров обработки. Главная функция трансформации process_batch() изначально проверяла if len(records) > CONFIG["batch_size"]:, чтобы определить, необходимо ли разделение. Позже в функции, при определенном условии, код попытался оптимизировать использование памяти, изменив размер партии на CONFIG = {"batch_size": 500}. Этот шаблон непреднамеренно вызвал конфликт области видимости.
Когда пайплайн выполнялся, он упал на первой строке функции с UnboundLocalError: локальная переменная 'CONFIG' ссылалась до присвоения. Операция присвоения в конце функции заставила компилятор Python считать CONFIG локальной переменной для всего тела функции. Таким образом, операция сравнения в начале использовала LOAD_FAST для доступа к неинициализированному слоту локальной переменной. Эта ошибка остановила обработку данных в критический момент работы, потому что функция не могла начать выполнение.
Команда сначала рассмотрела возможность переименовать локальную переопределенную переменную в local_config, создав новый словарь для уменьшенной обработки партии. Это полностью избегало бы проблемы затенения и сохраняло бы глобальную конфигурацию неизменной. Однако этот подход требовал бы рефакторинга последующего кода, который ожидал, что имя CONFIG будет отражать текущие ограничения. Это вводило потенциальные несоответствия, если разработчик забыл использовать новое имя переменной в последующей логике. Когнитивная нагрузка отслеживания двух имен переменных для одной концепции делала это решение менее привлекательным.
Другим вариантом было бы добавить global CONFIG в начале функции, принуждая компилятор считать все ссылки глобальными. Хотя это предотвратило бы ошибку, команда отвергла это, так как изменение глобального состояния во время обработки партии является опасным антипаттерном. Это мешает повторному входу функции и значительно усложняет юнит-тестирование. Кроме того, это создало бы гонки условий, если код когда-либо был бы распараллелен по потокам. Побочные эффекты на уровне состояния модуля были признаны неприемлемыми для производственных пайплайнов данных.
Третье решение заключалось в изменении существующего словаря на месте с помощью CONFIG["batch_size"] = 500, а не переназначения самого имени переменной. Так как эта операция не создает новое связывание для имени CONFIG, компилятор продолжает считать его глобальной ссылкой. Это позволяет избежать UnboundLocalError при сохранении возможности обновления конфигурации для последующих вызовов. Это решение показалось лучшим с точки зрения быстроты, хотя команда планировала позже рефакторить конфигурацию в объект класса. Подход изменения сохранял существующий API, одновременно устраняя немедленное падение.
Они внедрили третье решение, заменив переопределение на мутацию CONFIG["batch_size"] = 500. Пайплайн продолжил выполнение без ошибок, и изменение конфигурации было правильно применено к последующим партиям. Позже они рефакторили код для использования объекта настроек Pydantic, который был инъектирован в функцию. Это полностью устранило зависимость от глобальных переменных на уровне модуля и сделало функцию чистой и тестируемой. Этот инцидент побудил провести код-ревью всех операторов Airflow, чтобы устранить аналогичные шаблоны затенения.
Почему оператор del переменной внутри функции, за которым следует попытка чтения, вызывает UnboundLocalError, а не возвращается к глобальной области видимости?
Когда вы выполняете del x для локальной переменной, это удаляет ссылку из f_locals кадра, но не меняет статическую классификацию x как локальную. Компилятор все еще генерирует LOAD_FAST для последующих чтений. Когда интерпретатор выполняет LOAD_FAST, он находит слот пустым и вызывает UnboundLocalError, а не возвращается к глобальным переменным. Это подтверждает, что решения области видимости неизменяемы во время выполнения. Чтобы получить доступ к глобальному x после удаления, вы должны объявить global x на этапе компиляции.
Как стандартные выражения аргументов предотвращают ловушку UnboundLocalError, и что это раскрывает о времени их оценки?
Стандартные аргументы оцениваются один раз, когда выполняется определение функции в окружающей области, а не внутри локальной области функции. Если вы пишете def f(val=CONFIG["key"]):, Python использует LOAD_GLOBAL, чтобы разрешить CONFIG во время определения. Даже если тело функции позже присваивает CONFIG, делая его локальным, значение по умолчанию уже было захвачено безопасно. Это показывает, что значения по умолчанию используют глобальную область на этапе определения, отдельно от локального выполнения в теле функции. Таким образом, значения по умолчанию избегают UnboundLocalError, которая возникла бы, если бы такой доступ произошел внутри тела функции до присвоения.
Почему UnboundLocalError никогда не возникает в теле классов, и какое различие в байт-коде это позволяет?
Тела классов используют LOAD_NAME вместо LOAD_FAST для доступа к переменным. LOAD_NAME выполняет динамический поиск в словаре класса, затем в глобальном словаре, затем в встроенных. Он не использует предварительно выделенный фиксированный слот, поэтому никогда не сталкивается с состоянием "необъязанной локальной переменной". Если имя ссылается до присвоения в теле класса, LOAD_NAME просто продолжает искать его в глобальной области. Этот подход, основанный на словаре, жертвует скоростью локальных функций ради гибкости, необходимой в процессе построения класса.