Документация Python: как искать нужный модуль

Документация Python помогает понять, какие модули уже есть в стандартной библиотеке, как называются функции, какие аргументы они принимают и где посмотреть короткий пример. Если научиться читать документацию, многие вопросы решаются быстрее, чем через случайные ответы из поиска

Главная мысль: сначала ищите модуль в стандартной библиотеке, потом смотрите страницу модуля, затем проверяйте пример в отдельном файле

Где искать модуль

У Python есть стандартная библиотека: json, pathlib, datetime, csv, argparse, sqlite3, math, random, collections и много других модулей

Если вы не знаете точное имя модуля, ищите по задаче:

• работа с JSON — json
• пути и файлы — pathlib
• даты и время — datetime
• CSV-файлы — csv
• аргументы командной строки — argparse
• случайные числа — random
• счетчики и специальные коллекции — collections

После этого открывайте страницу конкретного модуля и ищите раздел с примерами

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

По этой теме полезно отдельно посмотреть Аннотации типов для декораторов в Python, чтобы расширить контекст и сравнить подходы

Как читать страницу модуля

На странице модуля обычно есть:

• краткое описание
• список функций
• список классов
• параметры функций
• примеры кода
• примечания и предупреждения

Не пытайтесь читать страницу сверху вниз как книгу. Ищите то, что нужно сейчас: функцию, класс, пример, тип результата или ошибку

Пример: найти json

Задача: превратить словарь Python в JSON-строку

В документации модуля json ищите функции dumps() и loads()

import json

data = {
    'name': 'Анна',
    'role': 'admin',
}

text = json.dumps(data, ensure_ascii=False)
print(text)

result = json.loads(text)
print(result['name'])

dumps() превращает объект Python в строку JSON. loads() делает обратное действие

Пример: найти pathlib

Задача: записать текст в файл и прочитать его обратно

В документации pathlib ищите класс Path

from pathlib import Path

path = Path('result.txt')
path.write_text('готово', encoding='utf-8')

text = path.read_text(encoding='utf-8')
print(text)

Если в документации видите класс, сначала найдите минимальный пример создания объекта. Для Path это Path('result.txt')

Пример: найти datetime

Задача: получить текущую дату и отформатировать ее

from datetime import datetime

now = datetime.now()
print(now.strftime('%Y-%m-%d'))

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

help() внутри Python

Документацию можно смотреть прямо в интерпретаторе

import json

help(json.dumps)

Для класса:

from pathlib import Path

help(Path)

help() полезен, когда вы уже знаете имя функции или класса и хотите быстро увидеть аргументы

pydoc из терминала

Еще один вариант:

python -m pydoc json
python -m pydoc pathlib.Path

Так можно посмотреть документацию без браузера

Если хотите открыть локальный сервер документации:

python -m pydoc -b

Python откроет страницу со справкой по установленным модулям

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

Не все, что вы импортируете, входит в Python

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

import json
import pathlib
import argparse

Сторонние пакеты:

import requests
import pandas
import aiogram

Если модуль сторонний, его нужно установить через pip, а документацию искать на сайте проекта. Если модуль стандартный, установка обычно не нужна

Как искать быстрее

Сформулируйте задачу обычными словами

Подберите вероятный модуль

Откройте страницу модуля

Найдите пример кода

Скопируйте минимальный пример в отдельный файл

Поменяйте одно значение и посмотрите результат

Сравните свое использование с сигнатурой функции

Частые ошибки

Сразу искать готовый большой фрагмент вместо документации конкретной функции

Путать похожие функции, например json.load() и json.loads()

Не смотреть тип результата

Копировать пример без импорта

Использовать сторонний пакет, хотя задача решается стандартной библиотекой

Открывать документацию не той версии Python

Практические задачи

Найдите в документации json.dumps() и проверьте параметр ensure_ascii

Найдите Path.write_text() и запишите файл

Найдите datetime.strftime() и выведите дату в формате год-месяц-день

Посмотрите справку help(str.replace)

Откройте python -m pydoc argparse

Документация Python полезна не только опытным разработчикам. Новичку она помогает быстро найти готовый модуль, увидеть правильное имя функции, понять аргументы и проверить короткий пример

Не читайте документацию как роман. Используйте ее как карту: задача, модуль, функция, пример, проверка в маленьком файле