В прошлом уроке функции научились создаваться через def, принимать аргументы и возвращать результат. Теперь наступает момент, когда у почти каждого новичка возникает один и тот же недоуменный вопрос: что случится, если внутри функции и снаружи окажутся переменные с одинаковым именем? Python в такой ситуации не путается ни на секунду, потому что у каждой переменной есть своя область видимости, то есть территория, на которой имя живёт и остаётся видимым для кода. Понять эту территорию стоит заранее, потому что конфликт имён способен испортить вечер, а казаться он будет загадочной ошибкой без причины. Во второй половине урока речь пойдёт о гибких аргументах: именованных вызовах, значениях по умолчанию, знаменитой ловушке с изменяемым значением по умолчанию и универсальных параметрах args и kwargs, благодаря которым одна функция обслуживает десятки разных сценариев.

Локальные переменные живут внутри функции

Переменная, созданная внутри функции, называется локальной. Она рождается в момент выполнения строки и исчезает, когда функция завершает работу. Снаружи её не существует, и попытка обратиться к ней из основного кода приводит к ошибке NameError.

def calc_total(price, count):
    total = price * count
    return total

result = calc_total(250, 3)
print(result)     # 750
print(total)      # NameError: name 'total' is not defined

Переменная total появилась внутри calc_total, отработала своё дело и вместе с функцией ушла в никуда. Такой строгий механизм приносит ощутимую пользу: локальные имена не засоряют программу, и их можно спокойно переиспользовать в десятках функций. Пять разных функций могут хранить у себя переменную count, и каждая увидит своё значение, потому что физически это пять разных ячеек памяти. Именно поэтому крупные проекты не превращаются в свалку имён, хотя функций там сотни.

То же правило действует и на параметры. Аргументы price и count тоже локальные, они существуют только внутри вызова. Если функция изменит числовой параметр внутри себя, оригинал в вызывающем коде останется прежним, ведь туда попала копия значения.

Заодно полезно знать, как Python вообще находит имя. Поиск идёт по цепочке уровней: сначала среди локальных имён текущей функции, затем среди имён внешней функции, если функции вложены друг в друга, затем среди глобальных имён файла и в самом конце среди встроенных имён языка вроде print и len. Эта цепочка носит имя LEGB, по первым буквам уровней. Механизм объясняет и то, почему одно и то же слово в разных местах программы означает разные вещи, и то, почему локальное имя надёжно прячет глобальное.

Чтение глобальных переменных из функции

Переменные, созданные на верхнем уровне файла, называют глобальными. Их видно отовсюду, и функция свободно читает их без всяких дополнительных слов.

TAX_RATE = 0.2

def with_tax(amount):
    return amount * (1 + TAX_RATE)

print(with_tax(1000))    # 1200.0

Функция with_tax заглянула наружу, нашла глобальную константу TAX_RATE и использовала её в расчёте. Это удобный и безопасный приём: читать глобальные значения можно без ограничений, и константы в верхнем регистре для этого подходят отлично. Одна именованная константа в начале файла лучше, чем одно и то же число, раскиданное по коду, потому что при смене ставки налога правка делается ровно в одном месте.

Проблемы начинаются, когда глобальную переменную пытаются не читать, а переписывать. При обычном присваивании Python не изменяет глобальное имя, а молча создаёт новую локальную переменную с тем же именем.

counter = 0

def add_click():
    counter = counter + 1    # UnboundLocalError

add_click()

Функция собирается вычислить counter + 1 и записать результат в counter. Справа идёт чтение, слева присваивание, и по правилам языка присваивание делает имя локальным на всю функцию целиком. Читать локальную переменную до её создания нельзя, отсюда ошибка UnboundLocalError. Она ставит в тупик многих начинающих, потому что текст ошибки не намекает на настоящую причину, а код выглядит абсолютно логичным.

Ключевое слово global и его ловушки

Существует официальное лекарство от UnboundLocalError, и это слово global. Оно ставится внутри функции и объявляет, что присваивания относятся к глобальному имени.

counter = 0

def add_click():
    global counter
    counter += 1

add_click()
add_click()
print(counter)    # 2

