Модули

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"]

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

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