Встроенные функции

Интерпретатор Python содержит ряд встроенных функций и типов, которые всегда доступны. Здесь они перечислены в алфавитном порядке.

abs(x)

Возвращает абсолютное значение числа. Аргументом может быть целое число, число с плавающей точкой или объект, реализующий __abs__(). Если аргумент — комплексное число, возвращается его модуль.

aiter(async_iterable)

Возвращает асинхронный итератор для асинхронного итерируемого объекта. Эквивалентно вызову x.__aiter__().

Примечание: в отличие от iter(), у aiter() нет варианта с двумя аргументами.

Добавлено в версии 3.10.

all(iterable)

Возвращает True, если все элементы итерируемого объекта истинны (или если итерируемый объект пуст). Эквивалентно:

def all(iterable):
    for element in iterable:
        if not element:
            return False
    return True

awaitable anext(async_iterator)

ожидаемый объект anext(async_iterator, default)

При ожидании возвращает следующий элемент из указанного асинхронного итератора или default, если он указан и итератор исчерпан.

Это асинхронный вариант встроенной функции next(), который работает аналогичным образом.

Вызывает метод __anext__() объекта async_iterator, возвращая ожидаемый объект. При ожидании он возвращает следующее значение итератора. Если указан default, он возвращается, когда итератор исчерпан; в противном случае возникает исключение StopAsyncIteration.

Добавлено в версии 3.10.

any(iterable)

Возвращает True, если хотя бы один элемент итерируемого объекта истинен. Если итерируемый объект пуст, возвращает False. Эквивалентно:

def any(iterable):
    for element in iterable:
        if element:
            return True
    return False

ascii(object)

Подобно repr(), возвращает строку, содержащую печатное представление объекта, но экранирует символы не из ASCII в строке, возвращаемой функцией repr(), с помощью экранирования \x, \u или \U. В результате получается строка, похожая на ту, которую возвращает repr() в Python 2.

bin(x)

Преобразует целое число в двоичную строку с префиксом «0b». Результат является допустимым выражением Python. Если x не является объектом Python типа int, он должен определять метод __index__(), возвращающий целое число. Примеры:

>>> bin(3)
'0b11'
>>> bin(-10)
'-0b1010'

Если наличие префикса «0b» не имеет значения, можно использовать любой из следующих способов.

>>> format(14, '#b'), format(14, 'b')
('0b1110', '1110')
>>> f'{14:#b}', f'{14:b}'
('0b1110', '1110')

Дополнительные сведения см. также в разделе format().

class bool(object=False, /)

Возвращает логическое значение, то есть одно из True или False. Аргумент преобразуется с помощью стандартной процедуры проверки истинности. Если аргумент ложен или не указан, возвращается False; в противном случае возвращается True. Класс bool является подклассом int (см. Числовые типы — int, float, complex). Его нельзя наследовать дальше. Его единственные экземпляры — False и True (см. Логический тип — bool).

Изменено в версии 3.7: Теперь параметр доступен только по позиции.

breakpoint(*args, **kws)

Эта функция запускает отладчик в месте вызова. В частности, она вызывает sys.breakpointhook(), передавая ей напрямую args и kws. По умолчанию sys.breakpointhook() вызывает pdb.set_trace() без аргументов. В этом случае это просто удобная функция, позволяющая не импортировать явно pdb и не вводить столько кода для запуска отладчика. Однако sys.breakpointhook() можно назначить другую функцию, и breakpoint() будет автоматически вызывать её, позволяя запустить выбранный отладчик. Если sys.breakpointhook() недоступна, эта функция вызовет исключение RuntimeError.

По умолчанию поведение функции breakpoint() можно изменить с помощью переменной среды PYTHONBREAKPOINT. Сведения об использовании см. в разделе sys.breakpointhook().

Обратите внимание, что это не гарантируется, если sys.breakpointhook() была заменена.

Вызывает событие аудита builtins.breakpoint с аргументом breakpointhook.

Добавлено в версии 3.7.

class bytearray(source=b'')

class bytearray(source, encoding)

class bytearray(source, encoding, errors)

Возвращает новый массив байтов. Класс bytearray представляет собой изменяемую последовательность целых чисел в диапазоне 0 <= x < 256. Он поддерживает большинство обычных методов изменяемых последовательностей, описанных в разделе Типы изменяемых последовательностей, а также большинство методов типа bytes; см. Операции с bytes и bytearray.

Необязательный параметр source можно использовать для инициализации массива несколькими способами:

• Если это строка, необходимо также указать параметры encoding и, необязательно, errors; функция bytearray() преобразует строку в байты с помощью str.encode().
• Если это целое число, массив будет иметь указанный размер и будет заполнен нулевыми байтами.
• Если это объект, соответствующий буферному интерфейсу, для инициализации массива байтов будет использоваться буфер объекта, доступный только для чтения.
• Если это итерируемый объект, он должен содержать целые числа в диапазоне 0 <= x < 256, которые будут использованы в качестве начального содержимого массива.

Если аргумент не указан, создаётся массив размером 0.

См. также Бинарные последовательности — bytes, bytearray, memoryview и Объекты bytearray.

class bytes(source=b'')

class bytes(source, encoding)

class bytes(source, encoding, errors)

Возвращает новый объект «bytes», представляющий собой неизменяемую последовательность целых чисел в диапазоне 0 <= x < 256. bytes — это неизменяемая версия bytearray: у неё те же методы, не изменяющие объект, а также те же правила индексирования и срезов.

Соответственно, аргументы конструктора интерпретируются так же, как для bytearray().

Объекты bytes также можно создавать с помощью литералов; см. Строковые и байтовые литералы.

См. также Бинарные последовательности — bytes, bytearray, memoryview, Объекты bytes и Операции с bytes и bytearray.

callable(object)

Возвращает True, если аргумент object выглядит вызываемым, и False в противном случае. Если возвращается True, вызов всё ещё может завершиться ошибкой, но если возвращается False, вызов object никогда не завершится успешно. Обратите внимание, что классы являются вызываемыми (вызов класса возвращает новый экземпляр); экземпляры являются вызываемыми, если их класс имеет метод __call__().

Добавлено в версии 3.2: Эта функция сначала была удалена в Python 3.0, а затем возвращена в Python 3.2.

chr(i)

Возвращает строку, представляющую символ, кодовая точка Unicode которого равна целому числу i. Например, chr(97) возвращает строку 'a', а chr(8364) возвращает строку '€'. Эта функция обратна функции ord().

Допустимый диапазон аргумента — от 0 до 1 114 111 (0x10FFFF в шестнадцатеричной системе). Если i выходит за пределы этого диапазона, возникает исключение ValueError.

@classmethod

Преобразует метод в метод класса.

Метод класса получает класс в качестве неявного первого аргумента, так же как метод экземпляра получает экземпляр. Для объявления метода класса используйте следующий шаблон:

class C:
    @classmethod
    def f(cls, arg1, arg2): ...

Форма @classmethod — это функция-декоратор; подробности см. в разделе Определения функций.

Метод класса можно вызвать как для класса (например, C.f()), так и для экземпляра (например, C().f()). Экземпляр игнорируется, используется только его класс. Если метод класса вызывается для производного класса, объект производного класса передаётся как неявный первый аргумент.

Методы класса отличаются от статических методов в C++ или Java. Если нужны именно такие методы, см. staticmethod() в этом разделе. Дополнительные сведения о методах класса см. в разделе Стандартная иерархия типов.

Изменено в версии 3.9: Теперь методы класса могут оборачивать другие дескрипторы, например property().

Изменено в версии 3.10: Теперь методы класса наследуют атрибуты метода (__module__, __name__, __qualname__, __doc__ и __annotations__) и имеют новый атрибут __wrapped__.

Изменено в версии 3.11: Методы класса больше не могут оборачивать другие дескрипторы, например property().

compile(source, filename, mode, flags=0, dont_inherit=False, optimize=-1)

Компилирует source в объект кода или AST. Объекты кода можно выполнять с помощью exec() или eval(). source может быть обычной строкой, байтовой строкой или объектом AST. Сведения о работе с объектами AST см. в документации модуля ast.

Аргумент filename должен указывать файл, из которого был прочитан код; если код был прочитан не из файла, передайте какое-нибудь узнаваемое значение (обычно используется '<string>').

Аргумент mode указывает, какой код необходимо скомпилировать: 'exec', если source состоит из последовательности инструкций; 'eval', если он состоит из одного выражения; или 'single', если он состоит из одной интерактивной инструкции (в последнем случае будут выведены инструкции-выражения, результатом которых является значение, отличное от None).

Необязательные аргументы flags и dont_inherit управляют тем, какие параметры компилятора следует включить и какие будущие возможности разрешить. Если ни один из аргументов не указан (или оба равны нулю), код компилируется с теми же флагами, которые влияют на вызывающий функцию compile() код. Если указан аргумент flags, а dont_inherit не указан (или равен нулю), параметры компилятора и инструкции future, заданные аргументом flags, используются в дополнение к тем, которые применялись бы в любом случае. Если dont_inherit — ненулевое целое число, аргумент flags используется как есть: флаги (будущие возможности и параметры компилятора) окружающего кода игнорируются.

