def kinetic_energy(m, v):
    """Кинетическая энергия тела, Дж.
 
    m — масса, кг; v — скорость, м/с.
    """
    return m * v ** 2 / 2
 
kinetic_energy(2.0, 3.0)    # 9.0

Пояснение

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

Для физика

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

Важно

Аннотации не проверяются при выполнении: аргумент другого типа принимается, и TypeError, если возникнет, произойдёт в теле функции. Проверку выполняют анализаторы mypy и pyright.

01

Функция с аннотациями и документацией

02

Имя и строка документации

03

Аннотации в __annotations__

04

Второе имя для той же функции

05

Функции как значения словаря

06

Функция без return

07

Непроверяемая аннотация: area('2')

def kinetic_energy(m, v):
    """Кинетическая энергия тела.
 
    Parameters
    ----------
    m : float
        Масса, кг.
    v : float
        Скорость, м/с.
 
    Returns
    -------
    float
        Энергия, Дж.
 
    Examples
    --------
    >>> kinetic_energy(2.0, 3.0)
    9.0
    """

Пояснение

python3 -m doctest phys.py выполняет примеры из документации и сравнивает вывод: документация проверяется как тест.

Для физика

Формат NumPy принят в NumPy, SciPy и Astropy; Sphinx с расширением numpydoc собирает из него справочник.

01

Примеры в документации функции

02

doctest: обнаружение ошибки в формуле

03

Исправление формулы

04

Повторный запуск с -v без ошибок

def integrate(f, a, b, *, n=1000, tol=1e-8):
    ...
 
integrate(g, 0.0, 1.0, n=10_000)   # явно
integrate(g, 0.0, 1.0, 10_000)     # TypeError
 
def unique(xs, seen=None):
    seen = set() if seen is None else set(seen)
    ...

Важно

Значение по умолчанию вычисляется один раз, при выполнении def: изменяемый объект становится общим для всех вызовов. Вместо него указывается None.

Для физика

Настройки расчёта — число узлов, метод, допуск — объявляются только именованными: по вызову integrate(g, 0, 1, 1e-6, 100) не понять, где допуск, а где число узлов.

def min_of(first, *rest):
    res = first
    for x in rest:
        if x < res:
            res = x
    return res
 
min_of(-5, 12, 13)        # -5
min_of(*{-5, 12, 13})     # распаковка

def run(cmd, **options):
    if options.get('verbose', True):
        print('Logging enabled')
 
opts = {'verbose': False}
run('mysqld', **opts)

Пояснение

Звёздочка в объявлении собирает аргументы, в вызове — раскладывает коллекцию по параметрам. Обёртка def w(*args, **kwargs): return f(*args, **kwargs) передаёт любые аргументы без изменений.

01

Функция со всеми видами параметров

02

Вызов с минимумом аргументов

03

Лишние позиционные и именованные

04

Сигнатура через inspect.signature

05

Ошибки: лишний позиционный и позиционный по имени

06

Распаковка кортежа и словаря в вызове

first, *rest = range(1, 5)        # 1, [2, 3, 4]
first, *mid, last = 'физика'      # 'ф', [...], 'а'
(x1, y1), (x2, y2) = (0, 0), (4, 3)
for name, *values in rows:
    ...
 
points = [*old, *new]             # PEP 448
config = {**defaults, **user}

Пояснение

Имя со звёздочкой получает список, возможно пустой; обычным именам значений должно хватить: a, *b, c = [42] вызывает ValueError.

Для физика

Строка файла вида «время, канал, отсчёты…» разбирается одним присваиванием: t, ch, *counts = line.split().

01

Первый элемент и остаток

02

Первый, середина и последний

03

Вложенная распаковка координат

04

Недостаток значений: ValueError

05

Распаковка в литералах списка и словаря

Built-in: len, print, min, sum

Global: имена модуля

Enclosing: объемлющая функция

Local: сама функция

поиск идёт изнутри наружу до первого совпадения

min = 42               # global
 
def f(*args):
    min = 2            # enclosing
    def g():
        min = 4        # local
        print(min)
    g()

Важно

Переменная с именем встроенной функции закрывает её: после len = 5 вызов len('abc') завершается ошибкой.

count = 0
 
def bump():
    count += 1      # UnboundLocalError

Пояснение

Решение «локальная или нет» принимается при компиляции функции: присваивание где угодно в теле делает имя локальным во всём теле.

Для физика

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

01

Чтение имени объемлющей функции

02

Присваивание в функции: UnboundLocalError

03

