Модули

6.1. Подробнее о модулях

Модуль может содержать исполняемые инструкции наряду с определениями функций. Эти инструкции предназначены для инициализации модуля. Они выполняются только при первом появлении имени модуля в инструкции импорта. [1] (Они также выполняются, если файл запущен как скрипт.)

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

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

Существует разновидность инструкции import, которая импортирует имена из модуля непосредственно в пространство имён импортирующего модуля. Например:

>>> from fibo import fib, fib2
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

При этом имя модуля, из которого выполняется импорт, не добавляется в локальное пространство имён (поэтому в примере имя fibo не определено).

Есть даже вариант, который импортирует все имена, определённые в модуле:

>>> from fibo import *
>>> fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Импортируются все имена, кроме тех, что начинаются с подчёркивания (_). В большинстве случаев программисты на Python не используют эту возможность, поскольку она добавляет в интерпретатор неизвестный набор имён и может скрыть уже определённые вами сущности.

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

Если за именем модуля следует as, имя после as напрямую связывается с импортированным модулем.

>>> import fibo as fib
>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

По сути, это импортирует модуль так же, как это делает import fibo, но с единственным отличием: он доступен под именем fib.

Это также можно использовать с инструкцией from с аналогичным результатом:

>>> from fibo import fib as fibonacci
>>> fibonacci(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

python fibo.py <arguments>

if __name__ == "__main__":
    import sys
    fib(int(sys.argv[1]))

$ python fibo.py 50
0 1 1 2 3 5 8 13 21 34

>>> import fibo
>>>

6.2. Стандартные модули

Python поставляется со стандартной библиотекой модулей, описанной в отдельном документе — справочнике по библиотеке Python (далее — «Справочник по библиотеке»). Некоторые модули встроены в интерпретатор; они предоставляют доступ к операциям, не входящим в ядро языка, но встроенным либо ради эффективности, либо для доступа к примитивам операционной системы, таким как системные вызовы. Набор таких модулей является параметром конфигурации и также зависит от используемой платформы. Например, модуль winreg доступен только в системах Windows. Особого внимания заслуживает модуль sys, встроенный в каждый интерпретатор Python. Переменные sys.ps1 и sys.ps2 задают строки, используемые в качестве основных и вторичных приглашений:

>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print('Yuck!')
Yuck!
C>

Эти две переменные определены только в интерактивном режиме интерпретатора.

Переменная sys.path — это список строк, определяющий путь поиска модулей для интерпретатора. Она инициализируется путём по умолчанию, заданным переменной среды PYTHONPATH, или встроенным путём по умолчанию, если переменная PYTHONPATH не задана. Её можно изменить с помощью стандартных операций со списками:

>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')

6.3. Функция dir()

Встроенная функция dir() используется для определения имён, заданных в модуле. Она возвращает отсортированный список строк:

>>> import fibo, sys
>>> dir(fibo)
['__name__', 'fib', 'fib2']
>>> dir(sys)
['__breakpointhook__', '__displayhook__', '__doc__', '__excepthook__',
 '__interactivehook__', '__loader__', '__name__', '__package__', '__spec__',
 '__stderr__', '__stdin__', '__stdout__', '__unraisablehook__',
 '_clear_type_cache', '_current_frames', '_debugmallocstats', '_framework',
 '_getframe', '_git', '_home', '_xoptions', 'abiflags', 'addaudithook',
 'api_version', 'argv', 'audit', 'base_exec_prefix', 'base_prefix',
 'breakpointhook', 'builtin_module_names', 'byteorder', 'call_tracing',
 'callstats', 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info',
 'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info',
 'float_repr_style', 'get_asyncgen_hooks', 'get_coroutine_origin_tracking_depth',
 'getallocatedblocks', 'getdefaultencoding', 'getdlopenflags',
 'getfilesystemencodeerrors', 'getfilesystemencoding', 'getprofile',
 'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval',
 'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',
 'intern', 'is_finalizing', 'last_traceback', 'last_type', 'last_value',
 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path', 'path_hooks',
 'path_importer_cache', 'platform', 'prefix', 'ps1', 'ps2', 'pycache_prefix',
 'set_asyncgen_hooks', 'set_coroutine_origin_tracking_depth', 'setdlopenflags',
 'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace', 'stderr',
 'stdin', 'stdout', 'thread_info', 'unraisablehook', 'version', 'version_info',
 'warnoptions']

Если не передавать аргументы, функция dir() выведет имена, определённые вами на данный момент:

>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']

Обратите внимание, что она выводит имена всех типов: переменные, модули, функции и т. д.

Функция dir() не выводит имена встроенных функций и переменных. Если вам нужен их список, они определены в стандартном модуле builtins:

>>> import builtins
>>> dir(builtins)
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
 'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
 'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
 'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
 'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
 'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
 'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
 'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
 'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
 'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
 'NotImplementedError', 'OSError', 'OverflowError',
 'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
 'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
 'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
 'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
 'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
 'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
 'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
 '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
 'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',
 'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',
 'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',
 'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',
 'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',
 'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',
 'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',
 'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',
 'zip']

