Python ошибка импорта своего модуля

Сегодня мы поговорим о том, как импортировать пакеты и модули в Python (а заодно и о разнице между ними). К концу руководства вы получите структуру каталогов (для проекта Medium_Imports_Tutorial), где будет удобно импортировать любые скрипты из одного подкаталога в другой (стрелки синего цвета на картинке ниже).

Примечание. Если вы хотите поиграться с кодом, то вот репозиторий Github.

Итак, наша структура каталогов для изучения импорта в Python будет выглядеть следующим образом:

Прежде чем начать, давайте обсудим, в чем разница между пакетом и модулем, так как мы будем опираться на эти понятия на протяжении всей статьи.

• Модуль — один скрипт Python.
• Пакет — набор модулей.

Вот и вся разница! Просто, не правда ли?

Что ж, теперь давайте начинать!

[python_ad_block]

Импорт в рамках одного каталога

Структура каталогов на изображении выше выглядит немного сложной, но мы не будем создавать ее всю сразу.

Для простоты давайте сначала создадим один каталог scripts в каталоге нашего проекта и добавим в него два модуля — example1.py и example2.py. Наша структура будет выглядеть так:

Идея состоит в том, чтобы любая функция/переменная/класс, определенные в example1.py, были доступны в example2.py. Содержимое у нас будет таким:

#example1.py
MY_EX1_STRING = 'Welcome to Example1 module!'
def yolo(x: int):
     print("You only LIve", x, "times.")

Чтобы импортировать эти элементы в example2.py, сделаем следующее:

#example2.py
import example1
# imported string
print("The imported string is: ", example1.MY_EX1_STRING)
# imported function
example1.yolo(10)

Как видно, доступ к элементам в импортированном модуле можно получить с помощью записи через точку — например, example1.yolo() или example1.MY_EX1_STRING. Если вам покажется, что каждый раз писать example1.XXX утомительно, можно воспользоваться псевдонимом (созданным при помощи as) и переписать example2.py следующим образом:

#example2.py
import example1 as e1
# imported string
print("The imported string is: ", e1.MY_EX1_STRING)
# imported function
e1.yolo(10)

Как вы правильно догадались, вывод останется прежним.

Но что именно происходит, когда мы пишем оператор import?

Интерпретатор Python пытается найти в sys.path каталог с модулем, который мы пытаемся импортировать. sys.path — это список каталогов, в которых Python будет искать после просмотра кэшированных модулей и модулей стандартной библиотеки Python.

Давайте посмотрим, что в данный момент содержит наш системный путь sys.path (предварительно закомментировав предыдущие строки кода в example2.py).

#example2.py
# import example1
# print("The imported string is: ", example1.MY_EX1_STRING)
# example1.yolo(10)
import sys
print(sys.path)

Как видите, самый первый элемент в полученном списке sys.path указывает на каталог Medium_Imports_Tutorial/scripts, в котором находится наш импортированный модуль, т. е. example1.py. Имейте в виду: то, что этот каталог волшебным образом присутствует в sys.path, не случайно.

Вывод из sys.path всегда будет содержать текущий каталог с индексом 0! Текущий каталог — это тот, в котором находится запускаемый скрипт.

Поэтому, когда и вызывающий, и вызываемый модули находятся в одном каталоге, импорт довольно прост.

Что делать, если нужно импортировать только определенные элементы из модуля?

В нашем примере в модуле example1.py определены только переменная типа string и функция. Важно помнить, что всякий раз, когда выполняется оператор импорта, будет запущен весь модуль. Чтобы доказать это, давайте немного изменим example1.py:

#example1.py
print("Thanks for importing Example1 module.")
MY_EX1_STRING = 'Welcome to Example1 module!'
def yolo(x: int):
     print("You only LIve", x, "times.")
yolo(10000)

А теперь попробуйте запустить example2.py. Вы увидите, что вместе с выводом оператора print() также выведется yolo(10000).

Примечание. Существует обходной путь, с помощью которого мы можем контролировать, будет ли оператор выполняться при импорте. 

#example1.py
print("Thanks for importing Example1 module.")
MY_EX1_STRING = 'Welcome to Example1 module!'
def yolo(x: int):
     print("You only LIve", x, "times.")
if __name__ == '__main__':
     yolo(10000)