Параметры компилятора и инструкции future задаются битами, которые можно объединять побитовой операцией ИЛИ для указания нескольких параметров. Битовую маску для указания определённой будущей возможности можно найти в атрибуте compiler_flag экземпляра _Feature в модуле __future__. Флаги компилятора можно найти в модуле ast; они имеют префикс PyCF_.

Аргумент optimize задаёт уровень оптимизации компилятора; значение по умолчанию -1 выбирает уровень оптимизации интерпретатора, заданный параметрами -O. Явно можно указать уровни 0 (без оптимизации; __debug__ имеет значение True), 1 (инструкции assert удаляются, __debug__ имеет значение False) или 2 (кроме того, удаляются строки документации).

Эта функция вызывает исключение SyntaxError, если исходный код некорректен, и ValueError, если исходный код содержит нулевые байты.

Чтобы разобрать код Python и получить его представление в виде AST, см. ast.parse().

Вызывает событие аудита compile с аргументами source и filename. Это событие также может возникнуть при неявной компиляции.

Примечание

При компиляции строки с многострочным кодом в режиме 'single' или 'eval' ввод должен завершаться как минимум одним символом новой строки. Это необходимо для обнаружения незавершённых и завершённых инструкций в модуле code.

Предупреждение

Интерпретатор Python может аварийно завершиться при компиляции достаточно большой или сложной строки в объект AST из-за ограничений глубины стека в компиляторе AST Python.

Изменено в версии 3.2: Разрешено использовать переводы строк Windows и Mac. Кроме того, ввод в режиме 'exec' больше не обязан завершаться символом новой строки. Добавлен параметр optimize.

Изменено в версии 3.5: Ранее при обнаружении нулевых байтов в source возникало исключение TypeError.

Добавлено в версии 3.8: Теперь для включения поддержки ast.PyCF_ALLOW_TOP_LEVEL_AWAIT на верхнем уровне в аргумент flags можно передать await, async for и async with.

class complex(number=0, /)

class complex(string, /)

class complex(real=0, imag=0)

Преобразует строку или число в комплексное число либо создаёт комплексное число из действительной и мнимой частей.

Примеры:

>>> complex('+1.23')
(1.23+0j)
>>> complex('-4.5j')
-4.5j
>>> complex('-1.23+4.5j')
(-1.23+4.5j)
>>> complex('\t( -1.23+4.5J )\n')
(-1.23+4.5j)
>>> complex('-Infinity+NaNj')
(-inf+nanj)
>>> complex(1.23)
(1.23+0j)
>>> complex(imag=-4.5)
-4.5j
>>> complex(-1.23, 4.5)
(-1.23+4.5j)

Если аргумент — строка, она должна содержать либо действительную часть (в том же формате, что и для float()), либо мнимую часть (в том же формате, но с суффиксом 'j' или 'J'), либо обе части (в этом случае знак мнимой части обязателен). Строка может быть окружена пробельными символами и круглыми скобками '(' и ')', которые игнорируются. Между '+', '-', суффиксом 'j' или 'J' и десятичным числом не должно быть пробелов. Например, complex('1+2j') допустимо, а complex('1 + 2j') вызывает исключение ValueError. Точнее, после удаления скобок и начальных и конечных пробельных символов ввод должен соответствовать правилу продукции complexvalue в следующей грамматике:

complexvalue ::= floatvalue |
                 floatvalue ("j" | "J") |
                 floatvalue sign absfloatvalue ("j" | "J")

Если аргумент — число, конструктор выполняет числовое преобразование, как int и float. Для общего объекта Python x функция complex(x) делегирует вызов x.__complex__(). Если __complex__() не определён, используется __float__(). Если __float__() не определён, используется __index__().

Если указаны два аргумента или используются именованные аргументы, каждый аргумент может иметь любой числовой тип (включая комплексный). Если оба аргумента — действительные числа, возвращается комплексное число с действительной частью real и мнимой частью imag. Если оба аргумента — комплексные числа, возвращается комплексное число с действительной частью real.real-imag.imag и мнимой частью real.imag+imag.real. Если один из аргументов — действительное число, в приведённых выше выражениях используется только его действительная часть.

Если все аргументы не указаны, возвращается 0j.

Тип complex описан в разделе Числовые типы — int, float, complex.

Изменено в версии 3.6: Разрешена группировка цифр с помощью символов подчёркивания, как в литералах кода.

Изменено в версии 3.8: Если __complex__() и __float__() не определены, используется __index__().

delattr(object, name)

Эта функция родственна функции setattr(). Аргументы — объект и строка. Строка должна быть именем одного из атрибутов объекта. Функция удаляет указанный атрибут, если объект это допускает. Например, delattr(x, 'foobar') эквивалентно del x.foobar. name не обязательно должен быть идентификатором Python (см. setattr()).

class dict(**kwarg)

class dict(mapping, **kwarg)

class dict(iterable, **kwarg)

Создаёт новый словарь. Объект dict — это класс словарей. Документацию по этому классу см. в разделах dict и Типы отображений — dict.

О других контейнерах см. встроенные классы list, set и tuple, а также модуль collections.

dir()

dir(object)

Без аргументов возвращает список имён в текущей локальной области видимости. С аргументом пытается вернуть список допустимых атрибутов этого объекта.

Если у объекта есть метод с именем __dir__(), будет вызван этот метод, который должен вернуть список атрибутов. Это позволяет объектам с собственной реализацией функции __getattr__() или __getattribute__() настраивать способ, которым dir() сообщает об их атрибутах.

Если объект не предоставляет __dir__(), функция пытается собрать сведения об объекте из его атрибута __dict__, если он определён, и из объекта его типа. Полученный список не обязательно будет полным и может быть неточным, если у объекта есть собственный метод __getattr__().

Механизм dir() по умолчанию ведёт себя по-разному для разных типов объектов, поскольку пытается предоставить наиболее полезные, а не исчерпывающие сведения:

• Если объект является объектом модуля, список содержит имена атрибутов модуля.
• Если объект является объектом типа или класса, список содержит имена его атрибутов, а также атрибутов его базовых классов с рекурсивным обходом.
• В остальных случаях список содержит имена атрибутов объекта, имена атрибутов его класса, а также атрибутов базовых классов этого класса с рекурсивным обходом.

Полученный список сортируется по алфавиту. Например:

>>> import struct
>>> dir()   # show the names in the module namespace
['__builtins__', '__name__', 'struct']
>>> dir(struct)   # show the names in the struct module
['Struct', '__all__', '__builtins__', '__cached__', '__doc__', '__file__',
 '__initializing__', '__loader__', '__name__', '__package__',
 '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
 'unpack', 'unpack_from']
>>> class Shape:
...     def __dir__(self):
...         return ['area', 'perimeter', 'location']
...
>>> s = Shape()
>>> dir(s)
['area', 'location', 'perimeter']

Примечание

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

divmod(a, b)

