Модули

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