Для чего в пакетах модулей python в файле init py служит список all
Если вы решили использовать импортирование пакетов, существует еще одно условие, которое необходимо будет соблюдать: каждый каталог в пути, указанном в инструкции импортирования пакета, должен содержать файл с именем __init__.py, в противном случае операция импорта пакета будет терпеть неудачу. То есть в примере выше каталоги dir1 и dir2 должны содержать файл с именем __init__.py каталог-контейнер dir0 может не содержать такой файл, потому что сам он не указан в инструкции импортирования пакета. Точнее говоря, для такой структуры каталогов:
dir0\dir1\dir2\mod.py
и инструкции импортирования, имеющей следующий вид:
import dir1.dir2.mod
применяются следующие правила:
• dir1 и dir2 должны содержать файл __init__.py .
• dir0 , каталог-контейнер, может не содержать файл __init__.py – этот файл
будет проигнорирован, если он присутствует.
• dir0 , но не dir0\dir1 , должен присутствовать в пути поиска модулей (то есть он должен быть домашним каталогом или присутствовать в переменной окружения PYTHONPATH и так далее).
Таким образом, структура каталогов в этом примере должна иметь следующий вид (здесь отступы указывают на вложенность каталогов):
Инициализация пакета
Когда интерпретатор Python импортрирует каталог в первый раз он автоматически запускает программный код файла __init__.py этого каталога. По этой причине обычно в эти файлы помещается программный код, выполняющий действия по инициализации, необходимые для файлов в пакете.
Например, этот файл инициализации в пакете может использоваться для создания файлов с данными, открытия соединения с базой данных и так далее. Обычно файлы __init__.py не предназначены для непосредственного выполнения – они запускаются автоматически, когда выполняется первое обращение к пакету.
Инициализация пространства имен модуля
При импортировании пакетов пути к каталогам в вашем сценарии после завершения операции импортирования превращаются в настоящие иерархии вложенных объектов. Например, в предыдущем примере после завершения операции импортирования можно будет использовать выражение dir1.dir2 , которое возвращает объект модуля, чье пространство имен содержит все имена, определяемые файлом __init__.py из каталога dir2 . Такие файлы создают пространства имен для объектов модулей, соответствующих каталогам, в которых отсутствуют настоящие файлы модулей.
Поведение инструкции from *
В качестве дополнительной особенности, в файлах __init__.py можно использовать списки __all__ , чтобы определить, что будет импортироваться из каталога инструкцией from *. Список __all__ в файлах __init__.py представляет собой список имен субмодулей, которые должны импортироваться, когда в инструкции from * указывается имя пакета (каталога). Если список __all__ отсутствует, инструкция from * не будет автоматически загружать субмодули, вложенные в каталог, – она загрузит только имена,
определяемые инструкциями присваивания в файле __init__.py , включая любые субмодули, явно импортируемые программным кодом в этом файле. Например, инструкция from submodule import X в файле __init__.py создаст имя X в пространстве имен каталога. (Мы поближе познакомимся со списком __all__ в следующих постах.)
Эти файлы можно оставить пустыми, если вам не требуется выполнять специальных действий. Однако для успешного выполнения операции импортирования каталогов они должны существовать обязательно.
Эти файлы можно оставить пустыми, если вам не требуется выполнять специальных действий. Однако для успешного выполнения операции импортирования каталогов они должны существовать обязательно.
Оператор import является наиболее распространенным способом вызова определений модуля, но это не единственный способ. Такие функции, как importlib.import_module() и встроенная функция __import__() также могут быть использованы для вызова механизма импорта.
Оператор import объединяет две операции: он выполняет поиск именованного модуля, а затем привязывает результаты этого поиска к имени в области видимости вызывающей стороны. Операция поиска оператором import определяется как вызов функции __import__() с соответствующими аргументами. Возвращаемое значение __import__() используется для выполнения операции связывания имени оператором import .
Прямой вызов функции __import__() выполняет только поиск модуля и, если он найден, операцию инициализации модуля. Только оператор import выполняет операцию привязки имени к пространству имен вызывающей стороны.
При первом импорте модуля Python выполняет поиск модуля и, если он найден, создает объект модуля, инициализируя его. Если именованный модуль не может быть найден, то вызывается исключение ModuleNotFoundError .
importlib
Модуль importlib предоставляет богатый API для взаимодействия с системой импорта. Например, importlib.import_module() предоставляет рекомендуемый, более простой API, чем встроенный __import__() , для вызова механизма импорта.
Спецификация инструкции import в Python.
Базовая инструкция `import`, без оператора `from`, выполняется в два этапа. Поиск модуля, загрузка и инициализация его при необходимости. Определение имени или имён, в локальном пространстве имен, для области, в которой выполняется инструкция import.
Определение модуля и его импорт в Python.
Модуль - это файл, содержащий определения и операторы Python. Имя файла - это имя модуля с добавленным суффиксом `.py`. Внутри модуля, имя модуля, в виде строки, доступно в качестве значения глобальной переменной `__name__`.
Конструкция импорта import modulle as name в Python.
Содержимое модуля можно импортировать из определения функции. В этом случае импорт не выполняется до тех пор, пока не будет вызвана функция
Конструкция импорта from modulle import names в Python.
Альтернативная форма инструкции `import` позволяет импортировать отдельные объекты из модуля непосредственно в область видимости вызывающего объекта (другого модуля или скрипта)
Конструкция импорта from modulle import name as alt_name в Python.
Можно импортировать отдельные объекты модуля, но ввести их в глобальную область видимости скрипта с альтернативными именами
Как Python ищет импортируемый модуль
Каталог, из которого был запущен скрипт. Список каталогов, содержащихся в переменной окружения `PYTHONPATH`. Список каталогов, настроенных во время установки Python.
Список имен, определенных в модуле Python.
Встроенная функция `dir()` возвращает список определенных имен в пространстве имен. Если задан аргумент, который является именем модуля, `dir()` перечисляет имена, определенные в модуле.
Выполнение модуля как скрипта в Python.
Когда файл `.py` импортируется как модуль, Python устанавливает специальную переменную `__name__` в имя модуля. Однако, если файл выполняется как автономный сценарий, `__name__` устанавливается в строку `__main__`.
Перезагрузка модуля в Python.
Если в модуль вносятся изменения то его нужно перезагружать, что бы изменения вступили в силу. Для этого нужно либо перезапустить интерпретатор, либо использовать функцию `importlib.reload()` из модуля `importlib`
Пакеты модулей в Python.
Пакеты позволяют иерархически структурировать пространство имен модуля с использованием точечной нотации. Точно так же, как модули помогают избежать коллизий между именами глобальных переменных, пакеты помогают избежать коллизий между именами модулей
Файл пакета __init__.py в Python.
Если файл с именем __init__.py присутствует в каталоге пакета, то он вызывается при импорте пакета или модуля в пакете. Это может быть использовано для выполнения кода инициализации пакета, например инициализации данных уровня пакета.
Переменная __all__ в пакетах и модулях в Python.
Если `__init__.py` файл в каталоге пакета содержит список с именем `__all__`, он считается списком модулей, которые должны быть импортированы при обнаружении инструкции `from import *`.
Переменная пакета __path__ в Python.
Атрибут пакета `__path__` используется при импорте его подпакетов. В механизме импорта он работает почти так же, как `sys.path` и предоставление списка местоположений для поиска модулей во время импорта.
Относительный импорт пакетов в Python.
Относительный импорт использует опережающие точки.
Вложенные подпакеты в Python.
Пакеты могут содержать вложенные подпакеты произвольной глубины. Для отделения имени пакета от имени вложенного пакета используется дополнительная точечная нотация
Пространства имен пакета в Python.
В настоящее время Python предоставляет pkgutil.extend_path для обозначения пространства имен пакета. `setuptools` предоставляет аналогичную функцию с именем `pkg_resources.declare_namespace`.
Настройка доступа к атрибутам модуля в Python.
Специальные имена __getattr__ и __dir__ также могут использоваться для настройки доступа к атрибутам модуля. Функция __getattr__ на уровне модуля должна принимать один аргумент, который является именем атрибута, и возвращать вычисленное значение или вызывать AttributeError.
Linked to, but not explicitly mentioned here, is exactly when __all__ is used. It is a list of strings defining what symbols in a module will be exported when from import * is used on the module.
For example, the following code in a foo.py explicitly exports the symbols bar and baz :
These symbols can then be imported like so:
If the __all__ above is commented out, this code will then execute to completion, as the default behaviour of import * is to import all symbols that do not begin with an underscore, from the given namespace.
NOTE: __all__ affects the from import * behavior only. Members that are not mentioned in __all__ are still accessible from outside the module and can be imported with from import .
The goal is to illustrate that the symbols are exported. Whether it executes the function or not is secondary.
I find it puzzling that to this day, there isn't a way to populate __all__ by referencing the functions/objects directly. Instead we have to type down their names and correct them individually anytime a name changes. Seems very bug prone for active codebases.
@JulioCezarSilva off topic a bit, but worth noting that for classes and functions you can use the __name__ property
It's a list of public objects of that module, as interpreted by import * . It overrides the default of hiding everything that begins with an underscore.
Objects that begin with an underscore, or are not mentioned in __all__ if __all__ is present, are not exactly hidden; they can be seen and accessed perfectly normally if you know their names. It is only in the case of an "import *", which is not recommended anyway, that the distinction carries any weight.
@BrandonRhodes: that’s not exactly true either: It’s recommended to only import modules that you know to be designed for import * (like e.g. tk ). A good hint if this is the case is the presence of __all__ or names starting with underscore in the module’s code.
I'm not sure that if tk were released today (or in 2012, even), the recommended practice would be to use from tk import * . I think the practice is accepted due to inertia, not intentional design.
To summarize: If you have __all__ , import * will import everything in the __all__ , otherwise, it will import everything that does not start with an underscore.
Explain all in Python?
I keep seeing the variable __all__ set in different __init__.py files.
What does this do?
6.1. More on Modules¶
A module can contain executable statements as well as function definitions. These statements are intended to initialize the module. They are executed only the first time the module name is encountered in an import statement. 1 (They are also run if the file is executed as a script.)
Each module has its own private symbol table, which is used as the global symbol table by all functions defined in the module. Thus, the author of a module can use global variables in the module without worrying about accidental clashes with a user’s global variables. On the other hand, if you know what you are doing you can touch a module’s global variables with the same notation used to refer to its functions, modname.itemname .
Modules can import other modules. It is customary but not required to place all import statements at the beginning of a module (or script, for that matter). The imported module names are placed in the importing module’s global symbol table.
There is a variant of the import statement that imports names from a module directly into the importing module’s symbol table. For example:
This does not introduce the module name from which the imports are taken in the local symbol table (so in the example, fibo is not defined).
There is even a variant to import all names that a module defines:
This imports all names except those beginning with an underscore ( _ ). In most cases Python programmers do not use this facility since it introduces an unknown set of names into the interpreter, possibly hiding some things you have already defined.
Note that in general the practice of importing * from a module or package is frowned upon, since it often causes poorly readable code. However, it is okay to use it to save typing in interactive sessions.
If the module name is followed by as , then the name following as is bound directly to the imported module.
This is effectively importing the module in the same way that import fibo will do, with the only difference of it being available as fib .
It can also be used when utilising from with similar effects:
For efficiency reasons, each module is only imported once per interpreter session. Therefore, if you change your modules, you must restart the interpreter – or, if it’s just one module you want to test interactively, use importlib.reload() , e.g. import importlib; importlib.reload(modulename) .
6.3. The dir() Function¶
The built-in function dir() is used to find out which names a module defines. It returns a sorted list of strings:
Without arguments, dir() lists the names you have defined currently:
Note that it lists all types of names: variables, modules, functions, etc.
dir() does not list the names of built-in functions and variables. If you want a list of those, they are defined in the standard module builtins :
Циклические импорты
Если вдруг вы захотите в один модуль импортировать другой, а другой захочет, пусть даже и не напрямую, импортировать первый, то вы получите ImportError . Потому что у вас случится циклический импорт. Про оный нужно просто знать и стараться архитектурить код так, чтобы циклов не случалось.
Если же приспичивает, и импортировать что-то "ну очень нужно", то можно попробовать обойтись локальным импортом:
Да, это костыль. Но иногда полезный. В идеале — до ближайшего большого рефакторинга. Поэтому настраивайте linter на ловлю локальных импортов и стремитесь убирать такие костыли хоть когда-нибудь!
Пакеты, модули и точки входа
С модулем __init__.py разобрались. Настала очередь модуля __main__.py . Этот модуль позволяет сделать пакет исполняемым посредством вызова python -m … . Те из вас, кому знакомо оформление точки входа в модулях, могут догадаться, откуда ноги растут у магического выражения __name__ == '__main__' — да, отсюда! Для остальных напоминаю: чтобы модуль сделать "исполняемым, но не при импорте", в конец модуля дописывается конструкция
У модуля, который скармливается интерпретатору напрямую ( python file.py ) или в роли претендента на запуск ( python -m module ), атрибут __name__ будет содержать то самое магическое '__main__' . А в остальное время атрибут содержит полное имя модуля. С помощью условия, показанного выше, модуль может решить, что делать при запуске.
У пакетов роль атрибута выполняет специальный файл __main__.py . Когда мы запустим пакет через python path/to/package или python -m package , интерпретатор будет искать и выполнять именно этот файл.
Более того, модули __main__ нельзя импортировать обычным способом, поэтому можно не бояться случайного импорта и писать команды прямо на верхнем уровне: всё равно странно в модуле с именем __main__ проверять, что его имя равно __main__ (хе-хе!).
А ещё модуль __main__.py удобен тем, что его можно класть в корень вашего проекта, после чего запускать проект можно будет с помощью команды python . ! Лаконично, не правда ли?
6.4.1. Importing * From a Package¶
Now what happens when the user writes from sound.effects import * ? Ideally, one would hope that this somehow goes out to the filesystem, finds which submodules are present in the package, and imports them all. This could take a long time and importing sub-modules might have unwanted side-effects that should only happen when the sub-module is explicitly imported.
The only solution is for the package author to provide an explicit index of the package. The import statement uses the following convention: if a package’s __init__.py code defines a list named __all__ , it is taken to be the list of module names that should be imported when from package import * is encountered. It is up to the package author to keep this list up-to-date when a new version of the package is released. Package authors may also decide not to support it, if they don’t see a use for importing * from their package. For example, the file sound/effects/__init__.py could contain the following code:
This would mean that from sound.effects import * would import the three named submodules of the sound.effects package.
If __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:
In this example, the echo and surround modules are imported in the current namespace because they are defined in the sound.effects package when the from. import statement is executed. (This also works when __all__ is defined.)
Although certain modules are designed to export only names that follow certain patterns when you use import * , it is still considered bad practice in production code.
Remember, there is nothing wrong with using from package import specific_submodule ! In fact, this is the recommended notation unless the importing module needs to use submodules with the same name from different packages.
from module import names
PEP 420, или неявные пространства имён
Раз уж развёл ликбез, расскажу и про эту штуку.
Долгое время в Python пакеты были обязаны иметь файл __init__.py — наличие этого файла позволяло отличить пакет от обычной директории с модулями (с которыми Python работать не мог). Но с версии Python3.3 вступил в силу PEP 420, позволяющий создавать пространства имён "на вырост".
Теперь вы можете создавать пакет без __init__.py , и такой пакет сможет существовать полноценно, разве что при импорте содержимого не будет производиться инициализация. Но, конечно же, данное изменение делалось не с целью сэкономить на файлах. Подобные пакеты могут встречаться в путях поиска пакетов (о поиске пакетов я ниже расскажу) более одного раза: все встреченные структуры с общим корневым именем при загрузке схлопнутся в одно пространство имён.
Тут стоит отметить, что с полноценными пакетами подобное не срабатывало ранее и не будет работать в будущем. Если среди путей пакет с модулем инициализации находится в первый раз, все последующие пакеты с тем же именем будут проигнорированы. Это защищает вас от смешивания сторонних пакетов с системными. И даже просто от ошибок именования: назвав пакет так же, как называется встроенный пакет или модуль, вы получите ошибку — ваши определения не будут импортироваться.
Пакеты — пространства имён (Namespace Packages, NP) — а именно так называются пакеты без инициализации — не могут объединяться с полноценными пакетами, поэтому добавить что-то в системный пакет вам также не удастся. И тут всё защищено!
Какая же польза от неявных пространств имён? А вы представьте себя авторами, скажем, игрового движка. Вы хотите весь код держать в общем пространстве имён engine , но при этом не желаете, чтобы весь код поставлялся одним дистрибутивом (не каждому же пользователю нужны все-все компоненты движка). С NP вы можете в нескольких дистрибутивах использовать общее корневое имя engine , но разные подпакеты и подмодули. А на выходе вы получите возможность делать импорты вида
Важно: помните, если встретятся обычный пакет и NP с одинаковым именем, то победит обычный пакет! А NP, сколько бы их не было, не будут загружены!
6.4.3. Packages in Multiple Directories¶
Packages support one more special attribute, __path__ . This is initialized to be a list containing the name of the directory holding the package’s __init__.py before the code in that file is executed. This variable can be modified; doing so affects future searches for modules and subpackages contained in the package.
While this feature is not often needed, it can be used to extend the set of modules found in a package.
In fact function definitions are also ‘statements’ that are ‘executed’; the execution of a module-level function definition enters the function name in the module’s global symbol table.
Как вы, возможно знаете, код на Python хранится в модулях (modules), которые могут быть объединены в пакеты (packages). Это руководство призвано подробно рассказать именно о пакетах, однако совсем не упомянуть модули нельзя, поэтому я немного расскажу и о них. Многое из того, что применимо к модулям, справедливо и для пакетов, особенно если принять во внимание тот факт, что каждый, как правило, ведёт себя как модуль.
Кратко о модулях
Модуль в Python — это файл с кодом. Во время же исполнения модуль представлен соответствующим объектом, атрибутами которого являются:
- Объявления, присутствующие в файле.
- Объекты, импортированные в этот модуль откуда-либо.
При этом определения и импортированные сущности ничем друг от друга не отличаются: и то, и другое — это всего лишь именованные ссылки на некоторые объекты первого класса (такие, которые могут быть переданы из одного участка кода в другой как обычные значения).
Такое единообразие удобно, например, при рефакторинге: мы можем разделить один разросшийся модуль на несколько, а потом импортировать вынесенные определения в оригинальный модуль. При этом с точки зрения внешнего наблюдателя переработанный модуль будет иметь те же атрибуты, которые имел до внесения изменений, а значит у пользователей модуля ничего в коде не сломается.
Модули и видимость содержимого
В Python нет настоящего сокрытия атрибутов объектов, поэтому и атрибуты объекта модуля так или иначе всегда доступны после импорта последнего. Однако существует ряд соглашений, которые влияют на процесс импортирования и поведение инструментов, работающих с кодом.
Так атрибуты, имя которых начинается с одиночного подчёркивания, считаются как бы помеченными "для внутреннего использования", и обычно не отображаются в IDE при обращению к объекту "через точку". И linter обычно предупреждает об использовании таких атрибутов, мол, "небезопасно!". "Опасность" состоит в том, что автор кода имеет полное право изменять состав таких атрибутов без уведомления пользователей кода. Поэтому программист, использовавший в своём коде приватные части чужого кода рискует в какой-то момент получить код, который перестанет работать при обновлении сторонней библиотеки.
Итак, мы можем определять публичные атрибуты модуля, приватные атрибуты (так называют упомянутые выше атрибуты "для внутреннего пользования"). И данное разделение касается не только определений, содержащихся в самом модуле, но и импортируемых сущностей. Ведь все импортированные объекты становятся атрибутами и того модуля, в который они импортированы.
Есть и третья группа атрибутов — атрибуты, добавляемые в область видимости при импортировании всего содержимого модуля ("со звёздочкой", from module import * ). Если ничего явно не указывать, то при таком импортировании в текущую область видимости добавятся все публичные атрибуты модуля. Помимо данного умолчания существует и возможность явно указать, что конкретно будет экспортировано при импорте со звёздочкой. Для управления названным методом импорта существует атрибут __all__ , в который можно положить список (а ещё лучше — кортеж) строк с именами, которые будут экспортироваться.
Живой пример видимости атрибутов модулей.
Рассмотрим пример, демонстрирующий всё вышеописанное. Пусть у нас будет два файла:
Рассмотрим сначала обычный импорт import module . Если импортировать модуль таким образом, то IDE, REPL и остальные инструменты "увидят" у модуля следующие атрибуты:
- FISH , MEAT т.к. имена констант — публичные,
- CAT , т.к. константа импортирована под публичным именем.
А эти атрибуты не будут видны:
- _DOG , т.к. при импортировании константа переименована в приватной манере,
- _GOAT , т.к. импортирована по своему приватному имени (тут линтер может и поругать за обращение к приватному атрибуту модуля!),
- _CARROT , ибо приватная константа.
Импорт import other_module я не рассматриваю как тривиальный случай.
Теперь рассмотрим импорт всего содержимого module:
После импортирования в текущей области видимости мы получим ровно два новых имени: FISH и _CARROT — именно они перечислены в атрибуте __all__ . Заметьте, что в данном случае при массовом импорте добавится даже приватный атрибут, потому что он явно указан!
Последствия импорта from other_module import * тоже очевидны и я их не рассматриваю.
6.1.2. The Module Search Path¶
When a module named spam is imported, the interpreter first searches for a built-in module with that name. These module names are listed in sys.builtin_module_names . If not found, it then searches for a file named spam.py in a list of directories given by the variable sys.path . sys.path is initialized from these locations:
The directory containing the input script (or the current directory when no file is specified).
PYTHONPATH (a list of directory names, with the same syntax as the shell variable PATH ).
The installation-dependent default (by convention including a site-packages directory, handled by the site module).
On file systems which support symlinks, the directory containing the input script is calculated after the symlink is followed. In other words the directory containing the symlink is not added to the module search path.
After initialization, Python programs can modify sys.path . The directory containing the script being run is placed at the beginning of the search path, ahead of the standard library path. This means that scripts in that directory will be loaded instead of modules of the same name in the library directory. This is an error unless the replacement is intended. See section Standard Modules for more information.
import module
Что не было раскрыто?
Я специально не стал рассказывать про
- создание модулей и пакетов на лету (без использования файлов исходников);
- загрузку модулей не с диска, а из других источников;
- расширение подсистемы импортирования с целью загрузки в виде объектов-модулей чего-то, не являющегося кодом вовсе (XML, CSV, JSON).
Темы эти насколько интересны, настолько и велики. На наше счастье, самим разбираться в такой тонкой и сложной машинерии приходится редко. Мы просто пользуемся готовыми магическими артефактами, а зачаровывают их другие :) Если же вы захотите научиться магии, документация вам в руки.
6.4.2. Intra-package References¶
When packages are structured into subpackages (as with the sound package in the example), you can use absolute imports to refer to submodules of siblings packages. For example, if the module sound.filters.vocoder needs to use the echo module in the sound.effects package, it can use from sound.effects import echo .
You can also write relative imports, with the from module import name form of import statement. These imports use leading dots to indicate the current and parent packages involved in the relative import. From the surround module for example, you might use:
Note that relative imports are based on the name of the current module. Since the name of the main module is always "__main__" , modules intended for use as the main module of a Python application must always use absolute imports.
6.4. Packages¶
Packages are a way of structuring Python’s module namespace by using “dotted module names”. For example, the module name A.B designates a submodule named B in a package named A . Just like the use of modules saves the authors of different modules from having to worry about each other’s global variable names, the use of dotted module names saves the authors of multi-module packages like NumPy or Pillow from having to worry about each other’s module names.
Suppose you want to design a collection of modules (a “package”) for the uniform handling of sound files and sound data. There are many different sound file formats (usually recognized by their extension, for example: .wav , .aiff , .au ), so you may need to create and maintain a growing collection of modules for the conversion between the various file formats. There are also many different operations you might want to perform on sound data (such as mixing, adding echo, applying an equalizer function, creating an artificial stereo effect), so in addition you will be writing a never-ending stream of modules to perform these operations. Here’s a possible structure for your package (expressed in terms of a hierarchical filesystem):
When importing the package, Python searches through the directories on sys.path looking for the package subdirectory.
The __init__.py files are required to make Python treat directories containing the file as packages. This prevents directories with a common name, such as string , unintentionally hiding valid modules that occur later on the module search path. In the simplest case, __init__.py can just be an empty file, but it can also execute initialization code for the package or set the __all__ variable, described later.
Users of the package can import individual modules from the package, for example:
This loads the submodule sound.effects.echo . It must be referenced with its full name.
An alternative way of importing the submodule is:
This also loads the submodule echo , and makes it available without its package prefix, so it can be used as follows:
Yet another variation is to import the desired function or variable directly:
Again, this loads the submodule echo , but this makes its function echofilter() directly available:
Note that when using from package import item , the item can be either a submodule (or subpackage) of the package, or some other name defined in the package, like a function, class or variable. The import statement first tests whether the item is defined in the package; if not, it assumes it is a module and attempts to load it. If it fails to find it, an ImportError exception is raised.
Contrarily, when using syntax like import item.subitem.subsubitem , each item except for the last must be a package; the last item can be a module or a package but can’t be a class or function or variable defined in the previous item.
What does __all__ do?
It declares the semantically "public" names from a module. If there is a name in __all__ , users are expected to use it, and they can have the expectation that it will not change.
It also will have programmatic effects:
Documentation tools
Documentation and code autocompletion tools may (in fact, should) also inspect the __all__ to determine what names to show as available from a module.
import module as localname
In the __init__.py file of a package __all__ is a list of strings with the names of public modules or other objects. Those features are available to wildcard imports. As with modules, __all__ customizes the * when wildcard-importing from the package. [@MartinStettner]
Here's an excerpt from the Python MySQL Connector __init__.py :
The default case, asterisk with no __all__ for a package, is complicated, because the obvious behavior would be expensive: to use the file system to search for all modules in the package. Instead, in my reading of the docs, only the objects defined in __init__.py are imported:
If __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.
And lastly, a venerated tradition for stack overflow answers, professors, and mansplainers everywhere, is the bon mot of reproach for asking a question in the first place:
Wildcard imports . should be avoided, as they [confuse] readers and many automated tools.
I really like this answer, but I'm missing the information on what's the default behavior for from
Thanks @Jatimir, I clarified as best I could without running experiments. I almost wanted to say this case (asterisk without all for a package) behaves the same as if __init__.py were a module. But I'm not sure that's accurate, or in particular if underscore-prefixed objects are excluded. Also, I more clearly separated the sections on MODULES and PACKAGES. Your thoughts?
The public names defined by a module are determined by checking the module's namespace for a variable named __all__ ; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module's namespace which do not begin with an underscore character ("_"). __all__ should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).
__all__ affects from import * statements.
Consider this example:
(Implicit) If we don't define __all__ , then from foo import * will only import names defined in foo/__init__.py .
(Explicit) If we define __all__ = [] , then from foo import * will import nothing.
(Explicit) If we define __all__ = [ , . ] , then from foo import * will only import those names.
Note that in the implicit case, python won't import names starting with _ . However, you can force importing such names using __all__ .
You can view the Python document here.
__all__ is used to document the public API of a Python module. Although it is optional, __all__ should be used.
Here is the relevant excerpt from the Python language reference:
The public names defined by a module are determined by checking the module’s namespace for a variable named __all__ ; if defined, it must be a sequence of strings which are names defined or imported by that module. The names given in __all__ are all considered public and are required to exist. If __all__ is not defined, the set of public names includes all names found in the module’s namespace which do not begin with an underscore character ('_'). __all__ should contain the entire public API. It is intended to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module).
PEP 8 uses similar wording, although it also makes it clear that imported names are not part of the public API when __all__ is absent:
To better support introspection, modules should explicitly declare the names in their public API using the __all__ attribute. Setting __all__ to an empty list indicates that the module has no public API.
[. ]
Imported names should always be considered an implementation detail. Other modules must not rely on indirect access to such imported names unless they are an explicitly documented part of the containing module's API, such as os.path or a package's __init__ module that exposes functionality from submodules.
Furthermore, as pointed out in other answers, __all__ is used to enable wildcard importing for packages:
The import statement uses the following convention: if a package’s __init__.py code defines a list named __all__ , it is taken to be the list of module names that should be imported when from package import * is encountered.
If you quit from the Python interpreter and enter it again, the definitions you have made (functions and variables) are lost. Therefore, if you want to write a somewhat longer program, you are better off using a text editor to prepare the input for the interpreter and running it with that file as input instead. This is known as creating a script. As your program gets longer, you may want to split it into several files for easier maintenance. You may also want to use a handy function that you’ve written in several programs without copying its definition into each program.
To support this, Python has a way to put definitions in a file and use them in a script or in an interactive instance of the interpreter. Such a file is called a module; definitions from a module can be imported into other modules or into the main module (the collection of variables that you have access to in a script executed at the top level and in calculator mode).
A module is a file containing Python definitions and statements. The file name is the module name with the suffix .py appended. Within a module, the module’s name (as a string) is available as the value of the global variable __name__ . For instance, use your favorite text editor to create a file called fibo.py in the current directory with the following contents:
Now enter the Python interpreter and import this module with the following command:
This does not enter the names of the functions defined in fibo directly in the current symbol table; it only enters the module name fibo there. Using the module name you can access the functions:
If you intend to use a function often you can assign it to a local name:
6.1.1. Executing modules as scripts¶
When you run a Python module with
the code in the module will be executed, just as if you imported it, but with the __name__ set to "__main__" . That means that by adding this code at the end of your module:
you can make the file usable as a script as well as an importable module, because the code that parses the command line only runs if the module is executed as the “main” file:
If the module is imported, the code is not run:
This is often used either to provide a convenient user interface to a module, or for testing purposes (running the module as a script executes a test suite).
import *
__all__ in a module, e.g. module.py :
means that when you import * from the module, only those names in the __all__ are imported:
__all__ in __init__.py
After more work, maybe you've decided that the modules are too big (like many thousands of lines?) and need to be split up. So you do the following:
First make the subpackage directories with the same names as the modules:
Move the implementations:
create __init__.py s for the subpackages that declare the __all__ for each:
And now you still have the api provisioned at the package level:
And you can easily add things to your API that you can manage at the subpackage level instead of the subpackage's module level. If you want to add a new name to the API, you simply update the __init__.py , e.g. in module_2:
And if you're not ready to publish Baz in the top level API, in your top level __init__.py you could have:
and if your users are aware of the availability of Baz , they can use it:
but if they don't know about it, other tools (like pydoc) won't inform them.
You can later change that when Baz is ready for prime time:
By default, Python will export all names that do not start with an _ when imported with import * . As demonstrated by the shell session here, import * does not bring in the _us_non_public name from the us.py module:
You certainly could rely on this mechanism. Some packages in the Python standard library, in fact, do rely on this, but to do so, they alias their imports, for example, in ctypes/__init__.py :
Using the _ convention can be more elegant because it removes the redundancy of naming the names again. But it adds the redundancy for imports (if you have a lot of them) and it is easy to forget to do this consistently - and the last thing you want is to have to indefinitely support something you intended to only be an implementation detail, just because you forgot to prefix an _ when naming a function.
I personally write an __all__ early in my development lifecycle for modules so that others who might use my code know what they should use and not use.
Most packages in the standard library also use __all__ .
It makes sense to stick to the _ prefix convention in lieu of __all__ when:
- You're still in early development mode and have no users, and are constantly tweaking your API.
- Maybe you do have users, but you have unittests that cover the API, and you're still actively adding to the API and tweaking in development.
The downside of using __all__ is that you have to write the names of functions and classes being exported twice - and the information is kept separate from the definitions. We could use a decorator to solve this problem.
I got the idea for such an export decorator from David Beazley's talk on packaging. This implementation seems to work well in CPython's traditional importer. If you have a special import hook or system, I do not guarantee it, but if you adopt it, it is fairly trivial to back out - you'll just need to manually add the names back into the __all__
So in, for example, a utility library, you would define the decorator:
and then, where you would define an __all__ , you do this:
And this works fine whether run as main or imported by another function.
And API provisioning with import * will work too:
Cross reference: I mentioned your decorator in this CW answer to the question of how to write an @export decorator.
This has single handedly been the most helpful answer I have seen in regards to helping a relatively new python developer understand the process of importing modules/packages with __init__.py and the use of __all__
This helps me a lot. My problem, tho, is that the submodules I want to import are all generated files with a lot of cruft in their symbols that I'd like to strip out, without having to manually ensure that __all__ is correct.
@MikeC then maybe you should generate your __all__ too - but then I would say you have an unstable API. This would be something to have some comprehensive acceptance tests on.
@AaronHall "they won't have all the other names . cluttering up the package namespace" But they will have the names module_1 and module_2 ; is it OK to include an explicit del module_1 in __init__.py ? Am I wrong to think this is worthwhile?
I'm just adding this to be precise:
All other answers refer to modules. The original question explicitely mentioned __all__ in __init__.py files, so this is about python packages.
Generally, __all__ only comes into play when the from xxx import * variant of the import statement is used. This applies to packages as well as to modules.
The behaviour for modules is explained in the other answers. The exact behaviour for packages is described here in detail.
In short, __all__ on package level does approximately the same thing as for modules, except it deals with modules within the package (in contrast to specifying names within the module). So __all__ specifies all modules that shall be loaded and imported into the current namespace when us use from package import * .
The big difference is, that when you omit the declaration of __all__ in a package's __init__.py , the statement from package import * will not import anything at all (with exceptions explained in the documentation, see link above).
On the other hand, if you omit __all__ in a module, the "starred import" will import all names (not starting with an underscore) defined in the module.
from package import * will still import everything defined in __init__.py , even if there is no all . The important difference is that without __all__ it will not automatically import any modules defined in package's directory.
When all contains [foo, bar] and in test.py file if we use: from package import *, then, do foo and bar get imported in the local namespace of test.py or in the foo and bars own namespace?
It also changes what pydoc will show:
I declare __all__ in all my modules, as well as underscore internal details, these really help when using things you've never used before in live interpreter sessions.
A module is a .py file meant to be imported.
A package is a directory with a __init__.py file. A package usually contains modules.
__all__ lets humans know the "public" features of a module. [@AaronHall] Also, pydoc recognizes them. [@Longpoke]
6.1.3. “Compiled” Python files¶
To speed up loading modules, Python caches the compiled version of each module in the __pycache__ directory under the name module. version .pyc , where the version encodes the format of the compiled file; it generally contains the Python version number. For example, in CPython release 3.3 the compiled version of spam.py would be cached as __pycache__/spam.cpython-33.pyc . This naming convention allows compiled modules from different releases and different versions of Python to coexist.
Python checks the modification date of the source against the compiled version to see if it’s out of date and needs to be recompiled. This is a completely automatic process. Also, the compiled modules are platform-independent, so the same library can be shared among systems with different architectures.
Python does not check the cache in two circumstances. First, it always recompiles and does not store the result for the module that’s loaded directly from the command line. Second, it does not check the cache if there is no source module. To support a non-source (compiled only) distribution, the compiled module must be in the source directory, and there must not be a source module.
Some tips for experts:
You can use the -O or -OO switches on the Python command to reduce the size of a compiled module. The -O switch removes assert statements, the -OO switch removes both assert statements and __doc__ strings. Since some programs may rely on having these available, you should only use this option if you know what you’re doing. “Optimized” modules have an opt- tag and are usually smaller. Future releases may change the effects of optimization.
A program doesn’t run any faster when it is read from a .pyc file than when it is read from a .py file; the only thing that’s faster about .pyc files is the speed with which they are loaded.
The module compileall can create .pyc files for all modules in a directory.
There is more detail on this process, including a flow chart of the decisions, in PEP 3147.
Наконец-то, пакеты!
Пакет в Python — директория с обязательным модулем __init__.py . Остальное содержимое опционально и может включать в себя и модули, и другие пакеты.
Импортирование пакетов
Пакет с единственным модулем __init__.py при импорте ведёт себя как обычный модуль. Содержимое инициализирующего модуля определяет атрибуты объекта пакета.
Прочие модули пакета и вложенные пакеты не импортируются автоматически вместе с пакетом-родителем, но могут быть импортированы отдельно с указанием полного имени. Важный момент: при импортировании вложенного модуля всегда сначала импортируются модули инициализации всех родительских пакетов (если оные ещё ни разу не импортировались, но об этом я расскажу ниже).
Рассмотрим, к примеру, следующую структуру директорий и файлов:
Когда мы импортируем модуль submodule.py , то фактически происходит следующее (именно в таком порядке):
- загружается и выполняется модуль package/__init__.py ,
- загружается и выполняется package/subpackage/__init__.py ,
- наконец, импортируется package/subpackage/submodule.py .
При импорте package.module предварительно загружается только package/__init__.py .
Так что же, если мы загрузим парочку вложенных модулей, то для каждого будет выполняться загрузка всех __init__.py по дороге? Не будет! Подсистема интерпретатора, отвечающая за загрузку модулей, кэширует уже загруженные пакеты и модули. Каждый конкретный модуль загружается ровно один раз, в том числе и инициализирующие модули __init__.py (короткие имена модулей хоть и одинаковы, но полные имена всегда разные). Все последующие импортирования модуля не приводят к его загрузке, только лишь нужные атрибуты копируются в соответствующие области видимости.
Пакеты и __all__
В целом атрибут __all__ в модуле инициализации пакета ведёт себя так же, как и в случае с обычным модулем. Но если при импорте пакета "со звёздочкой" среди перечисленных имён встретится имя вложенного модуля, а сам модуль не окажется импортирован ранее в этом же __init__.py , то этот модуль импортируется неявно! Очередной пример это продемонстрирует.
Вот структура пакета:
Файл же package/__init__.py содержит следующее (и только это!):
А импортируем мы from package import * . В области видимости у нас окажутся объекты модулей a и b под своими именами (без полного пути, то есть без package. ). При этом сами модули в коде нигде явно не импортируются! Такая вот "автомагия".
Указанный автоматизм достаточно ограничен: не работает "вглубь", например — не импортирует "через звёздочку" указанные модули и подпакеты. Если же вам вдруг такого захочется, вы всегда сможете на соответствующих уровнях в __init__.py сделать from x import * и получить в корневом пакете плоскую область видимости со всем нужным содержимым. Но такое нужно довольно редко, потому что "не помогает" ни IDE, ни ручному поиску по коду. Впрочем, знать о фиче и иметь её в виду — не вредно, как мне кажется.
Изучайте Python на Хекслете Первые курсы в профессии Python-программист доступны бесплатно сразу после регистрации. Начните сегодня, учитесь в комфортном для вас темпе.
6.2. Standard Modules¶
Python comes with a library of standard modules, described in a separate document, the Python Library Reference (“Library Reference” hereafter). Some modules are built into the interpreter; these provide access to operations that are not part of the core of the language but are nevertheless built in, either for efficiency or to provide access to operating system primitives such as system calls. The set of such modules is a configuration option which also depends on the underlying platform. For example, the winreg module is only provided on Windows systems. One particular module deserves some attention: sys , which is built into every Python interpreter. The variables sys.ps1 and sys.ps2 define the strings used as primary and secondary prompts:
These two variables are only defined if the interpreter is in interactive mode.
The variable sys.path is a list of strings that determines the interpreter’s search path for modules. It is initialized to a default path taken from the environment variable PYTHONPATH , or from a built-in default if PYTHONPATH is not set. You can modify it using standard list operations:
Поиск пакетов и модулей
Пайтон ищет модули и пакеты в директориях, во время исполнения перечисленных в списке sys.path — по порядку от первого пути к последнему.
В этом списке пути до стандартных библиотек обычно расположены раньше, чем директории со сторонними пакетами, чтобы нельзя было случайно заменить стандартный пакет сторонним (помним: кто первый, того и тапки — среди нескольких с одинаковыми именами загружается первый попавшийся пакет).
В списке путей (обычно в начале) присутствует и путь '' , означающий текущую директорию. Это, в свою очередь, означает, что модули и пакет в текущем проекте имеют больший приоритет.
Обычно пути трогать не нужно, всё вполне нормально "работает само". Но если очень хочется, то путей у вас несколько:
- Использовать переменную окружения PYTHONPATH (значение — строка с путями, разделёнными символом : ),
- Во время исполнения изменить sys.path .
Первый способ — простой и понятный. Не сложнее добавления пути до исполняемых файлов в PATH (даже синтаксис тот же).
Второй способ — сложный и требующий внимательности. Дело в том, что sys.path нужно изменять максимально рано — где-нибудь в точке входа. Если не торопиться менять sys.path , то что-то уже может успеть загрузиться до того, как вы перестроите пути для поиска пакетов. А ведь эта загрузка может произойти в другом потоке исполнения! Отлаживать проблемы с очерёдностью загрузки модулей сложно. Лучше просто их не создавать.
Кстати, когда вы используете виртуальные окружения, sys.path будет содержать пути до локальных копий стандартных библиотек. Именно это позволяет виртуальному окружению быть самодостаточным (работать на любой машине с подходящей ОС — даже без установленного в систему Python!).
__init__.py makes a directory a Python package
The __init__.py files are required to make Python treat the directories as containing packages; this is done to prevent directories with a common name, such as string, from unintentionally hiding valid modules that occur later on the module search path.
In the simplest case, __init__.py can just be an empty file, but it can also execute initialization code for the package or set the __all__ variable.
So the __init__.py can declare the __all__ for a package.
A package is typically made up of modules that may import one another, but that are necessarily tied together with an __init__.py file. That file is what makes the directory an actual Python package. For example, say you have the following files in a package:
Let's create these files with Python so you can follow along - you could paste the following into a Python 3 shell:
And now you have presented a complete api that someone else can use when they import your package, like so:
And the package won't have all the other implementation details you used when creating your modules cluttering up the package namespace.
from module import *
See how swiss and cheddar are brought into the local namespace, but not gouda :
Without __all__ , any symbol (that doesn't start with an underscore) would have been available.
Читайте также: