Модули и библиотеки: import – Учебник

8.5

О чём этот урок

Программа считает площадь круга – и упирается в квадратный корень. Написать его самим? Алгоритм извлечения корня придуман задолго до нас: его написали один раз, проверили на миллионах примеров и положили в Python. Осталось только попросить.

Так же со случайным числом: жребий, кубик в игре, выбор варианта – это тоже кто-то уже написал. Так же с сегодняшней датой: её умеет выдавать сама машина, и нужен лишь правильный вопрос.

Ни одну из этих вещей не пишут заново. Все они лежат рядом – в файлах, которые идут в комплекте с Python, – а подключить их к своей программе умеет одна строка. Именно поэтому программа на Python из десяти строк делает то, на что в другом языке ушли бы сотни.

В этом уроке: что такое модуль и библиотека и чем от них отличается стандартная библиотека; три формы записи import и разница между ними; почему не пишут from math import *; какие модули уже под рукой, а какие приходится ставить командой pip install; что означает ModuleNotFoundError; главная ловушка – свой файл, названный именем модуля и незаметно подменивший собой стандартный.

Модуль, пакет, библиотека

До сих пор вся программа жила в одном файле. Но код, который нужен второй и третий раз, выносят в отдельный файл – и подключают его к новому.

Модуль – файл с кодом на Python, готовый к подключению: в нём лежат функции и значения, которыми можно пользоваться из другой программы.

Библиотека – набор модулей, собранных вместе по одной теме: математика – в одном наборе, работа с датами – в другом.

Стандартная библиотека – модули, которые идут в комплекте с Python. Их не нужно нигде брать и ставить: они уже лежат на компьютере рядом с самим языком.

Сторонняя библиотека – модули, которые написали другие люди и выложили отдельно. Её скачивают и устанавливают сами.

Слово «пакет» значит примерно то же, что «библиотека»: несколько модулей вместе. В Python у него есть и более точное значение, но для нас пока важно одно: модуль – это файл, а библиотека – это много файлов.

Верно и обратное: наша собственная программа – обычный файл с кодом, то есть тоже модуль. Написанное сегодня можно завтра подключить к другому файлу – ровно так же, как подключают math.

Три формы импорта

Подключает модуль слово import – «импортировать», то есть ввезти. Записать это можно тремя способами, и отличаются они не смыслом, а тем, как потом выглядит обращение.

Запись	Как потом обращаться	Когда так пишут
`import math`	`math.sqrt(16)` – через имя модуля и точку	когда из модуля нужно много всего или когда важно, чтобы в каждой строке было видно, откуда взялась функция
`from math import sqrt`	`sqrt(16)` – сразу по имени	когда из модуля нужна одна-две функции и имя модуля в строке только мешает
`import math as m`	`m.sqrt(16)` – по короткому имени	когда имя модуля длинное и встречается в программе постоянно

Каждая запись читается как фраза: import math – «импортировать math»; from math import sqrt – «из math импортировать sqrt»; import math as m – «импортировать math как m».

Во второй форме можно перечислить сразу несколько имён через запятую: from math import sqrt, pi. Ввозится при этом ровно то, что назвали, – ни больше ни меньше.

Короткое имя через as – та же первая форма, только подписанная другим словом. Библиотека числовых массивов numpy (блок 19) в каждой строке превращается в np: ввозим тот же модуль, а пишем короче. Экономия тут не главное – as ставят там, где имя модуля длинное, и весь мир читает np как «numpy».

Разница во второй колонке – это не мелочь оформления, а подсказка читателю. math.sqrt(x) говорит: «это чужая функция, она из модуля math». Запись sqrt(x) говорит только «это sqrt»: своя она или чужая – из строки не видно, и искать её приходится по всему файлу.

# 1. import модуль – обращение через имя модуля
import math

print(math.sqrt(16))     # 4.0 – корень из 16
print(math.floor(3.7))   # 3 – округление вниз
print(math.pi)           # 3.141592653589793 – число пи
# в каждой строке видно, откуда взялась функция

# 2. from модуль import имя – обращение сразу по имени
from math import sqrt, pi

print(sqrt(144))         # 12.0
print(pi)                # 3.141592653589793
# короче – но по записи sqrt(144) уже не сказать,
# своя это функция или чужая

# 3. import модуль as короткое_имя – та же первая форма,
#    только имя короче
import math as m

print(m.sqrt(144))       # 12.0
print(m.pi)              # 3.141592653589793

Почему не пишут `from math import *`

У import есть четвёртая форма, о которой надо знать ровно для того, чтобы её не писать:

from math import *