Встроенная функция, закрытая глобальным именем

04

Встроенная len после del

def make_counter():
    count = 0
    def counter():
        nonlocal count
        count += 1
        return count
    return counter
 
c = make_counter()
c(), c(), c()         # (1, 2, 3)

make_counter завершилась, а count продолжает существовать в ячейке

Для физика

Фабрика make_gaussian(mu, sigma) возвращает функцию одной переменной x с закреплёнными параметрами, пригодную для интегрирования и построения графика.

funcs = [lambda: i for i in range(3)]
[f() for f in funcs]          # [2, 2, 2]
 
funcs = [lambda i=i: i for i in range(3)]
[f() for f in funcs]          # [0, 1, 2]
 
funcs = [partial(pow, 2, i) for i in range(3)]
[f() for f in funcs]          # [1, 2, 4]

Важно

Функция, созданная в цикле, захватывает переменную, а не её значение, и после цикла видит последнее значение.

Для физика

Список моделей или обработчиков для перебора параметров, созданный в цикле лямбдами, вычисляет всё с последним параметром без сообщения об ошибке.

01

Фабрика счётчиков с nonlocal

02

Три вызова одного счётчика

03

Значение в ячейке замыкания

04

Лямбды в цикле: позднее связывание

05

Фиксация значения параметром по умолчанию

lambda x: x ** 2
lambda a, *args, b=None, **kw: 42
 
sorted(events, key=lambda e: e.energy)
max(data, key=lambda p: p[0])

Пояснение

PEP 8 рекомендует def вместо присваивания лямбды имени: f = lambda x: ... ничем не лучше def f(x): ..., но в трассировке ошибки теряет имя.

[x ** 2 for x in range(10) if x % 2]
list(map(lambda x: x ** 2,
         filter(lambda x: x % 2, range(10))))
 
[x for xs in nested for x in xs]      # вложенные
{x % 7 for x in data}                 # множество
{k: v for k, v in date.items() if v}  # словарь

values = list(map(float, fields))
total = sum(x * x for x in data)

Пояснение

Включение читается проще комбинации map и filter с лямбдами; с готовой функцией короче запись через map: map(float, fields). Выражение-генератор в круглых скобках не строит список.

01

Сортировка записей: по первому элементу и по ключу

02

Максимум по ключу itemgetter

03

map — одноразовый итератор

04

filter(None, ...): только истинные

05

zip: обрезка по короткой последовательности

06

any и all по условию

total = 0.0
def add_sample(x):        # нечистая
    global total
    total += x
 
def mean(xs):             # чистая
    return sum(xs) / len(xs)

Для физика

Генератор случайных чисел передаётся в функцию моделирования аргументом: с тем же зерном default_rng(42) результат воспроизводится, хотя вызов меняет состояние генератора.

Важно

Лямбды, собранные в цикле и вызванные после него, получат последнее значение параметра; quad внутри той же итерации вычисляется верно.

Пояснение

Вызов функции Python добавил около 10 нс на элемент: 2,66 мс против 1,64 мс на 10⁵ чисел.

Для физика

Цикл по миллионам значений переносят во встроенные функции и NumPy: они выполняют цикл в скомпилированном коде. Подробно — в главе «Оптимизация средствами самого Python».

01

Подготовка: список и функция sq

02

Включение с выражением

03

Включение с вызовом функции

04

map с лямбдой

05

Явный цикл накопления

06

Встроенная sum

def trace(func):
    def inner(*args, **kwargs):
        print('вызов', func.__name__, args, kwargs)
        return func(*args, **kwargs)
    return inner
 
@trace
def area(r):
    return 3.14159 * r ** 2

Пояснение

func доступна внутри inner после завершения trace благодаря замыканию.

import functools
 
def trace(func):
    @functools.wraps(func)
    def inner(*args, **kwargs):
        print('вызов', func.__name__)
        return func(*args, **kwargs)
    return inner

Важно

Собственный декоратор всегда начинается с @functools.wraps(func) над внутренней функцией.

01

Декоратор trace без wraps

02

Декорированная функция area

03

Вызов: печать и результат

04

Имя функции после декорирования

05

Декоратор с functools.wraps

06

Имя после wraps и ссылка __wrapped__

def trace(handle):
    def decorator(func):
        @functools.wraps(func)
        def inner(*args, **kwargs):
            print(func.__name__, file=handle)
            return func(*args, **kwargs)
        return inner
    return decorator
 
@trace(sys.stderr)
def identity(x):
    return x

# @trace(sys.stderr) означает:
decorator = trace(sys.stderr)
identity = decorator(identity)
 