Код внутри оператора if__name__ == '__main__' не будет выполняться при импорте, но yolo() и MY_EX1_STRING, определенные снаружи, готовы к использованию через импорт. При этом, если бы мы запустили example1.py как автономный модуль, код внутри оператора if был бы выполнен.

Итак, мы увидели, что импорт модуля запускает все его содержимое (если не использовать if __name__ == «__main__»). Теперь должно быть довольно понятно, почему импорт только интересующих элементов имеет смысл. Давайте посмотрим, как это сделать в example2.py. Для этого импортируем из example1.py только функцию yolo(). Это также поможет нам избавиться от записи через точку, и мы сможем просто использовать функцию yolo().

#example2.py
from example1 import yolo
yolo(10)

Точно так же мы могли бы написать from example1 import yolo, MY_EX1_STRING, чтобы импортировать оба объекта из example1.py.

Примечание. В коде часто можно увидеть такие импорты, как from example1 import *. По сути, это означает импорт всего. Но это считается плохой практикой, поскольку негативно влияет на читабельность кода.

Зачем нужен PYTHONPATH?

Возможно, вы замечали, что в структуре каталогов проектов на GitHub часто бывает каталог utils. Он содержит служебные скрипты для распространенных задач, таких как предварительная обработка и очистка данных. Они хранятся отдельно от основных сценариев и предназначены для многократного использования.

Давайте создадим такой каталог для нашего проекта.

Пакет utils будет содержать три модуля — length.py, lower.py и upper.py для возврата длины строки и строк в нижнем и верхнем регистре соответственно.

Также создадим модуль example3_outer.py в корне проекта. Сюда мы будем импортировать модули из пакета utils.

Содержимое трех модулей будет следующим:

#utils/length.py
def get_length(name: str):
    return len(name)
#utils/lower.py
def to_lower(name: str):
    return name.lower()
#utils/upper.py
def to_upper(name: str):
    return name.upper()

Теперь, чтобы импортировать модуль length.py в example3_outer.py, пишем следующее:

#example3_outer.py
import utils.length
res = utils.length.get_length("Hello")
print("The length of the string is: ",res)

Важно отметить, что если бы мы выполнили импорт length вместо импорта utils.length, мы получили бы ModuleNotFoundError: No module named ‘length’. Это связано с тем, что список sys.path пока не содержит каталога ../Medium_Imports_Tutorial/utils, который необходим для поиска модуля length.py. Давайте посмотрим, как мы можем добавить его в этот список.

Есть два способа сделать это.

Способ 1: использование sys.path.append

#example3_outer.py
import os
import sys
fpath = os.path.join(os.path.dirname(__file__), 'utils')
sys.path.append(fpath)
print(sys.path)
import length
txt = "Hello"
res_len = length.get_length(txt)
print("The length of the string is: ",res_len)

Несколько вещей, которые следует учесть:

1. Порядок импорта важен. Мы сможем выполнить import length только после добавления пути к каталогу utils с помощью sys.path.append. 

Короче говоря, не поддавайтесь искушению объединить import os, import sys и import length в верхней части скрипта только для аккуратности!

2. os.path.dirname(__file__) возвращает абсолютный путь к текущему рабочему каталогу. Мы используем os.path.join, чтобы добавить каталог utils к этому пути.

3. Как всегда, доступ к функциям, определенным в импортированном модуле, упрощается с помощью записи через точку, т.е. length.get_length().

Способ 2: использование переменной окружения PYTHONPATH

Однако зачастую проще изменить переменную PYTHONPATH, чем возиться с добавлением каталогов, как мы это только что делали.

PYTHONPATH — это переменная среды, которую вы можете настроить для добавления дополнительных каталогов, в которых Python будет искать модули и пакеты.

Прежде чем изменить PYTHONPATH, давайте проверим его содержимое при помощи команды echo $PYTHONPATH в терминале (чтобы случайно не перезаписать):

Похоже, сейчас PYTHONPATH пуст, но если это не так, лучше изменять его путем дополнения, а не перезаписи. Для этого нужно добавлять новый каталог в PYTHONPATH, отделяя его двоеточием от существующего содержимого.

С установленной переменной PYTHONPATH нам больше не нужно добавлять каталог к sys.path в example3_outer.py (мы закомментировали этот код в приведенном ниже фрагменте для ясности).