Принимает два (не комплексных) числа в качестве аргументов и возвращает пару чисел — частное и остаток при целочисленном делении. Для операндов разных типов применяются правила бинарных арифметических операторов. Для целых чисел результат совпадает с (a // b, a % b). Для чисел с плавающей запятой результат равен (q, a % b), где q обычно равно math.floor(a / b), но может быть на 1 меньше этого значения. В любом случае q * b + a % b очень близко к a; если a % b не равно нулю, оно имеет тот же знак, что и b, и 0 <= abs(a % b) < abs(b).

enumerate(iterable, start=0)

Возвращает объект enumerate. iterable должен быть последовательностью, итератором или другим объектом, поддерживающим итерацию. Метод __next__() итератора, возвращённого функцией enumerate(), возвращает кортеж, содержащий счётчик (начиная с start, по умолчанию равного 0) и значения, полученные при итерации по iterable.

>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>> list(enumerate(seasons, start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]

Эквивалентно:

def enumerate(iterable, start=0):
    n = start
    for elem in iterable:
        yield n, elem
        n += 1

eval(expression, globals=None, locals=None)

Параметры:

• expression (str | объект кода) – Выражение Python.
• globals (dict | None) – Глобальное пространство имён (по умолчанию: None).
• locals (отображение | None) – Локальное пространство имён (по умолчанию: None).

Возвращает:

Результат вычисления выражения.

Вызывает исключения:

Синтаксические ошибки сообщаются как исключения.

Предупреждение

Эта функция выполняет произвольный код. Её вызов с данными, предоставленными пользователем, может привести к уязвимостям безопасности.

Аргумент expression анализируется и вычисляется как выражение Python (технически говоря, как список условий) с использованием словарей globals и locals в качестве глобального и локального пространств имён. Если словарь globals указан и не содержит значения для ключа __builtins__, под этим ключом помещается ссылка на словарь встроенного модуля builtins перед анализом expression. Таким образом, можно управлять доступными выполняемому коду встроенными именами, поместив собственный словарь __builtins__ в globals перед передачей его функции eval(). Если словарь locals не указан, по умолчанию используется словарь globals. Если не указаны оба словаря, выражение выполняется с глобальными и локальными пространствами имён среды, в которой вызывается eval(). Обратите внимание: eval() не имеет доступа к вложенным областям видимости (нелокальным переменным) внешней среды.

Пример:

>>> x = 1
>>> eval('x+1')
2

Эту функцию также можно использовать для выполнения произвольных объектов кода (например, созданных функцией compile()). В этом случае вместо строки передайте объект кода. Если объект кода скомпилирован с 'exec' в качестве аргумента mode, возвращаемым значением eval() будет None.

Подсказки: динамическое выполнение операторов поддерживается функцией exec(). Функции globals() и locals() возвращают текущие глобальный и локальный словари соответственно; их может быть полезно передавать для использования функциями eval() или exec().

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

См. ast.literal_eval() — функцию, которая безопасно вычисляет строки с выражениями, содержащими только литералы.

Вызывает событие аудита exec, передавая объект кода в качестве аргумента. Также могут вызываться события компиляции кода.

exec(object, globals=None, locals=None, /, *, closure=None)

Предупреждение

Эта функция выполняет произвольный код. Её вызов с данными, предоставленными пользователем, может привести к уязвимостям безопасности.

Эта функция поддерживает динамическое выполнение кода Python. object должен быть строкой или объектом кода. Если это строка, она анализируется как блок операторов Python, который затем выполняется (если не возникает синтаксическая ошибка). [1] Если это объект кода, он просто выполняется. Во всех случаях предполагается, что выполняемый код допустим в качестве файлового ввода (см. раздел Файловый ввод в справочном руководстве). Обратите внимание: операторы nonlocal, yield и return нельзя использовать вне определений функций, даже в контексте кода, переданного функции exec(). Возвращаемое значение — None.

Во всех случаях, если необязательные части не указаны, код выполняется в текущей области видимости. Если указан только globals, это должен быть словарь (а не подкласс словаря), который будет использоваться и для глобальных, и для локальных переменных. Если указаны globals и locals, они используются соответственно для глобальных и локальных переменных. Если указан, locals может быть любым объектом отображения. Помните, что на уровне модуля глобальные и локальные переменные находятся в одном словаре.

Примечание

Большинству пользователей следует просто передавать аргумент globals и никогда не передавать locals. Если функция exec получает два разных объекта в качестве globals и locals, код выполняется так, как если бы он находился внутри определения класса.

Если словарь globals не содержит значения для ключа __builtins__, под этим ключом помещается ссылка на словарь встроенного модуля builtins. Таким образом, можно управлять доступными выполняемому коду встроенными именами, поместив собственный словарь __builtins__ в globals перед передачей его функции exec().

Аргумент closure задаёт замыкание — кортеж переменных ячеек. Он допустим, только если object является объектом кода, содержащим свободные переменные. Длина кортежа должна в точности совпадать с количеством свободных переменных, на которые ссылается объект кода.

Вызывает событие аудита exec, передавая объект кода в качестве аргумента. Также могут вызываться события компиляции кода.

Примечание

Встроенные функции globals() и locals() возвращают текущие глобальный и локальный словари соответственно; их может быть полезно передавать для использования в качестве второго и третьего аргументов функции exec().

Примечание

Поведение locals по умолчанию описано ниже для функции locals(): не следует пытаться изменять словарь locals по умолчанию. Если необходимо увидеть влияние кода на locals после возврата функции exec(), передайте явный словарь locals.

Изменено в версии 3.11: Добавлен параметр closure.

filter(function, iterable)

Создаёт итератор из элементов iterable, для которых function истинна. iterable может быть последовательностью, контейнером, поддерживающим итерацию, или итератором. Если function равна None, предполагается тождественная функция, то есть удаляются все ложные элементы iterable.

Обратите внимание: filter(function, iterable) эквивалентна генераторному выражению (item for item in iterable if function(item)), если function не равна None, и (item for item in iterable if item), если function равна None.

См. itertools.filterfalse() — функцию, возвращающую элементы iterable, для которых function ложна.

class float(number=0.0, /)

class float(string, /)

Возвращает число с плавающей запятой, созданное из числа или строки.

Примеры:

>>> float('+1.23')
1.23
>>> float('   -12345\n')
-12345.0
>>> float('1e-003')
0.001
>>> float('+1E6')
1000000.0
>>> float('-Infinity')
-inf

Если аргумент является строкой, она должна содержать десятичное число, перед которым может стоять знак и вокруг которого могут быть пробелы. Допустимый знак — '+' или '-'; знак '+' не влияет на полученное значение. Аргумент также может быть строкой, представляющей NaN (не число), положительную или отрицательную бесконечность. Точнее, после удаления начальных и конечных пробельных символов входные данные должны соответствовать правилу продукции floatvalue в следующей грамматике:

sign          ::= "+" | "-"
infinity      ::= "Infinity" | "inf"
nan           ::= "nan"
digit         ::= <a Unicode decimal digit, i.e. characters in Unicode general category Nd>
digitpart     ::= digit (["_"] digit)*
number        ::= [digitpart] "." digitpart | digitpart ["."]
exponent      ::= ("e" | "E") [sign] digitpart
floatnumber   ::= number [exponent]
absfloatvalue ::= floatnumber | infinity | nan
floatvalue    ::= [sign] absfloatvalue

Регистр не имеет значения, поэтому, например, «inf», «Inf», «INFINITY» и «iNfINity» — допустимые варианты написания положительной бесконечности.

В противном случае, если аргумент является целым числом или числом с плавающей запятой, возвращается число с плавающей запятой с тем же значением (в пределах точности чисел с плавающей запятой Python). Если аргумент выходит за пределы диапазона чисел с плавающей запятой Python, возникает исключение OverflowError.

Для произвольного объекта Python x функция float(x) делегирует вызов x.__float__(). Если __float__() не определён, используется __index__().

Если аргумент не задан, возвращается 0.0.

Тип float описан в разделе Числовые типы — int, float, complex.

Изменено в версии 3.6: Разрешена группировка цифр с помощью символов подчёркивания, как в литералах кода.

Изменено в версии 3.7: Параметр теперь доступен только по позиции.

Изменено в версии 3.8: Если __float__() не определён, используется __index__().

format(value, format_spec='')

Преобразует value в «форматированное» представление, определяемое параметром format_spec. Интерпретация format_spec зависит от типа аргумента value; однако большинство встроенных типов использует стандартный синтаксис форматирования: Мини-язык спецификаций формата.

По умолчанию format_spec — пустая строка, которая обычно даёт тот же результат, что и вызов str(value).

Вызов format(value, format_spec) преобразуется в type(value).__format__(value, format_spec), что позволяет обойти словарь экземпляра при поиске метода __format__() для значения. Исключение TypeError возникает, если поиск метода доходит до object, а format_spec не пуст, либо если format_spec или возвращаемое значение не являются строками.

Изменено в версии 3.4: object().__format__(format_spec) вызывает исключение TypeError, если format_spec не является пустой строкой.

class frozenset(iterable=set())

Возвращает новый объект frozenset, при необходимости содержащий элементы из iterable. frozenset — встроенный класс. Документацию по этому классу см. в разделах frozenset и Типы множеств — set, frozenset.

О других контейнерах см. встроенные классы set, list, tuple и dict, а также модуль collections.

getattr(object, name)

getattr(object, name, default)

Возвращает значение именованного атрибута объекта object. name должен быть строкой. Если строка является именем одного из атрибутов объекта, результатом будет значение этого атрибута. Например, getattr(x, 'foobar') эквивалентно x.foobar. Если именованный атрибут не существует, возвращается default, если он задан; в противном случае возникает исключение AttributeError. name не обязательно должен быть идентификатором Python (см. setattr()).

Примечание

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

globals()

Возвращает словарь, реализующий пространство имён текущего модуля. Для кода внутри функций он задаётся при определении функции и остаётся неизменным независимо от того, где вызывается функция.

hasattr(object, name)

Аргументы — объект и строка. Результат равен True, если строка является именем одного из атрибутов объекта, и False — в противном случае. (Это реализовано вызовом getattr(object, name) и проверкой того, возникает ли исключение AttributeError.)

hash(object)

Возвращает хеш-значение объекта (если оно есть). Хеш-значения — целые числа. Они используются для быстрого сравнения ключей словаря при поиске в нём. Числовые значения, которые считаются равными, имеют одинаковое хеш-значение (даже если они относятся к разным типам, как в случае 1 и 1.0).

Примечание

Для объектов с собственными методами __hash__() обратите внимание: hash() усекает возвращаемое значение с учётом разрядности платформы.

help()

help(request)

Запускает встроенную справочную систему. (Эта функция предназначена для интерактивного использования.) Если аргумент не задан, интерактивная справочная система запускается в консоли интерпретатора. Если аргумент — строка, она используется для поиска модуля, функции, класса, метода, ключевого слова или раздела документации с таким именем, после чего в консоли выводится соответствующая справочная страница. Если аргументом является объект любого другого типа, создаётся справочная страница об этом объекте.

Обратите внимание: если при вызове help() в списке параметров функции появляется косая черта (/), это означает, что параметры перед ней доступны только по позиции. Подробнее см. ответ на часто задаваемый вопрос о параметрах, доступных только по позиции.

Эта функция добавляется во встроенное пространство имён модулем site.

Изменено в версии 3.4: Изменения в pydoc и inspect сделали отображаемые сигнатуры вызываемых объектов более полными и единообразными.

hex(x)

Преобразует целое число в строку, содержащую шестнадцатеричную запись в нижнем регистре с префиксом «0x». Если x не является объектом Python int, он должен определять метод __index__(), возвращающий целое число. Несколько примеров:

>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'

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

>>> '%#x' % 255, '%x' % 255, '%X' % 255
('0xff', 'ff', 'FF')
>>> format(255, '#x'), format(255, 'x'), format(255, 'X')
('0xff', 'ff', 'FF')
>>> f'{255:#x}', f'{255:x}', f'{255:X}'
('0xff', 'ff', 'FF')

Дополнительные сведения см. также в разделе format().

Преобразование шестнадцатеричной строки в целое число с основанием 16 описано также в разделе int().

Примечание

Чтобы получить строковое шестнадцатеричное представление числа с плавающей запятой, используйте метод float.hex().

id(object)

Возвращает «идентичность» объекта. Это целое число, уникальность и неизменность которого гарантируются для данного объекта на протяжении всего срока его существования. Два объекта с непересекающимися сроками существования могут иметь одинаковое значение id().

Особенность реализации CPython: Это адрес объекта в памяти.

Вызывает событие аудита builtins.id с аргументом id.

input()

input(prompt)

Если задан аргумент prompt, он выводится в стандартный вывод без завершающего символа новой строки. Затем функция считывает строку из ввода, преобразует её в строку (удаляя завершающий символ новой строки) и возвращает результат. При чтении EOF возникает исключение EOFError. Пример:

>>> s = input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"

Если загружен модуль readline, функция input() будет использовать его для предоставления расширенных возможностей редактирования строк и работы с историей.

Перед чтением ввода возникает событие аудита builtins.input с аргументом prompt

После успешного чтения ввода возникает событие аудита builtins.input/result с результатом.

class int(number=0, /)

class int(string, /, base=10)

Возвращает объект-целое число, созданный из числа или строки, либо возвращает 0, если аргументы не заданы.

Примеры:

>>> int(123.45)
123
>>> int('123')
123
>>> int('   -12_345\n')
-12345
>>> int('FACE', 16)
64206
>>> int('0xface', 0)
64206
>>> int('01110011', base=2)
115

Если аргумент определяет __int__(), int(x) возвращает x.__int__(). Если аргумент определяет __index__(), возвращается x.__index__(). Если аргумент определяет __trunc__(), возвращается x.__trunc__(). Для чисел с плавающей точкой дробная часть отбрасывается в сторону нуля.

Если аргумент не является числом или задан параметр base, аргумент должен быть строкой, экземпляром bytes или bytearray, представляющим целое число в системе счисления с основанием base. Перед строкой может находиться + или - (без пробела между ними), она может содержать ведущие нули, пробелы по краям и одиночные символы подчёркивания между цифрами.

Строка целого числа в системе счисления с основанием n содержит цифры, каждая из которых представляет значение от 0 до n-1. Значения 0–9 можно представлять любыми десятичными цифрами Юникода. Значения 10–35 можно представлять символами от a до z (или от A до Z). По умолчанию base равен 10. Допустимые значения основания — 0 и числа от 2 до 36. Строки в двоичной, восьмеричной и шестнадцатеричной системах счисления могут иметь префиксы 0b/0B, 0o/0O или 0x/0X, как и целочисленные литералы в коде. При основании 0 строка интерпретируется подобно целочисленному литералу в коде: фактическое основание — 2, 8, 10 или 16 — определяется префиксом. При основании 0 также запрещены ведущие нули: int('010', 0) недопустимо, а int('010') и int('010', 8) допустимы.

Тип целых чисел описан в разделе Числовые типы — int, float, complex.

Изменено в версии 3.4: Если base не является экземпляром int, а объект base имеет метод base.__index__, этот метод вызывается для получения целого числа, задающего основание. В предыдущих версиях вместо base.__index__ использовался base.__int__.

Изменено в версии 3.6: Разрешена группировка цифр символами подчёркивания, как в литералах кода.

Изменено в версии 3.7: Первый параметр теперь является только позиционным.

Изменено в версии 3.8: Если __int__() не определён, используется __index__().

Изменено в версии 3.11: Использование __trunc__() объявлено устаревшим.

Изменено в версии 3.11: Количество цифр в строковых аргументах int и строковых представлениях можно ограничить, чтобы помочь предотвратить атаки типа «отказ в обслуживании». Если при преобразовании строки в int превышено ограничение или преобразование int в строку приведёт к превышению ограничения, возникает исключение ValueError. См. документацию об ограничении длины при преобразовании целых чисел в строки.

isinstance(object, classinfo)

Возвращает True, если аргумент object является экземпляром типа, заданного аргументом classinfo, или его прямого, косвенного либо виртуального подкласса. Если object не является объектом указанного типа, функция всегда возвращает False. Если classinfo — это кортеж объектов-типов (или, рекурсивно, других таких кортежей) либо объединение типов, возвращается True, если object является экземпляром любого из этих типов. Если classinfo не является типом, кортежем типов или кортежем таких кортежей, возникает исключение TypeError. Исключение TypeError может не возникнуть при недопустимом типе, если предыдущая проверка завершилась успешно.

Изменено в версии 3.10: classinfo может быть объединением типов.

issubclass(class, classinfo)

Возвращает True, если class является прямым, косвенным или виртуальным подклассом classinfo. Класс считается подклассом самого себя. classinfo может быть кортежем объектов-классов (или, рекурсивно, других таких кортежей) либо объединением типов; в этом случае возвращается True, если class является подклассом любого элемента classinfo. Во всех остальных случаях возникает исключение TypeError.

Изменено в версии 3.10: classinfo может быть объединением типов.

iter(object)

iter(object, sentinel)

Возвращает объект-итератор. Первый аргумент интерпретируется совершенно по-разному в зависимости от наличия второго аргумента. Если второй аргумент не указан, object должен быть объектом-контейнером, поддерживающим протокол итерируемого объекта (метод __iter__()), либо поддерживать протокол последовательности (метод __getitem__() с целочисленными аргументами, начиная с 0). Если объект не поддерживает ни один из этих протоколов, возникает исключение TypeError. Если задан второй аргумент, sentinel, то object должен быть вызываемым объектом. Созданный в этом случае итератор при каждом вызове своего метода __next__() вызывает object без аргументов; если возвращаемое значение равно sentinel, возникает исключение StopIteration, в противном случае возвращается это значение.

См. также раздел Типы итераторов.

Одно из полезных применений второй формы iter() — создание средства для чтения блоков. Например, чтение блоков фиксированной ширины из двоичного файла базы данных до достижения конца файла:

from functools import partial
with open('mydata.db', 'rb') as f:
    for block in iter(partial(f.read, 64), b''):
        process_block(block)

len(s)

Возвращает длину объекта (количество элементов). Аргументом может быть последовательность (например, строка, bytes, кортеж, список или range) или контейнер (например, словарь, множество или неизменяемое множество).

Особенность реализации CPython: len вызывает исключение OverflowError для объектов длиной больше sys.maxsize, например range(2 ** 100).

class list

class list(iterable)

list — не функция, а изменяемый тип последовательности, описанный в разделах Списки и Типы последовательностей — list, tuple, range.

locals()

Обновляет и возвращает словарь, представляющий текущую таблицу локальных символов. Свободные переменные возвращаются функцией locals(), когда она вызывается в блоках функций, но не в блоках классов. Обратите внимание, что на уровне модуля locals() и globals() возвращают один и тот же словарь.

Примечание

Не следует изменять содержимое этого словаря: изменения могут не повлиять на значения локальных и свободных переменных, используемых интерпретатором.

map(function, iterable, *iterables)

Возвращает итератор, который применяет function к каждому элементу iterable, выдавая результаты. Если переданы дополнительные аргументы iterables, функция function должна принимать соответствующее количество аргументов и применяется к элементам всех итерируемых объектов параллельно. При нескольких итерируемых объектах итератор останавливается, когда исчерпан самый короткий из них. Если аргументы функции уже сгруппированы в кортежи аргументов, см. itertools.starmap().

max(iterable, *, key=None)

max(iterable, *, default, key=None)

max(arg1, arg2, *args, key=None)

Возвращает наибольший элемент итерируемого объекта или наибольший из двух или более аргументов.

Если передан один позиционный аргумент, он должен быть итерируемым объектом. Возвращается наибольший элемент этого объекта. Если переданы два или более позиционных аргумента, возвращается наибольший из них.

Есть два необязательных аргумента, доступных только по ключевому слову. Аргумент key задаёт функцию упорядочивания с одним аргументом, подобную той, что используется в list.sort(). Аргумент default задаёт объект, возвращаемый, если переданный итерируемый объект пуст. Если итерируемый объект пуст и default не задан, возникает исключение ValueError.

Если наибольшими являются несколько элементов, функция возвращает первый встретившийся. Это согласуется с другими инструментами, сохраняющими стабильность сортировки, такими как sorted(iterable, key=keyfunc, reverse=True)[0] и heapq.nlargest(1, iterable, key=keyfunc).

Изменено в версии 3.4: Добавлен параметр default, доступный только по ключевому слову.

Изменено в версии 3.8: Значением key может быть None.

class memoryview(object)

Возвращает объект «представление памяти», созданный из заданного аргумента. Дополнительные сведения см. в разделе Представления памяти.

min(iterable, *, key=None)

min(iterable, *, default, key=None)

min(arg1, arg2, *args, key=None)

Возвращает наименьший элемент итерируемого объекта или наименьший из двух или более аргументов.

Если передан один позиционный аргумент, он должен быть итерируемым объектом. Возвращается наименьший элемент этого объекта. Если переданы два или более позиционных аргумента, возвращается наименьший из них.

Есть два необязательных аргумента, доступных только по ключевому слову. Аргумент key задаёт функцию упорядочивания с одним аргументом, подобную той, что используется в list.sort(). Аргумент default задаёт объект, возвращаемый, если переданный итерируемый объект пуст. Если итерируемый объект пуст и default не задан, возникает исключение ValueError.

Если наименьшими являются несколько элементов, функция возвращает первый встретившийся. Это согласуется с другими инструментами, сохраняющими стабильность сортировки, такими как sorted(iterable, key=keyfunc)[0] и heapq.nsmallest(1, iterable, key=keyfunc).

Изменено в версии 3.4: Добавлен параметр default, доступный только по ключевому слову.

Изменено в версии 3.8: Значением key может быть None.

next(iterator)

next(iterator, default)

Получает следующий элемент итератора, вызывая его метод __next__(). Если задан default, он возвращается при исчерпании итератора; в противном случае возникает исключение StopIteration.

class object

Это базовый класс для всех остальных классов. Он содержит методы, общие для всех экземпляров классов Python. При вызове конструктора возвращается новый объект без дополнительных возможностей. Конструктор не принимает аргументов.

Примечание

У экземпляров object нет атрибутов __dict__, поэтому экземпляру object нельзя назначать произвольные атрибуты.

oct(x)

Преобразует целое число в восьмеричную строку с префиксом «0o». Результат является допустимым выражением Python. Если x не является объектом int Python, он должен определять метод __index__(), возвращающий целое число. Например:

>>> oct(8)
'0o10'
>>> oct(-56)
'-0o70'

Чтобы преобразовать целое число в восьмеричную строку с префиксом «0o» или без него, можно воспользоваться одним из следующих способов.

>>> '%#o' % 10, '%o' % 10
('0o12', '12')
>>> format(10, '#o'), format(10, 'o')
('0o12', '12')
>>> f'{10:#o}', f'{10:o}'
('0o12', '12')

Дополнительные сведения см. также в разделе format().

open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)

Открывает file и возвращает соответствующий объект файла. Если файл не удаётся открыть, возникает исключение OSError. Дополнительные примеры использования этой функции см. в разделе Чтение и запись файлов.

file — это объект, подобный пути, задающий путь (абсолютный или относительно текущего рабочего каталога) к открываемому файлу, либо целочисленный файловый дескриптор файла, который нужно обернуть. (Если указан файловый дескриптор, он будет закрыт при закрытии возвращённого объекта ввода-вывода, если только для closefd не задано значение False.)

mode — необязательная строка, задающая режим открытия файла. По умолчанию используется 'r', то есть файл открывается для чтения в текстовом режиме. Другие распространённые значения: 'w' — для записи (с усечением файла, если он уже существует), 'x' — для исключительного создания и 'a' — для добавления в конец (в некоторых системах Unix это означает, что все операции записи добавляют данные в конец файла независимо от текущей позиции перемещения). В текстовом режиме, если параметр encoding не задан, используется зависящая от платформы кодировка: для получения кодировки текущей локали вызывается locale.getencoding(). (Для чтения и записи необработанных байтов используйте двоичный режим и не задавайте encoding.) Доступны следующие режимы:

Символ	Значение
'r'	открыть для чтения (по умолчанию)
'w'	открыть для записи, предварительно усечь файл
'x'	открыть для исключительного создания; завершиться ошибкой, если файл уже существует
'a'	открыть для записи, добавляя данные в конец файла, если он существует
'b'	двоичный режим
't'	текстовый режим (по умолчанию)
'+'	открыть для обновления (чтения и записи)

Режим по умолчанию — 'r' (открытие для чтения текста; синоним 'rt'). Режимы 'w+' и 'w+b' открывают файл и усекают его. Режимы 'r+' и 'r+b' открывают файл без усечения.

Как сказано в разделе Обзор, Python различает двоичный и текстовый ввод-вывод. Файлы, открытые в двоичном режиме (включая 'b' в аргументе mode), возвращают содержимое в виде объектов bytes без декодирования. В текстовом режиме (по умолчанию или если в аргументе mode указано 't') содержимое файла возвращается в виде str: байты предварительно декодируются с использованием зависящей от платформы кодировки или указанной кодировки encoding.

Примечание

Python не зависит от представлений базовой операционной системы о текстовых файлах; вся обработка выполняется самим Python и поэтому не зависит от платформы.

buffering — необязательное целое число, задающее политику буферизации. Передайте 0, чтобы отключить буферизацию (допускается только в двоичном режиме), 1 — чтобы включить построчную буферизацию (можно использовать только при записи в текстовом режиме), а целое число > 1 — чтобы задать размер буфера фиксированного размера в байтах. Обратите внимание: указание размера буфера таким способом применяется к буферизованному двоичному вводу-выводу, однако TextIOWrapper (то есть файлы, открытые с помощью mode='r+') используют другую буферизацию. Чтобы отключить буферизацию в TextIOWrapper, используйте флаг write_through для io.TextIOWrapper.reconfigure(). Если аргумент buffering не задан, применяется следующая политика буферизации по умолчанию:

• Двоичные файлы буферизуются блоками фиксированного размера; размер буфера выбирается эвристически, чтобы определить «размер блока» базового устройства, а если это не удаётся, используется io.DEFAULT_BUFFER_SIZE. Во многих системах размер буфера обычно составляет 4096 или 8192 байта.
• Для «интерактивных» текстовых файлов (файлов, для которых isatty() возвращает True) используется построчная буферизация. Для остальных текстовых файлов применяется описанная выше политика буферизации двоичных файлов.

encoding — название кодировки, используемой для декодирования или кодирования файла. Этот параметр следует использовать только в текстовом режиме. Кодировка по умолчанию зависит от платформы (используется значение, возвращаемое locale.getencoding()), однако можно использовать любую текстовую кодировку, поддерживаемую Python. Список поддерживаемых кодировок см. в модуле codecs.

errors — необязательная строка, задающая способ обработки ошибок кодирования и декодирования; её нельзя использовать в двоичном режиме. Доступны различные стандартные обработчики ошибок (перечислены в разделе Обработчики ошибок), однако также допустимо любое имя обработчика ошибок, зарегистрированное с помощью codecs.register_error(). Стандартные имена включают:

• 'strict' — вызывает исключение ValueError при ошибке кодирования. Значение None по умолчанию действует так же.
• 'ignore' игнорирует ошибки. Обратите внимание, что игнорирование ошибок кодирования может привести к потере данных.
• 'replace' вставляет маркер замены (например, '?') в место, где обнаружены некорректные данные.
• 'surrogateescape' представляет любые некорректные байты в виде единиц кода младших суррогатов в диапазоне от U+DC80 до U+DCFF. При записи данных эти единицы кода суррогатов преобразуются обратно в те же байты, если используется обработчик ошибок surrogateescape. Это полезно для обработки файлов с неизвестной кодировкой.
• 'xmlcharrefreplace' поддерживается только при записи в файл. Символы, не поддерживаемые кодировкой, заменяются соответствующей ссылкой на символ XML &#nnn;.
• 'backslashreplace' заменяет некорректные данные экранированными обратной косой чертой последовательностями Python.
• 'namereplace' (также поддерживается только при записи) заменяет неподдерживаемые символы экранированными последовательностями \N{...}.

newline определяет способ разбора символов новой строки в потоке. Допустимы значения None, '', '\n', '\r' и '\r\n'. Параметр работает следующим образом:

• При чтении входных данных из потока, если newline равен None, включается режим универсальных символов новой строки. Строки во входных данных могут заканчиваться символами '\n', '\r' или '\r\n'; перед возвратом вызывающему коду они преобразуются в '\n'. Если значение равно '', режим универсальных символов новой строки включается, но окончания строк возвращаются вызывающему коду без преобразования. При любом другом допустимом значении входные строки завершаются только указанной строкой, а окончание строки возвращается вызывающему коду без преобразования.
• При записи выходных данных в поток, если newline равен None, все записываемые символы '\n' преобразуются в стандартный для системы разделитель строк os.linesep. Если newline равен '' или '\n', преобразование не выполняется. При любом другом допустимом значении все записываемые символы '\n' преобразуются в указанную строку.

Если closefd равен False и вместо имени файла указан файловый дескриптор, при закрытии файла базовый файловый дескриптор останется открытым. Если указано имя файла, closefd должен иметь значение True (по умолчанию); в противном случае возникнет ошибка.

Пользовательскую функцию открытия можно передать в качестве вызываемого объекта opener. Тогда базовый файловый дескриптор объекта файла получается вызовом opener с аргументами (file, flags). opener должна возвращать открытый файловый дескриптор (передача os.open в качестве opener обеспечивает функциональность, аналогичную передаче None).

Созданный файл является не наследуемым.

В следующем примере параметр dir_fd функции os.open() используется для открытия файла относительно указанного каталога:

>>> import os
>>> dir_fd = os.open('somedir', os.O_RDONLY)
>>> def opener(path, flags):
...     return os.open(path, flags, dir_fd=dir_fd)
...
>>> with open('spamspam.txt', 'w', opener=opener) as f:
...     print('This will be written to somedir/spamspam.txt', file=f)
...
>>> os.close(dir_fd)  # don't leak a file descriptor

Тип возвращаемого функцией open() объекта файла зависит от режима. Если функция open() используется для открытия файла в текстовом режиме ('w', 'r', 'wt', 'rt' и т. д.), она возвращает подкласс io.TextIOBase (а именно io.TextIOWrapper). При открытии файла в двоичном режиме с буферизацией возвращаемый класс является подклассом io.BufferedIOBase. Конкретный класс зависит от режима: в двоичном режиме чтения возвращается io.BufferedReader; в двоичных режимах записи и добавления возвращается io.BufferedWriter, а в режиме чтения и записи — io.BufferedRandom. Если буферизация отключена, возвращается необработанный поток — подкласс io.RawIOBase, io.FileIO.

См. также модули для работы с файлами, например fileinput, io (где объявлена функция open()), os, os.path, tempfile и shutil.

Вызывает событие аудита open с аргументами path, mode, flags.

Аргументы mode и flags могли быть изменены или определены на основе исходного вызова.

Изменено в версии 3.3:

• Добавлен параметр opener.
• Добавлен режим 'x'.
• Ранее возникало исключение IOError; теперь это псевдоним OSError.
• Теперь, если файл, открываемый в режиме исключительного создания ('x'), уже существует, возникает исключение FileExistsError.

Изменено в версии 3.4:

• Теперь файл не наследуется.

Изменено в версии 3.5:

• Если системный вызов прерван, а обработчик сигнала не вызывает исключение, функция теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (обоснование см. в PEP 475).
• Добавлен обработчик ошибок 'namereplace'.

Изменено в версии 3.6:

• Добавлена поддержка объектов, реализующих os.PathLike.
• В Windows при открытии буфера консоли может возвращаться подкласс io.RawIOBase, отличный от io.FileIO.

Изменено в версии 3.11: Режим 'U' удалён.

ord(c)

Для строки, представляющей один символ Unicode, возвращает целое число — кодовую точку Unicode этого символа. Например, ord('a') возвращает целое число 97, а ord('€') (знак евро) возвращает 8364. Эта функция является обратной к chr().

pow(base, exp, mod=None)

Возвращает base в степени exp; если указан mod, возвращает base в степени exp по модулю mod (это вычисляется эффективнее, чем pow(base, exp) % mod). Форма с двумя аргументами pow(base, exp) эквивалентна использованию оператора возведения в степень: base**exp.

Аргументы должны иметь числовые типы. Если типы операндов различаются, применяются правила приведения типов для бинарных арифметических операторов. Для операндов типа int результат имеет тот же тип, что и операнды (после приведения), если только второй аргумент не является отрицательным; в этом случае все аргументы преобразуются в float, и результат также имеет тип float. Например, pow(10, 2) возвращает 100, а pow(10, -2) возвращает 0.01. Если основание отрицательное и имеет тип int или float, а показатель степени не является целым числом, результат имеет комплексный тип. Например, pow(-9, 0.5) возвращает значение, близкое к 3j. Если же отрицательное основание имеет тип int или float, а показатель степени является целым числом, результат имеет тип float. Например, pow(-9, 2.0) возвращает 81.0.

Если операнды base и exp имеют тип int и указан mod, он также должен иметь целочисленный тип и не быть равным нулю. Если указан mod, а exp отрицателен, base и mod должны быть взаимно простыми. В этом случае возвращается pow(inv_base, -exp, mod), где inv_base — обратное к base по модулю mod.

Пример вычисления обратного числа для 38 по модулю 97:

>>> pow(38, -1, mod=97)
23
>>> 23 * 38 % 97 == 1
True

Изменено в версии 3.8: Для операндов int трёхаргументная форма pow теперь допускает отрицательное значение второго аргумента, что позволяет вычислять обратные элементы по модулю.

Изменено в версии 3.8: Добавлена поддержка именованных аргументов. Ранее поддерживались только позиционные аргументы.

print(*objects, sep=' ', end='\n', file=None, flush=False)

Выводит objects в текстовый поток file, разделяя их строкой sep и завершая строкой end. Аргументы sep, end, file и flush, если они указаны, должны передаваться как именованные.

Все позиционные аргументы преобразуются в строки так же, как это делает str(), и записываются в поток, разделённые строкой sep и завершаемые строкой end. И sep, и end должны быть строками; также они могут быть равны None, что означает использование значений по умолчанию. Если аргумент objects не указан, print() просто запишет end.

Аргумент file должен быть объектом с методом write(string); если он не указан или равен None, будет использоваться sys.stdout. Поскольку выводимые аргументы преобразуются в текстовые строки, print() нельзя использовать с файловыми объектами в двоичном режиме. Для них используйте file.write(...).

Буферизация вывода обычно определяется аргументом file. Однако, если flush имеет истинное значение, поток принудительно сбрасывается.

Изменено в версии 3.3: Добавлен именованный аргумент flush.

class property(fget=None, fset=None, fdel=None, doc=None)

Возвращает атрибут-свойство.

fget — функция для получения значения атрибута. fset — функция для задания значения атрибута. fdel — функция для удаления значения атрибута. А doc задаёт строку документации атрибута.

Типичный пример использования — определение управляемого атрибута x:

class C:
    def __init__(self):
        self._x = None

    def getx(self):
        return self._x

    def setx(self, value):
        self._x = value

    def delx(self):
        del self._x

    x = property(getx, setx, delx, "I'm the 'x' property.")

Если c — экземпляр C, c.x вызывает геттер, c.x = value вызывает сеттер, а del c.x — удалитель.

Если указан параметр doc, он становится строкой документации атрибута-свойства. В противном случае свойство копирует строку документации fget (если она существует). Благодаря этому можно легко создавать свойства только для чтения, используя property() в качестве декоратора:

class Parrot:
    def __init__(self):
        self._voltage = 100000

    @property
    def voltage(self):
        """Get the current voltage."""
        return self._voltage

Декоратор @property превращает метод voltage() в «геттер» атрибута только для чтения с тем же именем и задаёт для voltage строку документации «Получить текущее напряжение».

@getter

@setter

@deleter

У объекта-свойства есть методы getter, setter и deleter, которые можно использовать как декораторы. Они создают копию свойства, назначая соответствующей функции доступа декорированную функцию. Лучше всего это пояснить на примере:

class C:
    def __init__(self):
        self._x = None

    @property
    def x(self):
        """I'm the 'x' property."""
        return self._x

    @x.setter
    def x(self, value):
        self._x = value

    @x.deleter
    def x(self):
        del self._x

Этот код полностью эквивалентен первому примеру. Не забудьте присвоить дополнительным функциям то же имя, что и исходному свойству (в данном случае x).

У возвращаемого объекта-свойства также есть атрибуты fget, fset и fdel, соответствующие аргументам конструктора.

Изменено в версии 3.5: Строки документации объектов-свойств теперь доступны для записи.

class range(stop)

class range(start, stop, step=1)

range — не функция, а неизменяемый тип последовательности, описанный в разделах Диапазоны и Типы последовательностей — list, tuple, range.

repr(object)

Возвращает строку, содержащую пригодное для печати представление объекта. Для многих типов эта функция пытается вернуть строку, которая при передаче в eval() создаст объект с тем же значением; в противном случае представление представляет собой строку в угловых скобках, содержащую имя типа объекта и дополнительные сведения, часто включая имя и адрес объекта. Класс может управлять тем, что эта функция возвращает для его экземпляров, определив метод __repr__(). Если sys.displayhook() недоступен, эта функция вызывает исключение RuntimeError.

У этого класса есть пользовательское представление, которое можно вычислить:

class Person:
   def __init__(self, name, age):
      self.name = name
      self.age = age

   def __repr__(self):
      return f"Person('{self.name}', {self.age})"

reversed(seq)

Возвращает обратный итератор. seq должен быть объектом, у которого есть метод __reversed__() или который поддерживает протокол последовательности (метод __len__() и метод __getitem__() с целочисленными аргументами, начинающимися с 0).

round(number, ndigits=None)

Возвращает number, округлённое до точности ndigits знаков после десятичной точки. Если ndigits не указан или равен None, возвращается ближайшее к входному значению целое число.

Для встроенных типов, поддерживающих round(), значения округляются до ближайшего кратного 10 в степени минус ndigits; если два таких числа равноудалены, округление выполняется в сторону чётного числа (так, например, и round(0.5), и round(-0.5) равны 0, а round(1.5) равно 2). Для ndigits допустимо любое целое число (положительное, ноль или отрицательное). Если ndigits не указан или равен None, возвращаемое значение является целым числом. В противном случае возвращаемое значение имеет тот же тип, что и number.

Для произвольного объекта Python number функция round делегирует вызов number.__round__.

Примечание

Поведение round() для чисел с плавающей точкой может удивить: например, round(2.675, 2) даёт 2.67 вместо ожидаемого 2.68. Это не ошибка: так проявляется тот факт, что большинство десятичных дробей нельзя точно представить в виде числа с плавающей точкой. Дополнительные сведения см. в разделе Арифметика с плавающей точкой: проблемы и ограничения.

class set

class set(iterable)

Возвращает новый объект set, необязательно включающий элементы из iterable. set — встроенный класс. Описание этого класса см. в разделах set и Типы множеств — set, frozenset.

Другие контейнеры представлены встроенными классами frozenset, list, tuple и dict, а также модулем collections.

setattr(object, name, value)

Это аналог getattr(). Аргументы — объект, строка и произвольное значение. Строка может задавать имя существующего атрибута или нового атрибута. Функция присваивает значение атрибуту, если объект это допускает. Например, setattr(x, 'foobar', 123) эквивалентно x.foobar = 123.

name не обязательно должно быть идентификатором Python, определённым в разделе Идентификаторы и ключевые слова, если только объект сам не требует этого, например в пользовательском методе __getattribute__() или с помощью __slots__. Атрибут, имя которого не является идентификатором, нельзя получить с помощью точечной нотации, но к нему можно обратиться через getattr() и т. д.

Примечание

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

class slice(stop)

class slice(start, stop, step=None)

Возвращает объект среза, представляющий набор индексов, заданный range(start, stop, step). По умолчанию аргументы start и step равны None.

start

stop

step

У объектов среза есть атрибуты данных только для чтения start, stop и step, которые просто возвращают значения аргументов (или их значения по умолчанию). Других явных функций у них нет, однако они используются NumPy и другими сторонними пакетами.

Объекты среза также создаются при использовании расширенного синтаксиса индексирования. Например: a[start:stop:step] или a[start:stop, i]. См. itertools.islice() — альтернативную версию, возвращающую итератор.

Изменено в версии 3.12: Объекты среза теперь хешируемы (если start, stop и step хешируемы).

sorted(iterable, /, *, key=None, reverse=False)

Возвращает новый отсортированный список из элементов iterable.

Принимает два необязательных аргумента, которые необходимо указывать как именованные.

key задаёт функцию с одним аргументом, используемую для извлечения ключа сравнения из каждого элемента iterable (например, key=str.lower). Значение по умолчанию — None (элементы сравниваются напрямую).

reverse — логическое значение. Если оно равно True, элементы списка сортируются так, как если бы каждое сравнение было обратным.

Используйте functools.cmp_to_key(), чтобы преобразовать функцию cmp старого типа в функцию key.

Встроенная функция sorted() гарантированно выполняет стабильную сортировку. Сортировка стабильна, если она гарантирует, что относительный порядок элементов, сравниваемых как равные, не изменится. Это полезно при сортировке в несколько проходов (например, сначала по отделу, затем по разряду заработной платы).

Алгоритм сортировки использует только сравнения < между элементами. Для сортировки достаточно определить метод __lt__(), однако PEP 8 рекомендует реализовать все шесть операторов сравнения. Это поможет избежать ошибок при использовании тех же данных с другими средствами упорядочивания, например max(), которые используют другой базовый метод. Реализация всех шести операторов сравнения также помогает избежать путаницы при сравнении значений разных типов, когда может вызываться отражённый метод __gt__().

Примеры сортировки и краткое руководство см. в разделе Методы сортировки.

@staticmethod

Преобразует метод в статический метод.

Статический метод не получает неявный первый аргумент. Чтобы объявить статический метод, используйте следующий идиоматический способ:

class C:
    @staticmethod
    def f(arg1, arg2, argN): ...

Форма @staticmethod представляет собой функцию декоратор — подробности см. в разделе Определения функций.

Статический метод можно вызвать как у класса (например, C.f()), так и у экземпляра (например, C().f()). Кроме того, дескриптор статического метода также является вызываемым, поэтому его можно использовать в определении класса (например, f()).

Статические методы в Python аналогичны статическим методам в Java или C++. См. также classmethod() — вариант, полезный для создания альтернативных конструкторов класса.

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

def regular_function():
    ...

class C:
    method = staticmethod(regular_function)

Дополнительные сведения о статических методах см. в разделе Стандартная иерархия типов.

Изменено в версии 3.10: Статические методы теперь наследуют атрибуты метода (__module__, __name__, __qualname__, __doc__ и __annotations__), имеют новый атрибут __wrapped__ и теперь вызываются как обычные функции.

class str(object='')

class str(object=b'', encoding='utf-8', errors='strict')

Возвращает str-представление объекта object. Подробности см. в разделе str().

str — встроенный строковый класс. Общие сведения о строках см. в разделе Текстовый тип последовательностей — str.

sum(iterable, /, start=0)

Суммирует start и элементы iterable слева направо и возвращает итоговое значение. Элементы iterable обычно являются числами, а начальное значение не может быть строкой.

В некоторых случаях лучше использовать альтернативы sum(). Предпочтительный и быстрый способ объединить последовательность строк — вызвать ''.join(sequence). Для сложения чисел с плавающей точкой с повышенной точностью см. math.fsum(). Чтобы объединить несколько итерируемых объектов, рассмотрите возможность использования itertools.chain().

Изменено в версии 3.8: Параметр start можно указывать как именованный аргумент.

Изменено в версии 3.12: Для суммирования чисел с плавающей точкой был выбран алгоритм, обеспечивающий более высокую точность в большинстве сборок.

class super

class super(type, object_or_type=None)

Возвращает прокси-объект, перенаправляющий вызовы методов родительскому или соседнему классу относительно type. Это полезно для доступа к унаследованным методам, переопределённым в классе.

Параметр object_or_type определяет порядок разрешения методов (MRO), в котором выполняется поиск. Поиск начинается с класса, следующего за type.

Например, если __mro__ объекта object_or_type равно D -> B -> C -> A -> object, а значение type — B, то super() выполняет поиск в C -> A -> object.

Атрибут __mro__ класса, соответствующего object_or_type, содержит порядок поиска методов, используемый как getattr(), так и super(). Этот атрибут является динамическим и может меняться при обновлении иерархии наследования.

Если второй аргумент опущен, возвращаемый объект super не связан с объектом. Если второй аргумент — объект, должно выполняться условие isinstance(obj, type). Если второй аргумент — тип, должно выполняться условие issubclass(type2, type) (это полезно для методов класса).

У super есть два типичных случая использования. В иерархии классов с одиночным наследованием super позволяет обращаться к родительским классам, не указывая их явно, что упрощает сопровождение кода. Такое использование во многом соответствует применению super в других языках программирования.

Второй случай использования — поддержка кооперативного множественного наследования в динамической среде выполнения. Этот случай характерен для Python и не встречается в статически компилируемых языках или языках, поддерживающих только одиночное наследование. Это позволяет реализовать «ромбовидные диаграммы», в которых несколько базовых классов реализуют один и тот же метод. Хороший дизайн требует, чтобы во всех таких случаях методы имели одинаковую сигнатуру вызова (поскольку порядок вызовов определяется во время выполнения, адаптируется к изменениям иерархии классов и может включать соседние классы, неизвестные до выполнения программы).

В обоих случаях типичный вызов метода суперкласса выглядит так:

class C(B):
    def method(self, arg):
        super().method(arg)    # This does the same thing as:
                               # super(C, self).method(arg)

Помимо поиска методов, super() также работает при поиске атрибутов. Один из возможных вариантов использования — вызов дескрипторов родительского или соседнего класса.

Обратите внимание, что super() реализован как часть процесса связывания при явном обращении к атрибутам через точку, например super().__getitem__(name). Он делает это, реализуя собственный метод __getattribute__() для поиска классов в предсказуемом порядке, поддерживающем кооперативное множественное наследование. Поэтому super() не определён для неявного поиска с помощью инструкций или операторов, например super()[name].

Также обратите внимание, что, за исключением формы без аргументов, super() можно использовать не только внутри методов. Форма с двумя аргументами явно задаёт аргументы и формирует соответствующие ссылки. Форма без аргументов работает только внутри определения класса: компилятор подставляет необходимые сведения, чтобы правильно получить определяемый класс и обратиться к текущему экземпляру в обычных методах.

Практические рекомендации по проектированию кооперативных классов с использованием super() см. в руководстве по использованию super().

class tuple

class tuple(iterable)

tuple — не функция, а неизменяемый тип последовательности, описанный в разделах Кортежи и Типы последовательностей — list, tuple, range.

class type(object)

class type(name, bases, dict, **kwds)

С одним аргументом возвращает тип объекта object. Возвращаемое значение является объектом типа и обычно совпадает с объектом, возвращаемым object.__class__.

Для проверки типа объекта рекомендуется использовать встроенную функцию isinstance(), поскольку она учитывает подклассы.

С тремя аргументами возвращает новый объект типа. По сути, это динамическая форма инструкции class. Строка name задаёт имя класса и становится атрибутом __name__. Кортеж bases содержит базовые классы и становится атрибутом __bases__; если он пуст, добавляется object — базовый класс всех классов. Словарь dict содержит определения атрибутов и методов для тела класса; он может быть скопирован или обёрнут перед тем, как стать атрибутом __dict__. Следующие две инструкции создают идентичные объекты type:

>>> class X:
...     a = 1
...
>>> X = type('X', (), dict(a=1))

См. также:

• Документация об атрибутах и методах классов.
• Объекты типов

Именованные аргументы, переданные в форму с тремя аргументами, передаются соответствующим механизмам метакласса (обычно __init_subclass__()) так же, как именованные аргументы в определении класса (за исключением metaclass).

См. также раздел Настройка создания классов.

Изменено в версии 3.6: Подклассы type, не переопределяющие type.__new__, больше не могут использовать форму с одним аргументом для получения типа объекта.

vars()

vars(object)

Возвращает атрибут __dict__ модуля, класса, экземпляра или любого другого объекта с атрибутом __dict__.

У таких объектов, как модули и экземпляры, атрибут __dict__ можно изменять; однако для других объектов запись в атрибуты __dict__ может быть ограничена (например, в классах используется types.MappingProxyType, чтобы запретить прямое изменение словаря).

Без аргумента vars() действует как locals(). Обратите внимание: словарь locals полезен только для чтения, поскольку изменения словаря locals игнорируются.

Если указан объект, у которого нет атрибута __dict__ (например, если в его классе определён атрибут __slots__), возникает исключение TypeError.

zip(*iterables, strict=False)

Параллельно перебирает несколько итерируемых объектов, создавая кортежи из элементов каждого из них.

Пример:

>>> for item in zip([1, 2, 3], ['sugar', 'spice', 'everything nice']):
...     print(item)
...
(1, 'sugar')
(2, 'spice')
(3, 'everything nice')

Формальнее говоря, zip() возвращает итератор кортежей, где i-й кортеж содержит i-й элемент каждого из переданных итерируемых объектов.

Можно также представить, что zip() преобразует строки в столбцы, а столбцы — в строки. Это похоже на транспонирование матрицы.

zip() работает лениво: элементы обрабатываются только при переборе итерируемого объекта, например в цикле for или после обёртывания в list.

Следует учитывать, что итерируемые объекты, переданные в zip(), могут иметь разную длину — иногда намеренно, а иногда из-за ошибки в коде, который их подготовил. Python предлагает три способа решения этой проблемы:

• По умолчанию zip() останавливается, когда заканчивается самый короткий итерируемый объект. Оставшиеся элементы более длинных объектов игнорируются, а результат обрезается до длины самого короткого объекта:

  >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum']))
  [(0, 'fee'), (1, 'fi'), (2, 'fo')]
  

• zip() часто используется, когда предполагается, что итерируемые объекты имеют одинаковую длину. В таких случаях рекомендуется использовать параметр strict=True. Результат будет таким же, как и у обычного zip():

  >>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
  [('a', 1), ('b', 2), ('c', 3)]
  

  В отличие от поведения по умолчанию, если один итерируемый объект заканчивается раньше остальных, возникает исключение ValueError:

  >>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True):
  ...     print(item)
  ...
  (0, 'fee')
  (1, 'fi')
  (2, 'fo')
  Traceback (most recent call last):
    ...
  ValueError: zip() argument 2 is longer than argument 1
  

  Без аргумента strict=True любая ошибка, приводящая к появлению итерируемых объектов разной длины, останется незамеченной и может проявиться как трудноуловимая ошибка в другой части программы.