Звёздочка значит «всё, что есть в модуле». Python при этом не выдаст ни ошибки, ни предупреждения – программа, скорее всего, заработает. Плохо здесь не для машины, а для человека.

Имена сваливаются в общую кучу. В math их десятки, и после такой строки в программе разом появляются sqrt, floor, pi, e, sin, log и ещё два десятка имён. Какое из них что делает – видно только по документации.

Они незаметно перекрывают друг друга. Если два модуля объявили имя с одинаковым названием – а такое случается, – победит тот, что был импортирован последним. Программа не упадёт: она начнёт считать не то.

Читатель не может понять, откуда имя. Увидев sqrt(16), он не знает, своя это функция, из math или из другого модуля: больше такого имени в тексте программы нигде нет.

Поэтому имена перечисляют явно:

from math import sqrt, floor, pi

Строка длиннее – зато видно и что ввезли, и откуда. Это как список покупок: лучше перечислить, чем написать «всё из магазина».

Стандартная библиотека

Вот модули, с которыми придётся встречаться чаще всего. Все они уже стоят на компьютере вместе с Python – ни скачивать, ни устанавливать ничего не надо.

Модуль	Что в нём	Пример вызова
`math`	математика: корни, степени, тригонометрия, константы	`math.sqrt(16)`
`random`	случайные числа и случайный выбор	`random.randint(1, 6)`
`datetime`	даты и время: сегодняшний день, разница между датами	`date.today()`
`re`	поиск по образцу – регулярные выражения	`re.search(r'\d+', s)`
`os`	файлы и папки: список файлов, путь, переименование	`os.listdir('.')`
`sys`	сама программа: аргументы запуска, версия Python, выход	`sys.exit()`
`time`	время: пауза в работе, секунды, замер скорости	`time.sleep(1)`

re стоит в таблице не для полноты: это модуль регулярных выражений, и весь следующий урок – про него.

Стандартная библиотека – не короткий список, а сотни модулей: есть работа с текстом, с числами, с файлами, с датами, с архивами, с сетевыми протоколами. Про Python за это говорят «батарейки в комплекте» – то, что в других языках ищут и ставят отдельно, здесь уже лежит под рукой. Полный список – в документации, docs.python.org.

import random
from datetime import date

# случайное число и случайный выбор
print(random.randint(1, 6))                # 4 – например
print(random.choice(['орёл', 'решка']))    # решка – например

# сегодняшняя дата и та же дата, записанная по-человечески
print(date.today())                        # год-месяц-день
print(date.today().strftime('%d.%m.%Y'))   # день.месяц.год
# у даты есть готовый способ напечатать себя в любом виде

Сторонние библиотеки и `pip`

В стандартной библиотеке есть многое – но не всё. Попросить страницу из интернета, посчитать таблицу чисел, нарисовать график – этого там нет: такие задачи решают отдельные библиотеки, которые пишут и поддерживают другие люди.

pip – установщик пакетов Python: программа, которая скачивает библиотеку из интернета и раскладывает её так, чтобы import её нашёл.

Ставится сторонняя библиотека командой в терминале:

pip install requests

Читается буквально: «pip, установи requests». Делается это один раз на компьютере – и всё, дальше библиотека доступна любой программе, как будто всегда там была.

Важно не перепутать: pip install – команда терминала, а не код Python. Внутри программы такая строка бессмысленна: Python попытается увидеть в ней вызов функции pip и остановится с NameError.

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

ModuleNotFoundError: No module named 'requests'

Читается дословно: «модуль не найден – модуля с именем requests нет». Причин ровно две, и проверяют их по очереди:

Опечатка в имени. Имя модуля пишут точно: requests, а не request и не requsts. Одна пропущенная буква – и модуль «не найден», хотя всё остальное в программе верно.
Библиотека не установлена. Тогда её ставят: pip install requests – и запускают программу заново.

Ошибка при этом честная: Python действительно искал модуль и не нашёл. И её стоит отличать от соседней: если опечатка не в имени модуля, а в самом слове import (например, improt math), сообщение будет совсем другим – SyntaxError, «не понимаю такую запись». ModuleNotFoundError – это всегда «запись понятна, а модуля нет».

Ловушка: свой файл с именем модуля

Теперь ловушка, в которую попадают почти все – и почти никто не понимает с первого раза. Программу про случайные числа сохранили под именем random.py – и она перестала работать. Тот же файл, переименованный в task.py, работает снова. Что произошло?

Модуль ищут по списку папок, и папка программы стоит в нём раньше стандартной библиотеки.