Код работает, счётчик честно растёт, и у новичка появляется соблазн построить всю программу на глобальных переменных. Соблазн обманчив. Чем больше в проекте слов global, тем труднее понять, кто и когда изменил значение. Функция с глобальной записью перестаёт быть самостоятельной: её поведение зависит от состояния всей программы, а не от переданных аргументов. Проверить такую функцию отдельно тяжело, перенести в другой проект опасно, а гонку десятков функций за одну общую переменную отладчик за человека не разыграет.

Опытные разработчики придерживаются простого правила: функция получает данные через параметры и отдаёт результат через return, а любое состояние передаётся явно.

counter = 0

def add_click(counter):
    return counter + 1

counter = add_click(counter)
counter = add_click(counter)
print(counter)    # 2

Здесь нет скрытых связей. Видно, откуда приходит значение и куда уходит результат, а функцию легко проверить, подставив любые входные данные. Слово global в реальном коде встречается редко, и по большей части встреча с ним означает, что фрагмент дизайна стоит пересмотреть. Параметры и возвращаемое значение делают ту же работу надёжнее.

Именованные аргументы и значения по умолчанию

На вызов функции аргументы можно передавать не только по позиции, но и по имени. Такой способ называют именованными аргументами, и он делает код заметно понятнее.

def make_greeting(name, greeting, punctuation):
    return f"{greeting}, {name}{punctuation}"

text = make_greeting(name="Анна", greeting="Доброе утро", punctuation="!")
print(text)    # Доброе утро, Анна!

Именованный вызов снимает необходимость помнить порядок параметров и позволяет менять их местами без риска. Смешивать оба способа можно, но позиционные аргументы всегда идут первыми: запись make_greeting("Анна", greeting="Привет", punctuation="!") корректна, а именованный аргумент раньше позиционного Python не пропустит.

Значения по умолчанию добавляют параметрам запасной вариант. Если вызывающий код не передал значение, Python подставит то, что указано в сигнатуре.

def make_greeting(name, greeting="Привет", punctuation="."):
    return f"{greeting}, {name}{punctuation}"

print(make_greeting("Игорь"))                   # Привет, Игорь.
print(make_greeting("Игорь", punctuation="!"))  # Привет, Игорь!
print(make_greeting("Игорь", "Салют"))          # Салют, Игорь.

Благодаря умолчаниям одна функция обслуживает и самый простой вызов, и тонкую настройку, без дублирования кода и без десятка похожих функций с разными именами. Это один из тех приёмов, которые отличают аккуратный код от наспех написанного.

Ловушка изменяемого значения по умолчанию

Самая известная засада языка связана с тем, что значение по умолчанию вычисляется один раз, в момент создания функции, а не при каждом вызове. Для чисел и строк это незаметно, но изменяемые объекты вроде списков живут между вызовами и накапливают изменения.

def add_task(task, tasks=[]):
    tasks.append(task)
    return tasks

first = add_task("Купить хлеб")
print(first)             # ['Купить хлеб']

second = add_task("Позвонить маме")
print(second)            # ['Купить хлеб', 'Позвонить маме']
print(first is second)   # True

Кажется, будто в second попала только новая задача, а на деле это тот же список, в котором осталась задача из первого вызова. Список создался один раз, функция хранит его при себе между вызовами, и каждый append попадает в общую копилку. Новички тратят часы на отладку таких мест, потому что код читается логично, а ведёт себя коварно, и ошибка всплывает только после нескольких вызовов подряд.

Правильный приём выглядит скучновато, зато работает всегда. Значением по умолчанию ставят None, а список создают внутри функции:

def add_task(task, tasks=None):
    if tasks is None:
        tasks = []
    tasks.append(task)
    return tasks

first = add_task("Купить хлеб")
second = add_task("Позвонить маме")
print(first)     # ['Купить хлеб']
print(second)    # ['Позвонить маме']

Теперь каждый вызов получает собственный список, и сюрпризов не остаётся. Правило стоит запомнить с первого раза: изменяемые значения по умолчанию не использовать, None и проверка внутри функции спасают без исключений. Неизменяемые умолчания вроде чисел, строк и кортежей безопасны, потому что их невозможно изменить на месте.

Параметры args и kwargs для произвольного числа аргументов

Иногда заранее неизвестно, сколько аргументов придёт. Функция сложения должна уметь складывать и два числа, и пять, и ни одного. Для таких случаев в сигнатуре ставят параметр со звёздочкой, а Python собирает все лишние позиционные аргументы в кортеж.