• Более короткие итерируемые объекты можно дополнить постоянным значением, чтобы уравнять их длину. Это делает функция itertools.zip_longest().

Особые случаи: если передан один итерируемый аргумент, zip() возвращает итератор одноэлементных кортежей. Если аргументов нет, возвращается пустой итератор.

Советы и рекомендации:

• Порядок вычисления итерируемых объектов слева направо гарантирован. Это позволяет использовать идиоматический способ группировки набора данных в группы длиной n с помощью zip(*[iter(s)]*n, strict=True). Один и тот же итератор повторяется n раз, поэтому каждый выходной кортеж содержит результат n вызовов итератора. Таким образом, входные данные делятся на фрагменты длиной n.

• zip() вместе с оператором * можно использовать для распаковки списка:

  >>> x = [1, 2, 3]
  >>> y = [4, 5, 6]
  >>> list(zip(x, y))
  [(1, 4), (2, 5), (3, 6)]
  >>> x2, y2 = zip(*zip(x, y))
  >>> x == list(x2) and y == list(y2)
  True
  

Изменено в версии 3.10: Добавлен аргумент strict.

__import__(name, globals=None, locals=None, fromlist=(), level=0)

Примечание

Это расширенная функция, которая не требуется при повседневном программировании на Python, в отличие от importlib.import_module().