#example3_outer.py
#import os
#import sys
#fpath = os.path.join(os.path.dirname(__file__), 'utils')
#sys.path.append(fpath)
#print(sys.path)
import length
txt = "Hello"
res_len = length.get_length(txt)
print("The length of the string is: ",res_len)

Примечание. Как только вы закроете python, список вернется к предыдущим значениям по умолчанию. Если вы хотите добавить каталог в PYTHONPATH навсегда, добавьте команду экспорта (export PYTHONPATH=$PYTHONPATH:$(pwd)/utils) в файл ~/.bashrc. (подробнее можно почитать обсуждение на StackOverflow).

Наконец, познакомившись с обоими методами, давайте выберем один (в зависимости от ваших предпочтений и нужд) для импорта оставшихся двух модулей — upper.py и lower.py в example3_outer.py.

P.S. Мы воспользуемся методом 1 просто для удовольствия 😉

#example3_outer.py
import os
import sys
fpath = os.path.join(os.path.dirname(__file__), 'utils')
sys.path.append(fpath)
import length
import upper
import lower
txt = "Hello"
res_len = length.get_length(txt)
print("The length of the string is: ",res_len)
res_up = upper.to_upper(txt)
print("Uppercase txt: ", res_up)
res_low = lower.to_lower(txt)
print("Uppercase txt: ", res_low)

Супер! Это выглядит потрясающе. Однако было бы здорово, если бы мы могли просто выполнить команду import utils вместо того, чтобы импортировать все модули по отдельности. В конце концов, наш случай использования предполагает, что нам нужны все три функции. Итак, как это сделать?

Когда нам нужен __init__.py?

Во-первых, давайте попробуем импортировать каталог utils в файле example3_outer.py (предварительно закомментировав весь существующий код):

#example3_outer.py
import utils

Запуск этого скрипта не вызовет никакой ошибки, и это правильно — интерпретатор заглянет внутрь sys.path и найдет текущий каталог ../Medium_Imports_Tutorial с индексом 0. Это все, что ему нужно, чтобы найти каталог utils.

Теперь попробуем получить доступ к модулю length.py из utils:

#example3_outer.py
import utils
txt = "Hello"
res = utils.length.get_length(txt)

Попытавшись запустить этот скрипт, вы увидите AttributeError: module ‘utils’ has no attribute ‘length’. Это означает, что мы не сможем получить доступ к каким-либо скриптам Python внутри utils просто потому, что интерпретатор еще не знает, что это пакет!

Мы можем превратить этот каталог в пакет, добавив файл __init__.py в папку utils следующим образом:

В __init__.py мы импортируем все модули, которые, по нашему мнению, необходимы для нашего проекта.

# utils/__init__.py (incorrect way of importing)
from length import get_length
from lower import to_lower
from upper import to_upper

И сделаем вызов в example3_outer.py.

import utils
txt = "Hello"
res_low = utils.to_lower(txt)
print(res_low)

Подождите секунду! Почему мы видим ошибку при запуске example3_outer.py?

Ошибки импорта

То, как мы импортировали модули в __init__.py, может показаться логичным. Ведь __init__.py и length.py (или lower.py, upper.py) находятся на одном уровне, так что нет ни одной причины, чтобы from lower import to_lower не сработал. На самом деле, если вы запустите этот файл инициализации сам по себе, он будет выполняться безупречно (он не даст никаких результатов, но, тем не менее, будет успешно выполнен).

Но при этом мы не можем использовать описанный выше способ импорта, потому что, хотя length.py и lower.py находятся на том же уровне, что и __init__.py, это не тот уровень, с которого будет вызываться init.

В действительности, мы делаем вызов из example3_outer.py, поэтому для поиска любого импорта в sys.path будет только текущий каталог example3_outer.py, т.е. ../Medium_Imports_Tutorial.

Когда интерпретатор встречает команду import utils в файле example3_outer.py, даже если он переходит к __init__.py внутри каталога utils, sys.path не обновляется автоматически, и, следовательно, интерпретатор не может узнать, где найти модуль с именем length.

Мы должны как-то указать на расположение каталога utils. Для этого мы можем использовать относительный или абсолютный импорт в __init__.py (или установить переменную PYTHONPATH, как это было описано выше).

Относительный импорт

Мы не рекомендуем использовать относительный импорт, но для общего развития давайте посмотрим, как он работает. Тут нужно указать путь относительно пути вызывающего скрипта. Выглядеть это будет так:

# utils/__init__.py
from .lower import to_lower
from .upper import to_upper
from .length import get_length

При указании относительного импорта мы используем запись через точку (. или ..). Одиночная точка перед lower указывает на тот же каталог, из которого вызывается импорт. Это можно представить как импорт функции to_lower() из ./lower.py. Пара точек перед названием модуля означает переход на два уровня вверх от текущего.

Абсолютный импорт

Абсолютный импорт более предпочтителен. Вы указываете абсолютный путь к импортируемому модулю из корня проекта (или любого другого каталога, к которому имеет доступ sys.path):

# utils/__init__.py
from utils.lower import to_lower
from utils.upper import to_upper
from utils.length import get_length

Теперь у программы есть гораздо больше информации по сравнению с относительным импортом. Более того, она менее подвержена взлому. sys.path имеет доступ к корню проекта, т. е. ../Medium_Imports_Tutorial, как описано выше, и оттуда он может легко найти каталог utils. (Почему? Потому что это непосредственный дочерний каталог корня проекта).

Что происходит, когда мы импортируем пакет с определенным __init__.py? 

Это работает как шаг инициализации. __init__.py — первый файл, который будет выполняться при импорте пакета. Учитывая, что здесь мы делаем весь необходимый импорт, код в вызывающем скрипте становится намного чище. К примеру, example3_outer.py будет выглядеть так:

#example3_outer.py
import utils
txt = "Hello"
res_len = utils.get_length(txt)
print(res_len)
res_up = utils.to_upper(txt)
print(res_up)
res_low = utils.to_lower(txt)
print(res_low)

Потрясающе! Мы преобразовали наш каталог utils в пакет. Прелесть этого пакета в том, что его можно импортировать куда угодно и использовать практически сразу. Давайте посмотрим, как мы можем использовать этот пакет внутри каталога scripts. Для этого создадим новый файл с именем example3.py в scripts.

# scripts/example3.py
import os
import sys
PROJECT_ROOT = os.path.abspath(os.path.join(
                  os.path.dirname(__file__), 
                  os.pardir)
)
sys.path.append(PROJECT_ROOT)

import utils
print(utils.get_length("Hello"))
************** OUTPUT *********
5

Несколько вещей, которые следует учитывать:

• Перед импортом пакета utils мы должны убедиться, что родительский каталог utils, т.е. корень проекта, доступен для интерпретатора Python. Было бы неосмотрительно предполагать, что это произойдет по умолчанию, в основном потому, что мы сейчас находимся на один уровень ниже корневого каталога проекта (мы запускаем скрипт из scripts/example3.py), и в sys.path под индексом 0 будет ../Medium/Imports_Tutorial/scripts.
• os.path.dirname(__file__) даст имя каталога для текущего скрипта, а os.pardir даст путь к родительскому каталогу, используя точечную нотацию, т.е. .. . В общем, os.path.abspath будет предоставлять абсолютный путь к корню проекта.

Бонус: мы даже можем добавлять в наш __init__.py модули из других каталогов. Например, давайте добавим yolo(), определенный в scripts/example1.py.

# utils/__init__.py
from utils.lower import to_lower
from utils.upper import to_upper
from utils.length import get_length
from scripts.example1 import yolo

Вызов этой функции в example3.py будет выглядеть следующим образом:

# scripts/example3.py
import os
import sys
PROJECT_ROOT = os.path.abspath(os.path.join(
                  os.path.dirname(__file__), 
                  os.pardir)
)
sys.path.append(PROJECT_ROOT)
import utils
print(utils.get_length("Hello"))
utils.yolo(2)
************** OUTPUT *********
5
You only LIve 2 times.

Заключение

Итак, сегодня мы обсудили, как импортировать в Python. Честно говоря, поначалу ошибки импорта действительно пугают, потому что это та область, о которой не так много говорят. Однако есть один полезный прием: какой бы пакет/модуль вы ни пытались импортировать с помощью import XYZ, убедитесь, что интерпретатор Python имеет к нему доступ. Если нет, обновите sys.path или, что еще лучше, добавьте соответствующий каталог в переменную PYTHONPATH.

Надеемся, данная статья была полезна для вас! Успехов в написании кода!

Перевод статьи «Understanding Python imports, __init__.py and pythonpath — once and for all».