Когда программа пишет import random, Python не бросается сразу в стандартную библиотеку. Он смотрит по очереди: сначала папку, из которой запущена программа, потом папки, добавленные вручную, и только потом – модули, идущие с Python. В папке программы лежит random.py. Имя совпало – поиск закончен: под именем random в программу попал ваш файл, а настоящий модуль со случайными числами до дела не дошёл.

Дальше всё зависит от того, что в вашем файле. Чаще всего он пустой или почти пустой, и первая же строка с делом падает:

AttributeError: module 'random' has no attribute 'randint'

Читается это сообщение обманчиво: «в модуле random нет randint». Можно пойти в документацию, убедиться, что randint там есть, и решить, что ошибка врёт. А врёт не ошибка – под именем random подключён не тот файл.

Точно так же ломает жизнь любой свой файл, чьё имя совпало с именем модуля: re.py, math.py, datetime.py, os.py. Особенно обидно с re.py: программа работает, пока в ней нет регулярных выражений, а потом падает.

Что делать:

Не называть свои файлы именами модулей. Имя файла программы должно говорить о задаче: task.py, perevod.py, dnevnik.py.
Посмотреть, откуда пришёл модуль. Одна строка отвечает на вопрос целиком:

import random
print(random.__file__)
# C:\Python313\Lib\random.py – вот это настоящий модуль

У каждого модуля есть переменная __file__ – путь к файлу, из которого он загружен. Если в выводе стоит путь к вашей папке, значит под именем random найден ваш файл, и его надо переименовать.

Как узнать, что умеет модуль

Остался практический вопрос: откуда узнают, какие имена есть в модуле и что они делают. Способов три, и все они под рукой.

Документация. docs.python.org – официальная документация Python, у неё есть и русский раздел. В поиске набирают «python math» – и получают страницу, где перечислена каждая функция модуля с примером. Это единственный источник, которому стоит верить целиком: в случайной статье из интернета пример может быть устаревшим.

help() – справка прямо в программе:

import math

help(math)        # список имён модуля с описанием каждого
help(math.sqrt)   # справка по одной функции

help(math) печатает длинный текст: сначала описание модуля, потом имена с первой строкой пояснения к каждому. Читают его листая, выходят – клавишей q.

dir() – одно оглавление, без пояснений:

import math

print(dir(math))
# ['__doc__', '__file__', ..., 'ceil', 'cos', 'e', 'floor', 'pi']

dir(модуль) возвращает список всех имён в модуле. Имена с двумя подчёркиваниями по краям – служебные, их пропускают глазами; остальное – то, чем можно пользоваться. Список короткий и отвечает на вопрос «есть ли тут вообще нужное», а как именно вызывать – подскажет help() или документация.

В среде разработки третий способ находится сам: после имени модуля достаточно поставить точку, и список имён появится подсказкой. Но подсказка есть не везде, а help() работает в любом Python.

Шпаргалка

Что	Что делает
`import модуль`	подключает модуль целиком; обращение через `модуль.имя`
`from модуль import имя`	подключает названные имена; обращение сразу по имени
`from модуль import имя1, имя2`	то же для нескольких имён сразу
`import модуль as короткое`	подключает модуль под другим именем: `np.sqrt(16)`
`from модуль import *`	подключает все имена разом – так не пишут
`pip install пакет`	ставит стороннюю библиотеку; это команда терминала, а не код Python
`ModuleNotFoundError`	модуль не найден: опечатка в имени или библиотека не установлена
`help(модуль)`	справка по модулю или по одной функции
`dir(модуль)`	список имён, которые есть в модуле
`модуль.__file__`	путь к файлу, из которого загружен модуль: сразу видно, свой он или стандартный

Первые пять строк – про запись import, остальные – про то, как разобраться, когда что-то пошло не так.

Коротко

Модуль – файл с готовым кодом, библиотека – набор модулей. Слово import подключает их к программе, чтобы не писать заново то, что уже написано.
Три формы записи: import math (обращение math.sqrt), from math import sqrt (обращение sqrt) и import numpy as np (короткое имя). Имя модуля перед точкой показывает, откуда взялась функция.
from math import * не пишут: имена сваливаются в общую кучу, незаметно перекрывают друг друга, и читатель не может понять, откуда имя взялось.
Стандартная библиотека идёт в комплекте с Python: math, random, datetime, re, os, sys, time. Сторонние библиотеки (requests, numpy, matplotlib) ставят командой pip install – один раз на компьютере. Не найденный модуль – это ModuleNotFoundError: либо опечатка в имени, либо библиотека не установлена.
Свой файл с именем модуля (random.py, re.py, math.py) перекрывает стандартный: Python ищет модуль сначала в папке программы. Проверить, откуда пришёл модуль, можно через модуль.__file__.