Эта функция вызывается оператором import. Её можно заменить (импортировав модуль builtins и присвоив значение builtins.__import__), чтобы изменить семантику оператора import, однако делать это крайне не рекомендуется: обычно проще добиться тех же целей с помощью хуков импорта (см. PEP 302), и это не вызывает проблем с кодом, который предполагает использование реализации импорта по умолчанию. Также не рекомендуется напрямую использовать __import__(); вместо этого следует использовать importlib.import_module().

Функция импортирует модуль name, при необходимости используя переданные значения globals и locals, чтобы определить, как интерпретировать имя в контексте пакета. В fromlist указываются имена объектов или подмодулей, которые следует импортировать из модуля, заданного аргументом name. Стандартная реализация вообще не использует аргумент locals, а аргумент globals использует только для определения контекста пакета оператора import.

Параметр level указывает, следует ли использовать абсолютный или относительный импорт. 0 (значение по умолчанию) означает, что выполняется только абсолютный импорт. Положительные значения level указывают количество родительских каталогов для поиска относительно каталога модуля, вызывающего __import__() (подробности см. в PEP 328).

Если переменная name имеет вид package.module, обычно возвращается пакет верхнего уровня (имя до первой точки), а не модуль, указанный в name. Однако, если передан непустой аргумент fromlist, возвращается модуль, указанный в name.

Например, оператор import spam приводит к байт-коду, похожему на следующий код:

spam = __import__('spam', globals(), locals(), [], 0)

Оператор import spam.ham приводит к следующему вызову:

spam = __import__('spam.ham', globals(), locals(), [], 0)

Обратите внимание, что здесь __import__() возвращает модуль верхнего уровня, поскольку именно этот объект привязывается к имени оператором import.

С другой стороны, оператор from spam.ham import eggs, sausage as saus приводит к следующему:

_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], 0)
eggs = _temp.eggs
saus = _temp.sausage

Здесь из __import__() возвращается модуль spam.ham. Из этого объекта извлекаются имена для импорта и присваиваются соответствующим именам.

Если нужно просто импортировать модуль (возможно, находящийся внутри пакета) по имени, используйте importlib.import_module().

Изменено в версии 3.3: Отрицательные значения level больше не поддерживаются (в связи с этим значение по умолчанию также изменено на 0).

Изменено в версии 3.9: При использовании параметров командной строки -E или -I переменная среды PYTHONCASEOK теперь игнорируется.

Сноски