modules.md
1> **Источник:** https://python-all.ru/3.0/tutorial/modules.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Модули89Если выйти из интерпретатора Python и войти в него снова, все созданные определения (функции и переменные) теряются. Поэтому для написания более длинной программы лучше использовать текстовый редактор для подготовки входных данных для интерпретатора и запускать его с этим файлом в качестве входных данных. Это называется созданием *скрипта*. По мере роста программы может потребоваться разбить её на несколько файлов для упрощения сопровождения. Также может пригодиться удобная функция, написанная для нескольких программ, без копирования её определения в каждую из них.1011Для поддержки этого в Python есть способ помещать определения в файл и использовать их в скрипте или в интерактивном сеансе интерпретатора. Такой файл называется *модулем*; определения из модуля можно *импортировать* в другие модули или в *главный* модуль (набор переменных, доступных в скрипте, выполняемом на верхнем уровне, и в режиме калькулятора).1213Модуль – это файл, содержащий определения и инструкции Python. Имя файла – это имя модуля с добавлением суффикса `.py`. Внутри модуля имя модуля (в виде строки) доступно как значение глобальной переменной `__name__`. Например, с помощью вашего любимого текстового редактора создайте файл с именем `fibo.py` в текущем каталоге со следующим содержимым:1415```python16# Модуль чисел Фибоначчи1718def fib(n): # вывести ряд Фибоначчи до n19 a, b = 0, 120 while b < n:21 print(b, end=' ')22 a, b = b, a+b23 print()2425def fib2(n): # возвращает ряд Фибоначчи до n26 result = []27 a, b = 0, 128 while b < n:29 result.append(b)30 a, b = b, a+b31 return result32```3334Теперь войдите в интерпретатор Python и импортируйте этот модуль с помощью следующей команды:3536```python37>>> import fibo38```3940Это не добавляет имена функций, определённых в `fibo`, непосредственно в текущую таблицу символов; оно добавляет только имя модуля `fibo`. Используя имя модуля, можно обращаться к функциям:4142```python43>>> fibo.fib(1000)441 1 2 3 5 8 13 21 34 55 89 144 233 377 610 98745>>> fibo.fib2(100)46[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]47>>> fibo.__name__48'fibo'49```5051Если вы намерены часто использовать функцию, можно присвоить её локальному имени:5253```python54>>> fib = fibo.fib55>>> fib(500)561 1 2 3 5 8 13 21 34 55 89 144 233 37757```5859## Подробнее о модулях6061Модуль может содержать исполняемые операторы, а также определения функций. Эти операторы предназначены для инициализации модуля. Они выполняются только при *первом* импорте модуля куда-либо. [\[1\]](https://python-all.ru/3.0/tutorial/modules.html#id2)6263Каждый модуль имеет собственную приватную таблицу символов, которая используется как глобальная таблица символов всеми функциями, определёнными в модуле. Таким образом, автор модуля может использовать глобальные переменные в модуле, не беспокоясь о случайных конфликтах с глобальными переменными пользователя. С другой стороны, если вы знаете, что делаете, можно обращаться к глобальным переменным модуля, используя ту же нотацию, что и для обращения к его функциям: `modname.itemname`.6465Модули могут импортировать другие модули. Обычно, но не обязательно, размещать все инструкции [`import`](https://python-all.ru/3.0/reference/simple_stmts.html#import) в начале модуля (или, соответственно, скрипта). Имена импортированных модулей помещаются в глобальную таблицу символов импортирующего модуля.6667Существует разновидность инструкции [`import`](https://python-all.ru/3.0/reference/simple_stmts.html#import), которая импортирует имена из модуля непосредственно в таблицу символов импортирующего модуля. Например:6869```python70>>> from fibo import fib, fib271>>> fib(500)721 1 2 3 5 8 13 21 34 55 89 144 233 37773```7475При этом имя модуля, из которого берутся импорты, не вносится в локальную таблицу символов (поэтому в примере `fibo` не определён).7677Существует даже вариант импорта всех имён, определённых в модуле:7879```python80>>> from fibo import *81>>> fib(500)821 1 2 3 5 8 13 21 34 55 89 144 233 37783```8485Это импортирует все имена, кроме тех, которые начинаются с символа подчёркивания (`_`). В большинстве случаев программисты на Python не используют эту возможность, поскольку она вносит в интерпретатор неизвестный набор имён, что может скрыть уже определённые объекты.8687> **Примечание**88>89> Из соображений эффективности каждый модуль импортируется только один раз за сеанс интерпретатора. Поэтому, если вы изменили свои модули, необходимо перезапустить интерпретатор – или, если вы хотите интерактивно протестировать всего один модуль, используйте [`imp.reload()`](https://python-all.ru/3.0/library/imp.html#imp.reload), например `import imp; imp.reload(modulename)`.9091### Запуск модулей в виде скриптов9293Когда вы запускаете модуль Python с9495```python96python fibo.py <arguments>97```9899то код в модуле будет выполнен, как если бы вы его импортировали, но с `__name__`, установленным в `"__main__"`. Это означает, что, добавив этот код в конец вашего модуля:100101```python102if __name__ == "__main__":103 import sys104 fib(int(sys.argv[1]))105```106107можно сделать файл пригодным для использования как в качестве скрипта, так и импортируемого модуля, поскольку код, разбирающий командную строку, выполняется только при запуске модуля как «главного» файла:108109```python110$ python fibo.py 501111 1 2 3 5 8 13 21 34112```113114Если модуль импортируется, этот код не выполняется:115116```python117>>> import fibo118>>>119```120121Это часто используется либо для предоставления удобного пользовательского интерфейса модуля, либо для целей тестирования (запуск модуля как скрипта выполняет тестовый набор).122123### Путь поиска модулей124125Когда импортируется модуль с именем `spam`, интерпретатор ищет файл `spam.py` в текущем каталоге, а затем в списке каталогов, заданных переменной окружения [**PYTHONPATH**](https://python-all.ru/3.0/using/cmdline.html#envvar-PYTHONPATH). Это имеет тот же синтаксис, что и переменная оболочки **PATH**, то есть список имен каталогов. Если [**PYTHONPATH**](https://python-all.ru/3.0/using/cmdline.html#envvar-PYTHONPATH) не задана или файл не найден там, поиск продолжается в зависимом от установки пути по умолчанию; в Unix это обычно `.:/usr/local/lib/python`.126127На самом деле модули ищутся в списке каталогов, заданном переменной `sys.path`, которая инициализируется из каталога, содержащего входной скрипт (или текущего каталога), [**PYTHONPATH**](https://python-all.ru/3.0/using/cmdline.html#envvar-PYTHONPATH) и зависимого от установки пути по умолчанию. Это позволяет программам на Python, которые знают, что делают, изменять или заменять путь поиска модулей. Обратите внимание: поскольку каталог, содержащий выполняемый скрипт, находится в пути поиска, важно, чтобы скрипт не имел того же имени, что и стандартный модуль, иначе Python попытается загрузить скрипт как модуль при импорте этого модуля. Обычно это приводит к ошибке. См. раздел [*Стандартные модули*](https://python-all.ru/3.0/tutorial/modules.html#tut-standardmodules) для получения дополнительной информации.128129### «Скомпилированные» файлы Python130131Для значительного ускорения запуска коротких программ, использующих много стандартных модулей, если в каталоге, где находится `spam.py`, существует файл `spam.pyc`, то считается, что он содержит уже «откомпилированную в байт-код» версию модуля `spam`. Время изменения версии `spam.py`, использованной для создания `spam.pyc`, записывается в `spam.pyc`, и если они не совпадают, файл `.pyc` игнорируется.132133Обычно для создания файла `spam.pyc` ничего делать не нужно. Всякий раз, когда `spam.py` успешно компилируется, делается попытка записать скомпилированную версию в `spam.pyc`. Если эта попытка неудачна, это не считается ошибкой; если по какой-то причине файл не был записан полностью, полученный файл `spam.pyc` будет признан недействительным и впоследствии проигнорирован. Содержимое файла `spam.pyc` не зависит от платформы, поэтому каталог модулей Python можно использовать на машинах с разной архитектурой.134135Несколько советов для экспертов:136137- Когда интерпретатор Python запускается с флагом [*-O*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-O), генерируется оптимизированный код и сохраняется в файлах `.pyo`. Оптимизатор в настоящее время не слишком помогает; он только удаляет операторы [`assert`](https://python-all.ru/3.0/reference/simple_stmts.html#assert). При использовании [*-O*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-O) оптимизируется *весь* [*байт-код*](https://python-all.ru/3.0/glossary.html#term-bytecode); файлы `.pyc` игнорируются, а файлы `.py` компилируются в оптимизированный байт-код.138- Передача двух флагов [*-O*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-O) интерпретатору Python ([*-OO*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-OO)) заставит компилятор байт-кода выполнить оптимизации, которые в редких случаях могут привести к некорректной работе программ. В настоящее время из байт-кода удаляются только строки `__doc__`, что приводит к созданию более компактных файлов `.pyo`. Поскольку некоторые программы могут рассчитывать на их наличие, используйте эту опцию, только если вы знаете, что делаете.139- Программа не выполняется быстрее при чтении из файла `.pyc` или `.pyo`, чем при чтении из файла `.py`; единственное, что быстрее в файлах `.pyc` или `.pyo` – это скорость их загрузки.140- Когда скрипт запускается указанием его имени в командной строке, байт-код для скрипта никогда не записывается в файл `.pyc` или `.pyo`. Таким образом, время запуска скрипта можно сократить, переместив большую часть его кода в модуль и создав небольшой загрузочный скрипт, который импортирует этот модуль. Также можно указать файл `.pyc` или `.pyo` непосредственно в командной строке.141- Может существовать файл с именем `spam.pyc` (или `spam.pyo` при использовании [*-O*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-O)) без файла `spam.py` для того же модуля. Это можно использовать для распространения библиотеки кода Python в форме, которую относительно трудно декомпилировать.142- Модуль [`compileall`](https://python-all.ru/3.0/library/compileall.html#module-compileall) может создавать файлы `.pyc` (или `.pyo` при использовании [*-O*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-O)) для всех модулей в каталоге.143144## Стандартные модули145146Python поставляется с библиотекой стандартных модулей, описанной в отдельном документе – Python Library Reference (далее «Справочник по библиотеке»). Некоторые модули встроены в интерпретатор; они предоставляют доступ к операциям, которые не являются частью ядра языка, но тем не менее встроены в него, либо для эффективности, либо для доступа к примитивам операционной системы, таким как системные вызовы. Набор таких модулей – это опция конфигурации, которая также зависит от базовой платформы. Например, модуль [`winreg`](https://python-all.ru/3.0/library/winreg.html#module-winreg) доступен только в системах Windows. Один конкретный модуль заслуживает внимания: [`sys`](https://python-all.ru/3.0/library/sys.html#module-sys), который встроен в каждый интерпретатор Python. Переменные `sys.ps1` и `sys.ps2` определяют строки, используемые в качестве основного и вторичного приглашений.147148```python149>>> import sys150>>> sys.ps1151'>>> '152>>> sys.ps2153'... '154>>> sys.ps1 = 'C> '155C> print('Yuck!')156Yuck!157C>158```159160Эти две переменные определены только в том случае, если интерпретатор находится в интерактивном режиме.161162Переменная `sys.path` – это список строк, определяющий путь поиска модулей интерпретатором. Она инициализируется путем по умолчанию, взятым из переменной окружения [**PYTHONPATH**](https://python-all.ru/3.0/using/cmdline.html#envvar-PYTHONPATH), или из встроенного значения по умолчанию, если [**PYTHONPATH**](https://python-all.ru/3.0/using/cmdline.html#envvar-PYTHONPATH) не задана. Её можно изменить с помощью стандартных операций со списками.163164```python165>>> import sys166>>> sys.path.append('/ufs/guido/lib/python')167```168169## Функция [`dir()`](https://python-all.ru/3.0/library/functions.html#dir)170171Встроенная функция [`dir()`](https://python-all.ru/3.0/library/functions.html#dir) используется для выяснения, какие имена определяет модуль. Она возвращает отсортированный список строк:172173```python174>>> import fibo, sys175>>> dir(fibo)176['__name__', 'fib', 'fib2']177>>> dir(sys)178['__displayhook__', '__doc__', '__excepthook__', '__name__', '__stderr__',179 '__stdin__', '__stdout__', '_getframe', 'api_version', 'argv',180 'builtin_module_names', 'byteorder', 'callstats', 'copyright',181 'displayhook', 'exc_info', 'excepthook',182 'exec_prefix', 'executable', 'exit', 'getdefaultencoding', 'getdlopenflags',183 'getrecursionlimit', 'getrefcount', 'hexversion', 'maxint', 'maxunicode',184 'meta_path', 'modules', 'path', 'path_hooks', 'path_importer_cache',185 'platform', 'prefix', 'ps1', 'ps2', 'setcheckinterval', 'setdlopenflags',186 'setprofile', 'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout',187 'version', 'version_info', 'warnoptions']188```189190Без аргументов [`dir()`](https://python-all.ru/3.0/library/functions.html#dir) перечисляет имена, которые вы определили в данный момент:191192```python193>>> a = [1, 2, 3, 4, 5]194>>> import fibo195>>> fib = fibo.fib196>>> dir()197['__builtins__', '__doc__', '__file__', '__name__', 'a', 'fib', 'fibo', 'sys']198```199200Обратите внимание, что она перечисляет имена всех типов: переменные, модули, функции и т.д.201202[`dir()`](https://python-all.ru/3.0/library/functions.html#dir) не перечисляет имена встроенных функций и переменных. Если вам нужен их список, они определены в стандартном модуле [`builtins`](https://python-all.ru/3.0/library/builtins.html#module-builtins):203204```python205>>> import builtins206>>> dir(builtins)207208['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException', 'Buffer209Error', 'BytesWarning', 'DeprecationWarning', 'EOFError', 'Ellipsis', 'Environme210ntError', 'Exception', 'False', 'FloatingPointError', 'FutureWarning', 'Generato211rExit', 'IOError', 'ImportError', 'ImportWarning', 'IndentationError', 'IndexErr212or', 'KeyError', 'KeyboardInterrupt', 'LookupError', 'MemoryError', 'NameError',213 'None', 'NotImplemented', 'NotImplementedError', 'OSError', 'OverflowError', 'P214endingDeprecationWarning', 'ReferenceError', 'RuntimeError', 'RuntimeWarning', '215StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError', 'SystemExit', 'Ta216bError', 'True', 'TypeError', 'UnboundLocalError', 'UnicodeDecodeError', 'Unicod217eEncodeError', 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserW218arning', 'ValueError', 'Warning', 'ZeroDivisionError', '__build_class__', '__deb219ug__', '__doc__', '__import__', '__name__', '__package__', 'abs', 'all', 'any',220'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'chr', 'classmethod', 'compile', '221complex', 'copyright', 'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate222', 'eval', 'exec', 'exit', 'filter', 'float', 'format', 'frozenset', 'getattr',223'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance',224 'issubclass', 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memory225view', 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property'226, 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice', 'sort227ed', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars', 'zip']228```229230## Пакеты231232Пакеты – это способ структурирования пространства имён модулей Python с помощью «точечных имён модулей». Например, имя модуля `A.B` обозначает подмодуль с именем `B` в пакете с именем `A`. Подобно тому, как использование модулей избавляет авторов разных модулей от необходимости беспокоиться о глобальных переменных друг друга, использование точечных имён модулей избавляет авторов многомодульных пакетов, таких как NumPy или Python Imaging Library, от беспокойства об именах модулей друг друга.233234Предположим, вы хотите спроектировать набор модулей («пакет») для единообразной обработки звуковых файлов и звуковых данных. Существует множество различных форматов звуковых файлов (обычно определяемых по расширению, например: `.wav`, `.aiff`, `.au`), поэтому вам может потребоваться создать и поддерживать растущую коллекцию модулей для преобразования между различными форматами файлов. Также существует множество различных операций, которые вы, возможно, захотите выполнять со звуковыми данными (таких как микширование, добавление эха, применение эквалайзера, создание искусственного стереоэффекта), поэтому, вдобавок, вы будете писать бесконечный поток модулей для выполнения этих операций. Вот возможная структура вашего пакета (выраженная в терминах иерархической файловой системы):235236```python237sound/ Top-level package238 __init__.py Initialize the sound package239 formats/ Subpackage for file format conversions240 __init__.py241 wavread.py242 wavwrite.py243 aiffread.py244 aiffwrite.py245 auread.py246 auwrite.py247 ...248 effects/ Subpackage for sound effects249 __init__.py250 echo.py251 surround.py252 reverse.py253 ...254 filters/ Subpackage for filters255 __init__.py256 equalizer.py257 vocoder.py258 karaoke.py259 ...260```261262При импорте пакета Python просматривает каталоги по `sys.path` в поисках подкаталога пакета.263264Файлы `__init__.py` необходимы, чтобы Python рассматривал каталоги как содержащие пакеты; это сделано для предотвращения случайного скрытия каталогами с распространённым именем, например `string`, корректных модулей, находящихся позже в пути поиска модулей. В простейшем случае `__init__.py` может быть просто пустым файлом, но он также может выполнять код инициализации пакета или устанавливать переменную `__all__`, описанную далее.265266Пользователи пакета могут импортировать отдельные модули из пакета, например:267268```python269import sound.effects.echo270```271272Это загружает подмодуль `sound.effects.echo`. К нему необходимо обращаться по полному имени.273274```python275sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)276```277278Альтернативный способ импорта подмодуля:279280```python281from sound.effects import echo282```283284Это также загружает подмодуль `echo` и делает его доступным без префикса пакета, так что его можно использовать следующим образом:285286```python287echo.echofilter(input, output, delay=0.7, atten=4)288```289290Ещё один вариант – импортировать нужную функцию или переменную напрямую:291292```python293from sound.effects.echo import echofilter294```295296Опять же, это загружает подмодуль `echo`, но на этот раз делает его функцию `echofilter()` непосредственно доступной:297298```python299echofilter(input, output, delay=0.7, atten=4)300```301302Обратите внимание, что при использовании `from package import item` элемент может быть как подмодулем (или подпакетом) пакета, так и другим именем, определённым в пакете, например функцией, классом или переменной. Инструкция `import` сначала проверяет, определён ли элемент в пакете; если нет, она предполагает, что это модуль, и пытается его загрузить. Если его не удаётся найти, возбуждается исключение [`ImportError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ImportError).303304Напротив, при использовании синтаксиса типа `import item.subitem.subsubitem` каждый элемент, кроме последнего, должен быть пакетом; последний элемент может быть модулем или пакетом, но не может быть классом, функцией или переменной, определённой в предыдущем элементе.305306### Импорт \* из пакета307308Что происходит, когда пользователь пишет `from sound.effects import *`? В идеале можно было бы надеяться, что этот оператор каким-то образом обращается к файловой системе, находит все подмодули, присутствующие в пакете, и импортирует их все. К сожалению, эта операция не очень хорошо работает на платформах Windows, где файловая система не всегда содержит точную информацию о регистре имени файла! На этих платформах нет гарантированного способа узнать, должен ли файл `ECHO.PY` импортироваться как модуль `echo`, `Echo` или `ECHO`. (Например, в Windows 95 есть раздражающая практика отображать все имена файлов с заглавной первой буквой.) Ограничение на имена файлов DOS 8+3 добавляет ещё одну интересную проблему для длинных имён модулей.309310Единственное решение – чтобы автор пакета предоставил явный индекс пакета. Оператор import использует следующее соглашение: если в коде `__init__.py` пакета определён список с именем `__all__`, то он считается списком имён модулей, которые должны быть импортированы при встрече оператора `from пакет import *`. Автор пакета должен обновлять этот список при выпуске новой версии пакета. Авторы пакетов также могут решить не поддерживать его, если не видят пользы от импорта \* из своего пакета. Например, файл `sounds/effects/__init__.py` может содержать следующий код:311312```python313__all__ = ["echo", "surround", "reverse"]314```315316Это означает, что `from sound.effects import *` импортирует три указанных подмодуля пакета `sound`.317318If `__all__` is not defined, the statement `from sound.effects import *` does *not* import all submodules from the package `sound.effects` into the current namespace; it only ensures that the package `sound.effects` has been imported (possibly running any initialization code in `__init__.py`) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by `__init__.py`. It also includes any submodules of the package that were explicitly loaded by previous import statements. Consider this code:319320```python321import sound.effects.echo322import sound.effects.surround323from sound.effects import *324```325326В этом примере модули echo и surround импортируются в текущее пространство имён, потому что они определены в пакете `sound.effects`, когда выполняется оператор `from...import`. (Это также работает, если определён `__all__`.)327328Отметим, что в целом практика импорта `*` из модуля или пакета не одобряется, так как часто приводит к плохо читаемому коду. Однако её можно использовать для сокращения ввода в интерактивных сессиях, и некоторые модули разработаны так, чтобы экспортировать только имена, соответствующие определённым шаблонам.329330Помните: в использовании `from Package import specific_submodule` нет ничего плохого! Фактически это рекомендуемая форма записи, если только импортирующему модулю не нужны подмодули с одинаковыми именами из разных пакетов.331332### Ссылки внутри пакета333334Когда пакеты структурированы в подпакеты (как пакет `sound` в примере), можно использовать абсолютные импорты для обращения к подмодулям соседних пакетов. Например, если модулю `sound.filters.vocoder` нужен модуль `echo` из пакета `sound.effects`, он может использовать `from sound.effects import echo`.335336Можно также писать относительные импорты в форме `from module import name`. В таких импортах ведущие точки указывают на текущий и родительские пакеты. Например, из модуля `surround` можно использовать:337338```python339from . import echo340from .. import formats341from ..filters import equalizer342```343344Обратите внимание: относительные импорты основаны на имени текущего модуля. Поскольку имя главного модуля всегда `"__main__"`, модули, предназначенные для использования в качестве главного модуля приложения Python, всегда должны использовать абсолютные импорты.345346### Пакеты в нескольких каталогах347348Пакеты поддерживают ещё один специальный атрибут – `__path__`. Он инициализируется списком, содержащим имя каталога, в котором находится `__init__.py` пакета, до выполнения кода в этом файле. Эту переменную можно изменять; это повлияет на последующий поиск модулей и подпакетов, содержащихся в пакете.349350Хотя эта возможность требуется нечасто, её можно использовать для расширения набора модулей, доступных в пакете.351352Сноски353354| [\[1\]](https://python-all.ru/3.0/tutorial/modules.html#id1) | На самом деле определения функций также являются «операторами», которые «выполняются»; выполнение вносит имя функции в глобальную таблицу символов модуля. |355| --- | --- |356