Модули

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