def add_all(*args):
    total = 0
    for number in args:
        total += number
    return total

print(add_all(2, 3))             # 5
print(add_all(1, 2, 3, 4, 5))    # 15
print(add_all())                 # 0

Имя args не зарезервировано языком, оно закреплено соглашением, а важна именно звёздочка. Внутри функции args оказывается обычным кортежем, по которому можно ходить циклом, считать длину и индексировать элементы. Похожим образом устроена и знакомая функция print: она принимает сколько угодно значений и добавляет к ним настройки sep и end.

print(1, 2, 3, sep=" | ")    # 1 | 2 | 3

Двойная звёздочка собирает лишние именованные аргументы в словарь. Так функция принимает любые пометки, которых создатель заранее не предусмотрел:

def save_profile(name, **kwargs):
    print("Имя:", name)
    for key, value in kwargs.items():
        print(key, "=", value)

save_profile("Ольга", age=29, city="Казань", hobby="гитара")

Вывод покажет имя и три дополнительные пары. Словарь kwargs внутри функции ведёт себя как обычный словарь, с ним работают привычные методы items, keys и values. Такой приём часто используют для настроек: обязательные параметры идут в сигнатуру явно, а необязательные собираются пачкой и разбираются по ключам.

Порядок параметров в сигнатуре не произвольный, и запомнить его проще один раз:

  1. обычные позиционные параметры;
  2. параметры со значениями по умолчанию;
  3. параметр со звёздочкой для лишних позиционных аргументов;
  4. обязательные именованные параметры, которые пишутся после звёздочки;
  5. параметр с двумя звёздочками для лишних именованных аргументов.

После двойной звёздочки ни один обычный параметр стоять не может, интерпретатор сразу сообщит о синтаксической ошибке. Звёздочка сама по себе, без имени, тоже допустима, и она отделяет параметры, которые разрешено передавать только по имени.

Гибкая функция логирования событий на практике

Соберём изученное в один рабочий пример. Задача звучит житейски: программа записывает события в файл, но у каждого события свой набор деталей. Где-то важен пользователь, где-то длительность операции, где-то число повторов. Жёсткая сигнатура с фиксированными параметрами здесь обречена на постоянные переделки, а гибкая функция справляется без единого изменения.

import time

LOG_FILE = "events.log"

def log_event(message, level="INFO", **details):
    stamp = time.strftime("%Y-%m-%d %H:%M:%S")
    line = f"[{stamp}] [{level}] {message}"
    for key, value in details.items():
        line += f" | {key}={value}"
    with open(LOG_FILE, "a", encoding="utf-8") as f:
        f.write(line + "\n")
    return line

log_event("Старт программы")
log_event("Пользователь вошёл", level="AUTH", user="marina", attempts=1)
log_event("Медленный запрос", level="WARNING", path="/items", seconds=3.4)

Функция log_event принимает обязательное сообщение, уровень по умолчанию и любое число дополнительных деталей. Первый вызов записывает короткую строку, второй добавляет пользователя и число попыток, третий помечает медленный запрос. Уровень передан именованным аргументом, поэтому его невозможно перепутать с сообщением даже при беглом чтении. Глобальная константа LOG_FILE читается функцией без слова global, а записывать в неё через присваивание функция не собирается.

Пример объединяет все темы урока: локальные переменные stamp, line и f живут только внутри вызова, чтение глобальной константы безопасно, значение по умолчанию неизменяемое, а kwargs делает функцию пригодной для событий, которых автор не знал в момент написания. Именно так и появляется код, который не приходится переписывать после каждой новой идеи.

Остался финальный штрих: звёздочка при вызове разворачивает коллекцию в аргументы, и это зеркальное отражение сборки.

numbers = [4, 8, 15]
print(add_all(*numbers))    # 27

Список numbers разложился на три позиционных аргумента, и функция увидела те же числа, будто их перечислили вручную. Две звёздочки перед словарем при вызове работают так же для именованных аргументов, и данные из конфигурационного файла удобно превращаются в параметры функции.

Гибкие аргументы избавляют от ошибок при передаче данных, но не от ошибок внутри самих данных: пользователь способен передать вместо числа строку, а вместо словаря вообще ничего. Следующий урок посвящён обработке ошибок через try и except, и именно там функция научится переживать неудачные входные данные, не роняя всю программу целиком.