6.4. Пакеты

Пакеты позволяют структурировать пространство имён модулей Python с помощью «составных имён модулей», разделённых точками. Например, имя модуля A.B обозначает подмодуль B в пакете A. Подобно тому, как модули избавляют авторов разных модулей от необходимости беспокоиться о совпадении имён их глобальных переменных, составные имена модулей избавляют авторов многомодульных пакетов, таких как NumPy или Pillow, от необходимости беспокоиться о совпадении имён модулей.

Предположим, вы хотите разработать коллекцию модулей («пакет») для единообразной работы со звуковыми файлами и аудиоданными. Существует множество форматов звуковых файлов (обычно определяемых по расширению, например: .wav, .aiff, .au), поэтому может понадобиться создать и поддерживать растущую коллекцию модулей для преобразования между различными форматами файлов. Кроме того, существует множество операций, которые можно выполнять над аудиоданными (например, микширование, добавление эха, применение эквалайзера, создание искусственного стереоэффекта), поэтому вам придётся постоянно писать новые модули для выполнения этих операций. Возможная структура вашего пакета (представленная в виде иерархической файловой системы) выглядит так:

sound/                          Top-level package
      __init__.py               Initialize the sound package
      formats/                  Subpackage for file format conversions
              __init__.py
              wavread.py
              wavwrite.py
              aiffread.py
              aiffwrite.py
              auread.py
              auwrite.py
              ...
      effects/                  Subpackage for sound effects
              __init__.py
              echo.py
              surround.py
              reverse.py
              ...
      filters/                  Subpackage for filters
              __init__.py
              equalizer.py
              vocoder.py
              karaoke.py
              ...

При импорте пакета Python просматривает каталоги в sys.path в поисках подкаталога пакета.

Файлы __init__.py необходимы, чтобы Python считал содержащие их каталоги пакетами (если только не используется пакет пространства имён — относительно продвинутая возможность). Это не позволяет каталогам с распространёнными именами, например string, случайно скрывать действительные модули, расположенные далее в пути поиска модулей. В простейшем случае файл __init__.py может быть пустым, но в нём также можно выполнять код инициализации пакета или задавать переменную __all__, о которой речь пойдёт далее.

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

import sound.effects.echo

Эта инструкция загружает подмодуль sound.effects.echo. На него нужно ссылаться по полному имени.

sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

Другой способ импортировать подмодуль:

from sound.effects import echo

Эта инструкция также загружает подмодуль echo и делает его доступным без префикса пакета, поэтому его можно использовать так:

echo.echofilter(input, output, delay=0.7, atten=4)

Ещё один вариант — напрямую импортировать нужную функцию или переменную:

from sound.effects.echo import echofilter

И в этом случае загружается подмодуль echo, но его функция echofilter() становится доступна напрямую:

echofilter(input, output, delay=0.7, atten=4)

Обратите внимание, что при использовании from package import item элементом может быть подмодуль (или подпакет) пакета либо другое имя, определённое в пакете, например функция, класс или переменная. Инструкция import сначала проверяет, определён ли элемент в пакете; если нет, она считает его модулем и пытается загрузить. Если найти его не удаётся, возникает исключение ImportError.

Напротив, при использовании синтаксиса вроде import item.subitem.subsubitem все элементы, кроме последнего, должны быть пакетами; последний элемент может быть модулем или пакетом, но не классом, функцией или переменной, определёнными в предыдущем элементе.

__all__ = ["echo", "surround", "reverse"]

__all__ = [
    "echo",      # refers to the 'echo.py' file
    "surround",  # refers to the 'surround.py' file
    "reverse",   # !!! refers to the 'reverse' function now !!!
]

def reverse(msg: str):  # <-- this name shadows the 'reverse.py' submodule
    return msg[::-1]    #     in the case of a 'from sound.effects import *'

import sound.effects.echo
import sound.effects.surround
from sound.effects import *

from . import echo
from .. import formats
from ..filters import equalizer