# @trace и @trace(handle=sys.stderr):
def trace(func=None, *, handle=sys.stdout):
    if func is None:
        return lambda f: trace(f, handle=handle)
    if not callable(func):
        raise TypeError('нужно trace(handle=...)')
    ...

Важно

Звёздочка не защищает от записи @trace(sys.stderr): файл попадает в параметр func, поэтому декоратор проверяет callable(func).

@deco1
@deco2
def foo(): ...
 
# применение снизу вверх:
foo = deco1(deco2(foo))

Пояснение

@lru_cache располагают выше проверок, чтобы попадание в кеш не тратило время на проверку; @timethis — ниже, чтобы измерять саму функцию.

01

Декоратор tag с аргументом

02

Два tag на одной функции

03

Вызов: порядок входа и выхода

def deprecated(func):
    @functools.wraps(func)
    def inner(*args, **kwargs):
        warnings.warn(f'{func.__name__} устарела',
                      DeprecationWarning, stacklevel=2)
        return func(*args, **kwargs)
    return inner

Пояснение

С Python 3.13 то же делает готовый декоратор warnings.deprecated (PEP 702).

01

Декоратор deprecated в модуле legacy.py

02

Вызов из сценария: предупреждение со строкой вызова

03

Предупреждение как ошибка: -W error

def pre(cond, message):
    def decorator(func):
        @functools.wraps(func)
        def inner(*args, **kwargs):
            assert cond(*args, **kwargs), message
            return func(*args, **kwargs)
        return inner
    return decorator
 
@pre(lambda x: 0 < x < 1, 'аргумент должен лежать в (0, 1)')
def log_fraction(x):
    return math.log(x)

Важно

Ключ -O удаляет assert из байт-кода: внешние данные проверяются явным raise ValueError.

Для физика

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

01

Функция с предусловием

02

Обычный запуск: AssertionError на 2.0

03

Запуск с -O без проверки

def depth(n):
    return 0 if n == 0 else 1 + depth(n - 1)
 
depth(900)       # 900
depth(5000)      # RecursionError
 
def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)

01

Предел глубины рекурсии

02

Рекурсия глубины 900

03

Глубина 5000: RecursionError

04

Тот же подсчёт циклом

from functools import lru_cache
 
@lru_cache(maxsize=None)
def fib(n):
    return n if n < 2 else fib(n - 1) + fib(n - 2)
 
fib(32)            # 2178309
fib.cache_info()

Для физика

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

Важно

Кеш с maxsize=None в долго работающей программе растёт неограниченно.

01

Рекурсивный fib без кеша: время fib(32)

02

Тот же fib с lru_cache

03

Статистика кеша

04

fib(400): однократное вычисление каждого значения

from functools import partial
 
int2 = partial(int, base=2)
int2('1010')          # 10
 
def planck(nu, T):
    ...
 
quad(partial(planck, T=5800.0), 1e14, 1e15)

Для физика

multiprocessing.Pool.map передаёт функцию в процессы через pickle: partial подходит, лямбда — нет; исходная функция — из импортируемого модуля.

from functools import singledispatch
 
@singledispatch
def describe(x):
    return 'объект'
 
@describe.register
def _(x: int):
    return 'целое'
 
@describe.register
def _(x: list):
    return f'список из {len(x)}'

Пояснение

Реализация выбирается по типу первого аргумента с учётом наследования: describe(True) даёт 'целое', поскольку bool — подкласс int.

Для физика

Функция обработки принимает число, список или массив и выбирает реализацию по типу входа без цепочки isinstance.

01

partial(int, base=2): двоичный разбор

02

Атрибуты func и keywords

03

singledispatch: реализации для int и list

04

Выбор по типу, включая bool

05

Свёртка reduce: 5!

Книга курса: главы «Функции» и «Декораторы и functools»

phys-dev.github.io/soft-dev-book

Лебедев С. Функции в Python. – Computer Science Center

youtube.com/watch?v=ZRZq2u0v6KI

Лебедев С. Декораторы. Модуль functools. – Computer Science Center

youtube.com/watch?v=qIDBMpy38O4

The Python Tutorial: More on Defining Functions

docs.python.org/3/tutorial/controlflow.html

Модуль functools — документация Python

docs.python.org/3/library/functools.html

PEP 318, 570, 3102, 3104, 448, 484 — декораторы, параметры, nonlocal, распаковка, типы

peps.python.org

Ramalho L. Fluent Python. – 2nd ed. – O'Reilly, 2022