Документация по языку программирования Python

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

Коротко о языке Python

Python - интерпретируемый язык общего назначения с динамической типизацией. Тип переменной определяется значением во время выполнения, объявлять его не нужно, а блоки кода выделяются отступами вместо фигурных скобок. Благодаря этому программы короче и читаются почти как псевдокод.

Язык поддерживает несколько стилей программирования: процедурный, объектно-ориентированный и функциональный. В комплекте с интерпретатором идет стандартная библиотека из сотен модулей для работы с файлами, сетью, датами, JSON, базами SQLite, регулярными выражениями. Еще сотни тысяч пакетов доступны в каталоге PyPI и ставятся командой pip.

Python применяют в веб-разработке (Django, Flask, FastAPI), анализе данных и машинном обучении (pandas, NumPy, scikit-learn), автоматизации и парсинге, написании ботов, научных расчетах и обучении программированию.

Из чего состоит официальная документация

Официальная документация опубликована на docs.python.org. Для каждой версии языка там отдельная копия, версию выбирают в меню вверху страницы. Разделы рассчитаны на разные задачи, и путаница между ними чаще всего мешает быстро найти ответ.

В обычной работе чаще всего нужен Library Reference. Встроенные функции описаны на странице Built-in Functions, методы строк, списков и словарей в разделе Built-in Types. Документацию можно скачать архивом в форматах HTML, PDF и EPUB для чтения без сети.

Документация на русском языке

У официальной документации есть переключатель языка, среди доступных переводов есть русский. Перевод делают добровольцы, поэтому часть страниц может оставаться на английском, а англоязычная версия всегда самая полная и актуальная. Начать удобно с русской версии docs.python.org.

Если перевода нужной страницы нет, помогает знание нескольких десятков терминов: argument (аргумент), keyword argument (именованный аргумент), iterable (итерируемый объект), return value (возвращаемое значение), raises (выбрасывает исключение), deprecated (устарело). Остальной текст справочника написан простым техническим английским.

Справка без интернета: help() и pydoc

Документация к функциям и модулям встроена в сам Python в виде строк документации (docstring). Функция help() выводит ее в интерактивном режиме.

help(len)          # справка по функции
help(str.split)    # справка по методу
help('modules')    # список установленных модулей

import json
print(json.dumps.__doc__[:200])   # текст docstring напрямую

Утилита pydoc показывает ту же справку из командной строки, а с ключом -b запускает локальный сервер и открывает документацию по всем установленным модулям в браузере.

# в терминале, а не в интерпретаторе
# python -m pydoc json.loads
# python -m pydoc -b

Свои функции стоит документировать так же: строка в тройных кавычках сразу после def станет текстом, который покажет help().

def area(width, height):
    """Вернуть площадь прямоугольника."""
    return width * height

help(area)

Как читать сигнатуры функций

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

• Значение после знака равенства - значение по умолчанию: sorted(iterable, /, *, key=None, reverse=False).
• Косая черта / означает, что параметры слева от нее передаются только по позиции, без имени.
• Звездочка * означает, что параметры справа от нее передаются только по имени: sorted(data, reverse=True), но не sorted(data, None, True).
• Квадратные скобки, как в range(start, stop[, step]), обозначают необязательные аргументы.
• Пометки Added in version и Changed in version показывают, с какой версии Python доступна функция или параметр. Пометка Deprecated означает, что от функции планируют отказаться.

Подробнее о позиционных и именованных параметрах рассказано в статье про аргументы функции.

Документация сторонних библиотек

Пакеты из PyPI документируются их авторами, а не в docs.python.org. Ссылка на документацию обычно стоит на странице пакета в PyPI в блоке Project links. Многие проекты публикуются на сервисе Read the Docs, их адреса выглядят как имя-проекта.readthedocs.io.

Перед чтением проверьте установленную версию пакета командой pip show requests и откройте документацию той же версии: интерфейс библиотек между версиями меняется сильнее, чем у стандартной библиотеки. Обзор подключения пакетов есть в статье об импорте библиотек.

Учебные материалы по разделам

Справочник удобен, когда понятно, что искать. Для последовательного изучения лучше подходят уроки с примерами. Материалы сайта разбиты на несколько больших тем:

• Основы языка Python: переменные, типы данных, условия, циклы, функции и работа с файлами.
• Модули Python: стандартная библиотека и популярные пакеты с примерами использования.
• Веб-разработка на Flask: маршруты, шаблоны, формы и подключение базы данных.
• Графические интерфейсы на Tkinter: окна, виджеты, обработка событий.

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

Частые вопросы

Ответы на вопросы о документации Python.

Где найти официальную документацию Python?

На сайте docs.python.org. Для каждой версии языка там своя копия, а в меню можно выбрать язык, в том числе русский.

Как узнать, какая версия документации мне нужна?

Выполните в терминале python --version и выберите ту же версию в меню документации. Возможности новых версий в старых работать не будут.

Можно ли читать документацию без интернета?

Да. Справку по любому объекту выводит help() в интерпретаторе, полную документацию по установленным модулям показывает python -m pydoc -b, а весь справочник можно скачать архивом с docs.python.org.

Чем Tutorial отличается от Library Reference?

Tutorial объясняет основы языка по порядку, как учебник. Library Reference - справочник, где описаны все функции и модули с параметрами, его открывают точечно под конкретную задачу.