Питон документация: Работа с документацией в Python: поиск информации и соглашения

Содержание

Работа с документацией в Python: поиск информации и соглашения

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

Работа с документацией является одной из важных составляющих деятельности разработчика. И это не только чтение документации к библиотекам и комментариев в коде, но и документирование собственного кода, а также поддержание его в актуальном состоянии. Качественно задокументированный код во многих случаях упрощает его поддержание и сокращает время на «вхождение» новых сотрудников в проект. Если же речь идет об изучении нового языка программирования, качество документации и поддержка сообщества могут сыграть решающую роль в освоении материала и снизить порог вхождения.

Документация к языку программирования Python обладает всеми качествами, которые отличают «хорошую» документацию от «плохой». Тем не менее, новички часто сталкиваются с рядом вопросов. Как быстро найти информацию о классе или функции? Как самому писать документацию к коду? Какие инструменты можно использовать при документировании кода? На эти вопросы мы и постараемся ответить в статье.

Основной источник информации о Python

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

Важные разделы сайта (полезно начинающим программистам)

Setup and Usage — содержит информацию об установке и настройке Python на разных платформах;
Tutorial — учебное пособие для новичков, с которого и рекомендуется начинать свой путь в мир Python;
Library Reference — подробное описание стандартной библиотеки Python;
Python HOWTO — различные руководства по конкретным темам;
Language Reference — раздел для тех кто, хочет знать подробности реализации СPython.

В остальных разделах вы можете найти информацию о сторонних модулях, их установке и распространении, информацию по написанию расширений для Python на языках С/С++, часто задаваемые вопросы и новости Python.

Поиск по сайту с документацией

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

Создатели Python предусмотрели возможность установить документацию локально на компьютере. Для этого необходимо перейти на страницу загрузки, выбрать версию Python, формат файлов (доступны pdf, epub, html, txt) и способ архивирования. После скачивания и распаковки архива, вы можете пользоваться документацией в полном объеме.

Встроенная справочная система

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

Небольшое уточнение: поскольку в Python все является объектом, в том числе методы и классы, далее мы будем часто употреблять термин «объект» применительно к целям получения информации.

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

Примеры

>>> help(ord)
Help on built-in function ord in module builtins:
ord(c, /)
    Return the Unicode code point for a one-character string.
(END)

В приведенном выше примере, мы вызвали справку по функции ord. В тексте сообщения содержится информация о том, что делает функция и к какому модулю она относится.

Теперь попробуем получить информацию о модуле стандартной библиотеки os.

>>> help(os)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'os' is not defined

Почему вызов функции завершился выбросом исключения? Ведь модуль os входит в стандартную библиотеку и маловероятно, что справочная информация по нему не была включена.

Docstring

Чтобы ответить на этот вопрос, давайте разберемся, где хранится справочная информация и как работает функция help. Как уже говорилось выше, все в Python является объектом. Все объекты в Python имеют специальный атрибут __doc__, предназначенный для хранения строки документации — docstring. Вот как определено понятие docstring в официальной документации: «Docstring — строковый литерал, который встречается как первый оператор в определении модуля, функции, класса или метода. Такой docstring становится специальным атрибутом __doc__ этого объекта».

Посмотрим, что хранится в атрибуте __doc__ объекта ord.

>>> ord.__doc__
'Return the Unicode code point for a one-character string.'

Размещение справки об объекте в исходном коде самого объекта позволяет элегантно решить вопрос хранения информации и доступа к ней. Функция help при передаче ей в качестве аргумента объекта для получения информации о нем, обращается к атрибуту __doc__ этого объекта. Поскольку модуль os не импортирован, он отсутствует в глобальной области видимости и не доступен при вызове функции help. Именно по этой причине мы получаем ошибку. Для решения проблемы достаточно импортировать модуль. Есть еще один способ избежать ошибки и не связанный с импортом объекта — передать в качестве аргумента в функцию help строку с именем объекта.

>>> help('os')

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

Посмотрим на исходный код модуля os и убедимся в том, что docstring и содержимое атрибута os.__doc__ совпадают. Из приведенного кода видно, как определяются в коде docstring. Строки документации заключаются в тройные кавычки и пишутся сразу под заголовком объекта.

Вы уже заметили, что вывод функции help отличается от вывода, полученного через обращение к атрибуту __doc__ объекта. Он более информативен и выводит информацию в виде форматированного текста. У функции help есть еще одна особенность, повышающая удобство работы со справочной системой. При вызове help без аргументов запускается интерактивный режим справочной системы. Для получения справки в нем достаточно набрать только название интересующего нас объекта. Запустив интерактивный режим в отдельном терминале, мы получаем удобный инструмент для работы с документацией.

Как вспомнить название модуля, класса или функции?

Стандартная библиотека Python весьма обширна и содержит большое количество модулей. Помнить их все, в том числе и заложенный функционал, невозможно. Что делать, если мы не помним (не знаем) название модуля, класса или функции? Ниже приведены несколько примеров, помогающих в таких ситуациях.

Получение списка доступных модулей:

>>> help('modules')

Получение ключевых слов:

>>> from keyword import kwlist
>>> print(*kwlist, sep='\n')

Получение списка названий встроенных функций:

>>> import builtins
>>> print(*builtins.__dict__.keys(), sep='\n')

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

>>> dir(int)

Как задокументировать собственный код?

Теперь, когда мы знаем о docstring и работе функции help, мы можем задокументировать свой код. В качестве примера возьмем скрипт factorial.py:

def factorial(n):
   if n < 2:
       return 1
   return n * factorial(n — 1)

if __name__ == "__main__":
   n = int(input())
   print(factorial(n))

Добавим docstring.

""" Скрипт для нахождения факториала """

def factorial(n):
    """ Вычисляет факториал числа n """
   if n < 2:
       return 1
   return n * factorial(n - 1)

if __name__ == "__main__":
   n = int(input())
   print(factorial(n))

Убедимся в наличии документации по модулю factorial:

>>> import factorial
>>> factorial.__doc__
' Скрипт для нахождения факториала '
>>> factorial.factorial.__doc__
' Вычисляет факториал числа n '

Вызов help(factorial) вернет справку:

Help on module factorial:

NAME
   factorial - Скрипт для нахождения факториала

FUNCTIONS
   factorial(n)
       Вычисляет факториал числа n

FILE
   /home/user/factorial.py
(END)

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

О библиотеке pydoc

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

Команда pydoc позволяет вывести текст справки прямо в терминале (не интерпретаторе Python):

$ pydoc sum

Help on built-in function sum in module __builtin__:

sum(...)
   sum(sequence[, start]) -> value
   Return the sum of a sequence of numbers (NOT strings) plus the value
   of parameter 'start' (which defaults to 0). When the sequence is
   empty, return start.
(END)

Для создания документации в виде HTML-страниц используется ключ -w. Это позволяет организовать хранение документации отдельно от кода.

$ pydoc -w sum
wrote sum.html
$ cat sum.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><title>python: built-in function sum</title>
<meta charset="utf-8">
</head><body bgcolor="#f0f0f8">
<dl><dt><a name="-sum"><strong>sum</strong></a>(...)</dt><dd><tt>sum(sequence[,&nbsp;start])&nbsp;-&gt;&nbsp;value<br>
&nbsp;<br>
Return&nbsp;the&nbsp;sum&nbsp;of&nbsp;a&nbsp;sequence&nbsp;of&nbsp;numbers&nbsp;(NOT&nbsp;strings)&nbsp;plus&nbsp;the&nbsp;value<br>
of&nbsp;parameter&nbsp;'start'&nbsp;(which&nbsp;defaults&nbsp;to&nbsp;0).&nbsp;&nbsp;When&nbsp;the&nbsp;sequence&nbsp;is<br>
empty,&nbsp;return&nbsp;start.</tt></dd></dl>

Для поиска по docstring модулей используется ключ -k. В качестве аргумента в этом случае передается ключевое слово. В результате будут выведены названия всех модулей в docstring которых встречается ключевое слово.

$ pydoc -k json
json - JSON (JavaScript Object Notation) <http://json.org> is a subset of
json.decoder - Implementation of JSONDecoder
json.encoder - Implementation of JSONEncoder
json.scanner - JSON token scanner
json.tool - Command-line tool to validate and pretty-print JSON
_json
pbr.pbr_json

Обратим ваше внимание на одну особенность поиска по документации при использовании ключа -k. Поиск производится только по первым строкам документации модулей. Тем не менее, данный функционал может быть весьма полезным в некоторых случаях.

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

$ pydoc3 -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server>

В третьей версии Python для управления сервером добавлена пара команд: b — открытие страницы документации в браузере, q — завершения работы сервера. При вызове команды pydoc3 с ключом -b произойдет запуск сервера и автоматическое открытие страницы в браузере. В документацию также будут включены модули, расположенные в директории из которой был запущен сервер.

Соблюдение соглашений

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

Модуль pydocstyle — это инструмент статического анализа для проверки соответствия docstring соглашениям, принятым в Python. Установка модуля осуществляется с помощью менеджера пакетов pip:

$ pip install pydocstyle

По умолчанию pydocstyle проверяет docstring на соответствие официальному соглашению PEP257. Проверим созданный нами скрипт factorial.py:

$ pydocstyle factorial.py
factorial.py:1 at module level:
  D400: First line should end with a period (not 'а')
factorial.py:1 at module level:
  D210: No whitespaces allowed surrounding docstring text
factorial.py:3 in public function `factorial`:
  D400: First line should end with a period (not 'n')
factorial.py:3 in public function `factorial`:
  D210: No whitespaces allowed surrounding docstring text

Видим, что pydocstyle обнаружил ошибки — лишние пробелы вокруг текста и отсутствие точки в конце строк документации. Исправим эти ошибки и запустим pydocstyle еще раз.

Модуль pydocstyle имеет более широкие возможности, чем в приведенном выше примере, и гибкую систему настроек под требования по оформлению документации. Ознакомится с их полным списком можно вызвав pydocstyle -h или в разделе «документация» на сайте проекта.

Полезные ссылки

ФРОО рекомендует:

Еще статьи по Python

Учебник Python — документация Python 3.x

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

Интерпретатор Python и обширная стандартная библиотека находятся в свободном доступе в виде исходных кодов или бинарной форме для всех основных платформ на веб-сайте Python: https://www.python.org, и могут свободно распространяться. Кроме того, на этом сайте также есть дистрибутивы и указатели на многие свободные сторонние модули Python, программы и инструменты, дополнительную документацию.

Интерпретатор Python легко расширяется новыми функциями и типами данных, выполненных на C или C++ (или других языках, вызываемых из C). Python также является подходящим как язык расширения для настраиваемых приложений.

Этот учебник неформально знакомит читателя с основными концепциями и возможностями языка и системы Python. Он помогает удобно использовать интерпретатор Python для практического опыта, но все примеры самодостаточны, так что учебник можно читать также в режиме off-line.

Описание стандартных объектов и модулей смотрите в Стандартной библиотеке Python. Справка по языку Python дает более формальное определение языка. Чтобы писать расширения на C и C++, читайте Расширение и внедрение интерпретатора Python и Справочное руководство по API Python/C.

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

Также стоит полистать Глоссарий (толковый словарь).

Введение в стандартную библиотеку — документация Python 3.x

«Библиотека Python» включает несколько разных видов компонентов.

Она содержит типы данных, которые обычно считаются частью «ядра» языка, как, например, числа и списки. Для этих типов ядро языка Python определяет форму литералов и накладывает некоторые ограничения на их семантику, но полностью не определяет ее. (С другой стороны ядро языка определяет синтаксические свойства как в написании, так и в приоритете операторов.)

Библиотека также содержит встроенные функции и исключения — объекты, которые могут использоваться во всем коде Python без необходимости использования оператора import (docs.python.org/3/reference/simple_stmts.html#import). Некоторые из них определяются ядром языка, но многие не является необходимыми для семантики ядра и только описаны здесь.

Однако основная часть библиотеки состоит из набора модулей. Существует много способов проанализировать эту коллекцию. Некоторые модули написаны на языке C и встроены в интерпретатор Python; другие написаны на Python и импортированы в виде исходного кода. Некоторые модули обеспечивают интерфейсы, которые весьма специфичны для Python, например вывод трассировки стека; некоторые предоставляют интерфейсы, которые являются специфическими для конкретных операционных систем, такие как доступ к конкретному оборудованию; другие предоставляют интерфейсы, которые являются специфическими для конкретной области приложений, как, например, World Wide Web. Некоторые модули доступны во всех версиях и портах Python; другие доступны только тогда, когда лежащая в основе система поддерживает или требует их; другие доступны только тогда, когда был выбран конкретный параметр конфигурации при компиляции и установки Python.

Это руководство организовано «шиворот навыворот»: оно сначала описывает встроенные типы данных, затем встроенные функции и исключения, и, наконец, модули, сгруппированные в главах связанных модулей.

Это означает, что если вы начнете читать данное руководство с самого начала и переходите к следующей главе, то когда вам надоест, вы уже получите приемлемый обзор доступных модулей и областей применения, которые поддерживаются библиотеками Python. Конечно, вы не обязаны читать руководство как роман — вы также можете просмотреть оглавление (в начале руководства), или искать конкретную функцию, модуль или термин в индексе (в конце). И, наконец, если вам нравится узнавать о случайных предметах, вы выбираете случайный номер страницы (см. модуль random (docs.python.org/3/library/random.html#module-random)) и читаете раздел или два. Независимо от того, как вы будете читать разделы данного руководства, начните с главы «Встроенные функции», так как остальная часть руководства предполагает знакомство с этим материалом.

Пусть шоу начинается!

Управление потоком выполнения — документация Python 3.x

Кроме оператора while (docs.python.org/3/reference/compound_stmts.html#while), который только что был представлен, Python знает обычные операторы управления потоком, известные из других языков, но с некоторыми особенностями.

4.1. Операторы if

Возможно наиболее хорошо известным типом оператора является if (docs.python.org/3/reference/compound_stmts.html#if). Например:

>>> x = int(input("Пожалуйста, введите число: "))
Пожалуйста, введите число: 42
>>> if x < 0:
...     x = 0
...     print('Отрицательное изменяется на 0')
... elif x == 0:
...     print('Ноль')
... elif x == 1:
...     print('Один')
... else:
...     print('Больше')
...
Больше

Частей elif (docs.python.org/3/reference/compound_stmts.html#elif) может быть больше или не быть вообще, часть else (docs.python.org/3/reference/compound_stmts.html#else) также необязательна. Ключевое слово ‘elif’ есть сокращение от ‘else if’ и полезно для избежания излишних отступов. Последовательность if ... elif ... elif ... есть замена для операторов switch или case, встречающихся в других языках.

4.2. Операторы for

В Python оператор for (docs.python.org/3/reference/compound_stmts.html#for) немного отличается от того, что вы могли использовать в C или Pascal. Вместо того, чтобы всегда выполнять итерацию по арифметической прогрессии чисел (как в Pascal), или давая пользователю возможность определить как шаг итерации, так и условие остановки (как в C), в Python оператор for перебирает элементы любой последовательности (список или строку) в том порядке, в котором они появляются в последовательности. Например (нет намеренной игры слов):

>>> # Измерить несколько слов:
... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
...     print(w, len(w))
...
cat 3
window 6
defenestrate 12

Если вам надо изменить последовательность, вы перебираете внутри цикла (например, для дублирования выбранных элементов), рекомендуется сначала сделать копию. Выполнение итерации над последовательностью безоговорочно не создает ее копию. Взятие среза делает это особенно удобным:

>>> for w in words[:]:  # Цикл по срезу-копии целого списка.
...     if len(w) > 6:
...         words.insert(0, w)
...
>>> words
['defenestrate', 'cat', 'window', 'defenestrate']

С for w in words: пример попытался бы создать бесконечный список, вставляя defenestrate опять и опять.

4.3. Функция range()

Если вам надо перебрать последовательность чисел, пригодится встроенная функция range(). Она генерирует арифметические прогрессии:

>>> for i in range(5):
...     print(i)
...
0
1
2
3
4

Заданная конечная точка никогда не входит в генерируемую последовательность; range(10) генерирует 10 значений, индексируемые как обычная последовательность длинной 10. Возможно установить другое число в качестве начала диапазона или указать другое приращение (даже отрицательное; иногда приращение называют «шагом»):

range(5, 10)
   от 5 по 9
 
range(0, 10, 3)
   0, 3, 6, 9
 
range(-10, -100, -30)
  -10, -40, -70

Для перебора по индексам последовательности, вы можете сочетать range() и len() как в следующем примере:

>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
...     print(i, a[i])
...
0 Mary
1 had
2 a
3 little
4 lamb

В большинстве подобных случаев, однако, удобно использовать функцию enumerate(), см. Приемы использования цикла.

Странная вещь случится, если вы просто напечатаете диапазон:

>>> print(range(10))
range(0, 10)

Во многих отношениях объект, возвращаемый range(), ведет себя так, как будто это список, но на самом деле это не так. Это объект, который возвращает последовательные элементы желаемой последовательности, когда вы перебираете его, но это на самом деле не список, тем самым экономится пространство.

Мы говорим, что объект является iterable (итерация, итерируемый — прим. пер.), то есть подходит в качестве цели для функций и конструкций, которые ожидают что-то, из чего они могут получить последовательные элементы, пока они не исчерпаны. Мы видели, что оператор for именно такой iterator (итератор — прим. пер.). Функций list() есть другой; она создает списки из итерируемых (перечисляемых) объектов:

>>> list(range(5))
[0, 1, 2, 3, 4]

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

4.4. Операторы break, continue и условие else в циклах

Оператор break (docs.python.org/3/reference/simple_stmts.html#break), как и в C, прерывает выполнение вмещающего (самого внутреннего) его цикла for (docs.python.org/3/reference/compound_stmts.html#for) или while (docs.python.org/3/reference/compound_stmts.html#while).

Операторы цикла могут иметь условие else; оно выполняется, когда цикл завершается при исчерпании списка (с for) или когда условие становится ложным (с while), но не в том случае, когда цикл прерван оператором break. Это иллюстрирует следующий пример с циклом, в котором ищутся простые числа:

>>> for n in range(2, 10):
...     for x in range(2, n):
...         if n % x == 0:
...             print(n, 'equals', x, '*', n//x)
...             break
...     else:
...         # цикл потерпел неудачу, не найдя множитель
...         print(n, 'is a prime number')
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3

(Да, это корректный код. Посмотрите внимательней: условие else относится к циклу for, не к оператору if.)

При использовании с циклом условие else имеет больше общего с условием else оператора try (docs.python.org/3/reference/compound_stmts.html#try), чем if (docs.python.org/3/reference/compound_stmts.html#if): ветка else оператора try срабатывает, когда исключения не происходит, а ветка else цикла срабатывает, когда не срабатывает break. За дополнительной информацией по оператору try и исключениям, см. Обработка исключений.

Оператор continue (docs.python.org/3/reference/simple_stmts.html#continue) также заимствован из C, он продолжает выполнение со следующей итерации цикла:

>>> for num in range(2, 10):
...     if num % 2 == 0:
...         print("Found an even number", num)
...         continue
...     print("Found a number", num)
Found an even number 2
Found a number 3
Found an even number 4
Found a number 5
Found an even number 6
Found a number 7
Found an even number 8
Found a number 9

4.5. Оператор pass

Оператор pass (docs.python.org/3/reference/simple_stmts.html#pass) ничего не делает. Он может быть использован, когда синтаксически требуется какой-нибудь оператор, но программа не требует действия. Например:

>>> while True:
...     pass  # Занят ожиданием прерывания с клавиатуры (Ctrl+C)
...

Обычно это используется при создании очень маленьких классов:

>>> class MyEmptyClass:
...     pass
...

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

>>> def initlog(*args):
...     pass   # Вспомните потом реализовать это!
...

4.6. Определение функций

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

>>> def fib(n):    # выводит ряд Фибоначчи до n
...     """Печатает ряд Фибоначчи вплоть до n."""
...     a, b = 0, 1
...     while a < n:
...         print(a, end=' ')
...         a, b = b, a+b
...     print()
...
>>> # Теперь вызовем функцию, которую мы только что определили:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

Ключевое слово def (docs.python.org/3/reference/compound_stmts.html#def) вводит определение функции. За ним должно следовать имя функции и в круглых скобках список формальных параметров. Выражения, которые формируют тело функции, начинаются на следующей строке и должны быть с отступом.

Опционально (не обязательно) первое выражение тела функции может быть строковым литералом; этот строковый литерал является строкой документации функции, или docstring. (Дополнительно о строках документации может быть найдено в разделе Строки документации.) Есть инструменты, которые используют строки документации для автоматического создания онлайн или печатной документации, или позволить пользователю интерактивно просматривать код; это хорошая практика включать строки документации в код, который вы пишите, так что сделайте это привычкой.

Выполнение функции вводит новую таблицу обозначений, используемую для локальных переменных функции. Точнее, все присваивания переменным в функции сохраняют значение в локальной таблице обозначений; так ссылки на переменные сначала ищутся в локальной таблице, затем в локальной таблице обрамляющих функций, затем в глобальной таблице обозначений, и наконец в таблице встроенных имен. Поэтому глобальные переменные не могут быть связаны со значением непосредственно в функции (если не названы в операторе global (docs.python.org/3/reference/simple_stmts.html#global)), хотя на них можно ссылаться.

Фактические параметры (аргументы) при вызове функции вводятся в ее локальную таблицу имен; таким образом, аргументы передаются с помощью вызова по значению (где значение всегда ссылка на объект, не значение объекта). [1] Когда функция вызывает другую функцию, создается новая локальная таблица имен для этого вызова.

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

>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89

Придя из других языков, вы можете подумать, что объект fib не функция, а процедура, поскольку она не возвращает значение. В действительности даже функции без оператора return (docs.python.org/3/reference/simple_stmts.html#return) делают возврат значения, хотя довольно скучный. Это значение называется None (это встроенное имя). Вывод значения None обычно подавляется интерпретатором, если это будет только записанное значение. Вы можете увидеть это, если захотите с помощью print():

>>> fib(0)
>>> print(fib(0))
None

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

>>> def fib2(n): # возвращает ряд Фибоначчи вплоть до n
...     """Возвращает список, включающий ряд Фибоначчи вплоть до n."""
...     result = []
...     a, b = 0, 1
...     while a < n:
...         result.append(a)    # смотри ниже
...         a, b = b, a+b
...     return result
...
>>> f100 = fib2(100)    # вызов
>>> f100                # вывод результата
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

Этот пример, как обычно, демонстрирует некоторые особенности Python:

Оператор return (docs.python.org/3/reference/simple_stmts.html#return) возвращает значение из функции. return без выражения аргумента возвращает None. Выполнение функции до конца также возвращает None.
Выражение result.append(a) вызывает метод спискового объекта result. Метод — это функция, которая «принадлежит» объекту и называется obj.methodname, где obj — это какой-либо объект (это может быть выражение), а methodname — имя метода, который определен типом объекта. Различные типы определяют разные методы. Методы разных типов могут иметь одинаковые имена, при этом не возникает неоднозначности. (Возможно определить ваши собственные типы объектов и методы, используя классы, см. Классы.) Метод append(), показанный в примере, определен для списковых объектов; он добавляет новый элемент в конец списка. В данном примере это эквивалентно result = result + [a], но более эффективно.

4.7. Подробнее об определении функций

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

4.7.1. Значения аргументов по умолчанию

Наиболее полезная форма — это указать значение по умолчанию для одного или более аргументов. Это создает функцию, которая может быть вызвана с меньшим количеством аргументов, чем это определено по умолчанию. Например:

def ask_ok(prompt, retries=4, reminder='Please try again!'):
    while True:
        ok = input(prompt)
        if ok in ('y', 'ye', 'yes'):
            return True
        if ok in ('n', 'no', 'nop', 'nope'):
            return False
        retries = retries - 1
        if retries < 0:
            raise ValueError('invalid user response')
        print(reminder)

Эта функция может быть вызвана несколькими способами:

передачей только обязательного аргумента: ask_ok('Do you really want to quit?')
передачей одного из необязательных аргументов: ask_ok('OK to overwrite the file?', 2)
или даже передачей всех аргументов: ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')

Этот пример также знакомит с ключевым словом in (docs.python.org/3/reference/expressions.html#in). Оно проверяет содержит ли последовательность определенное значение.

Значения по умолчанию вычисляются в точке определения функции в области определения, так что

i = 5
 
def f(arg=i):
    print(arg)
 
i = 6
f()

напечатает 5.

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

def f(a, L=[]):
    L.append(a)
    return L
 
print(f(1))
print(f(2))
print(f(3))

Это напечатает

[1]
[1, 2]
[1, 2, 3]

Если вы не хотите, чтобы по умолчанию было разделено между последующими вызовами, то можете написать функцию как эта:

def f(a, L=None):
    if L is None:
        L = []
    L.append(a)
    return L

4.7.2. Аргументы с ключевым словом

Функции также могут быть вызваны с использованием keyword arguments (docs.python.org/3/glossary.html#term-keyword-argument) вида kwarg=value. Например, следующая функция:

def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
    print("-- This parrot wouldn't", action, end=' ')
    print("if you put", voltage, "volts through it.")
    print("-- Lovely plumage, the", type)
    print("-- It's", state, "!")

принимает один обязательный аргумент (voltage) и три необязательных (state, action и type). Эта функция может быть вызвана любым из следующих способов:

parrot(1000)                                          # 1 позиционный аргумент
parrot(voltage=1000)                                  # 1 аргумент ключевое слово
parrot(voltage=1000000, action='VOOOOOM')             # 2 аргумента ключевых слова
parrot(action='VOOOOOM', voltage=1000000)             # 2 аргумента ключевых слова
parrot('a million', 'bereft of life', 'jump')         # 3 позиционных аргумента
parrot('a thousand', state='pushing up the daisies')  # 1 позиционный, 1 ключевое слово

но все следующие вызовы будут считаться недействительными:

parrot()                     # опущен обязательный аргумент
parrot(voltage=5.0, 'dead')  # аргумент без ключевого слова после аргумента с ключевым словом
parrot(110, voltage=220)     # дублирование значения для одного и того же аргумента
parrot(actor='John Cleese')  # неизвестный аргумент ключевое слово

В вызове функции аргументы с ключевыми словами должны следовать после позиционных аргументов. Все передаваемые аргументы с ключевым словом должны соответствовать одному из аргументов, принимаемых функцией (например, actor не действительный аргумент для функции parrot), и их порядок не важен. Это также включает неопциональные аргументы (например, parrot(voltage=1000) также верно). Ни один аргумент не может получить значение более, чем один раз. Вот пример, который не работает из-за этого ограничения:

>>> def function(a):
...     pass
...
>>> function(0, a=0)
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
TypeError: function() got multiple values for keyword argument 'a'

Когда конечные формальные параметры представлены в форме **name, функция принимает словарь (см. Типы отображений — dict), включающий все аргументы с ключевыми словами за исключением тех, которые уже соответствуют формальным параметрам. Это может быть скомбинировано с формальным параметром в форме *name (описано в следующем подразделе), который получает кортеж, включающий позиционные аргументы за списком формальных параметров. (*name должен находиться перед **name.) Например, если мы определяем функцию, как эту:

def cheeseshop(kind, *arguments, **keywords):
    print("-- Do you have any", kind, "?")
    print("-- I'm sorry, we're all out of", kind)
    for arg in arguments:
        print(arg)
    print("-" * 40)
    keys = sorted(keywords.keys())
    for kw in keys:
        print(kw, ":", keywords[kw])

Она может быть вызвана так:

cheeseshop("Limburger", "It's very runny, sir.",
           "It's really very, VERY runny, sir.",
           shopkeeper="Michael Palin",
           client="John Cleese",
           sketch="Cheese Shop Sketch")

и конечно было бы выведено:

-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
client : John Cleese
shopkeeper : Michael Palin
sketch : Cheese Shop Sketch

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

4.7.3. Произвольные списки аргументов

Наконец, реже используется возможность вызова функции с произвольным числом аргументов. Эти аргументы будут обернуты в кортеж (см. Кортежи и последовательности). Перед переменным числом аргументов могут быть обычные аргументы или не быть ни одного.

def write_multiple_items(file, separator, *args):
    file.write(separator.join(args))

Как правило, эти variadic аргументы будут последними в списке формальных параметров, потому что они собирают все оставшиеся вводимые аргументы, которые передаются в функцию. Любые формальные параметры, которые находятся после параметра *args являются аргументами «только по ключевому слову», это означает, что они могут быть использованы только в качестве ключевых слов, а не позиционных аргументов.

>>> def concat(*args, sep="/"):
...    return sep.join(args)
...
>>> concat("earth", "mars", "venus")
'earth/mars/venus'
>>> concat("earth", "mars", "venus", sep=".")
'earth.mars.venus'

4.7.4. Распаковка списков аргументов

Происходит обратная ситуация, когда аргументы уже в списке или кортеже, но должны быть распакованы при вызове функции, требующей отдельных позиционных аргументов. Например, встроенная функция range() ожидает отдельных аргументов start и stop. Если они не доступны по отдельности, записывают вызов функции с *-оператором для распаковки аргументов из списка или кортежа:

>>> list(range(3, 6)) # нормальный вызов с отдельными аргументами
[3, 4, 5]
>>> args = [3, 6]
>>> list(range(*args)) # вызов с аргументами, распакованными из списка
[3, 4, 5]

В такой же форме словари могут поставлять аргументы с ключевым словом с помощью **-оператора:

>>> def parrot(voltage, state='a stiff', action='voom'):
...     print("-- This parrot wouldn't", action, end=' ')
...     print("if you put", voltage, "volts through it.", end=' ')
...     print("E's", state, "!")
...
>>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
>>> parrot(**d)
-- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !

4.7.5. Lambda-выражения

С помощью ключевого слова lambda (docs.python.org/3/reference/expressions.html#lambda) может быть создана маленькая анонимная функция. Эта функция возвращает сумму ее двух аргументов: lambda a, b: a+b. Lambda-функции могут быть использованы там, где требуются объекты-функции. Синтаксически они ограничены одним выражением. Семантически они являются просто синтаксическим сахаром для обычного определения функции. Как вложенные определения функции lambda-функции могут ссылаться на переменные из содержащей области:

>>> def make_incrementor(n):
...     return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43

Пример выше использует lambda-выражения для возврата функции. Другое использование — это передать небольшую функцию в качестве аргумента:

>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]

4.7.6. Строки документации

Здесь несколько соглашений о содержании и форматировании строк документации.

Первой строке всегда следует быть короткой, краткая сводка назначения объекта. Для краткости не следует явно указывать имя или тип объекта, поскольку они доступны другими способами (за исключением, если имя оказывается глаголом, описывающим операцию функции). Эта строка должна начинаться с заглавной буквы и заканчиваться точкой.

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

Анализатор Python не удаляет отступ из многострочных строковых литералов, так что инструменты, которые обрабатывают документацию, должны удалять отступы, если это необходимо. Это делается с помощью следующего соглашения. Первый непустая линия после первой строки определяет размер отступа для всей строки документации. (Мы не можем использовать первую строку, поскольку она, как правило, примыкает к открывающим кавычкам строки, так что ее отступ не является очевидным в строковом литерале.) Пробелы «эквивалентные» этому отступу затем удаляются из начала всех линий строки. Линий с меньшим отступом быть не должно, но если они есть, все их ведущие пробелы должны удаляться. Эквивалентность пробелов должна быть проверена после расширения табуляций (до 8 пробелов, как правило).

Вот пример многострочной строки документации:

>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything.
...     """
...     pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.
 
    No, really, it doesn't do anything.

4.7.7. Аннотации функций

Function annotations (docs.python.org/3/reference/compound_stmts.html#function) являются полностью необязательными метаданными о типах, используемых пользовательскими функциями (см. PEP 484 (python.org/dev/peps/pep-0484) для получения дополнительной информации).

Аннотации хранятся в атрибуте __annotations__ функции как словарь и не имеют никакого эффекта на любую другую часть функции. Параметры аннотаций определяются двоеточием после имени параметра, за которым следует выражение, оценивающее значение аннотации. Возвращения аннотации определяются литералом ->, следующим выражению, между списком параметра и двоеточием, обозначая конец оператора def (docs.python.org/3/reference/compound_stmts.html#def). Следующий пример имеет позиционный аргумент, аргумент с ключевым словом и аннотированное возвращаемое значение:

>>> def f(ham: str, eggs: str = 'eggs') -> str:
...     print("Annotations:", f.__annotations__)
...     print("Arguments:", ham, eggs)
...     return ham + ' and ' + eggs
...
>>> f('spam')
Annotations: {'ham': <class 'str'>, 'return': <class 'str'>, 'eggs': <class 'str'>}
Arguments: spam eggs
'spam and eggs'

4.8. Стиль кодирования

Теперь, когда вы собираетесь писать более длинный, более сложный код на Python, настало время поговорить о coding style (стиле кодирования — прим. пер.). В большинстве языков можно писать (или по-другому, форматировать) в различных стилях; некоторые из них более читабельные, чем другие. Создание кода более читаемого для других — всегда хорошая идея, и принятый хороший стиль кодирования чрезвычайно помогает этому.

Для Python, появился PEP 8 (python.org/dev/peps/pep-0008) как руководство по стилю, которого придерживается большинство проектов; он поощряет хорошо читаемый и приятный для глаз стиль кодирования. Каждый разработчик Python должен прочитать это однажды; вот наиболее важные извлеченные пункты для вас:

Используйте 4-х-пробельный отступ, а не табуляцию.
4 пробела — хороший компромисс между маленьким отступом (позволяет большую глубину вложенности) и большим отступом (легче для чтения). Табуляции вносят путаницу, и лучше опустить их.
Делайте строки длиной не более 79 символов.
Это поможет пользователям с маленькими дисплеями и сделает возможным расположить рядом несколько файлов с кодом на больших дисплеях.
Используйте пустые строки для отделения функций и классов, а большие блоки кода помещайте внутрь функций.
Когда возможно, оставляйте комментарии на их собственной строке.
Используйте строки документации.
Используйте пробелы вокруг операторов и после запятой, но не непосредственно внутри конструкции скобок: a = f(1, 2) + g(3, 4).
Называйте ваши классы и функции последовательно; соглашением является использование CamelCase («верблюжьей» нотации — прим. пер.) для классов и lower_case_with_underscores (нижнего регистра с подчеркиванием — прим. пер.) для функций и методов. Всегда используйте self в качестве имени первого аргумента метода (см. Первый взгляд на классы для большей информации о классах и методах).
Не используйте причудливые кодировки, если ваш код предназначен для использования в международной среде. По умолчанию в Python UTF-8 или даже обычный ASCII работает лучше в любом случае.
Точно так же не используйте не-ASCII символы в идентификаторах, если есть хотя бы малейший шанс, что люди, говорящие на другом языке, будут читать или поддерживать этот код.

Примечания

[1] На самом деле, вызов по ссылки на объект было бы лучшим описанием, поскольку если передается изменяемый объект, тот кто вызывает будет видеть любые изменения, которые вызываемый сделает с ним (элементы вставляются в список).

Ресурсы по Python — документация Python 3.x

Чтение этого учебника вероятно усилило ваш интерес к Python — вы должно быть в нетерпении применить его для решения ваших практических задач. Куда следует обратиться, чтобы узнать больше?

Данный учебник лишь часть набора документации Python. Некоторая другая документация:

Стандартная библиотека Python:
Вам следует сделать обзор этого руководства, которое дает полное (хотя краткое) упоминание материала о типах, функциях и модулях стандартной библиотеки. Стандартная поставка Python включает множество дополнительного кода. Там есть модули для чтения почтовых ящиков Unix, извлечения документов через HTTP, генерации случайных чисел, анализа опций командной строки, написания CGI-программ, сжатия данных и многих других задач. Беглое прочтение справочной библиотеки даст вам понимание того, что доступно.
Installing Python Modules (docs.python.org/3/installing/index.html#installing-index) объясняет, как установить дополнительные модули, написанные другими пользователями Python.
Справочник по языку Python: Детальное объяснение синтаксиса и семантики Python. Это тяжелое чтение, но полезное как полное руководство по самому языку.

Дополнительные ресурсы по Python:

https://www.python.org: Главный веб-сайт о Python. Содержит код, документацию, указатели на связанные с Python страницы по всему Web. Этот сайт имеет зеркала в различных частях мира, таких как Европа, Япония и Австралия; зеркало может быть быстрее, чем главный сайт, это зависит от вашего географического положения.
https://docs.python.org: Быстрый доступ к документации Python.
https://pypi.python.org/pypi: Индекс пакетов Python, ранее также названный Cheese Shop, представляет собой индекс созданных пользователями модулей, которые доступны для загрузки. Если вы когда-нибудь создадите код, вы можете зарегистрировать его здесь, так что другие пользователи найдут его.
https://code.activestate.com/recipes/langs/python/: Поваренная книга Python представляет собой большую коллекцию примеров кода, больше модулей и полезных скриптов. Особенно выдающийся вклад собирается в книге также названной Python Cookbook (O’Reilly & Associates, ISBN 0-596-00797-3.)
http://www.pyvideo.org собирает ссылки на связанное с Python видео конференций и встреч групп пользователей.
https://scipy.org: Проект научного Питона включает модули для быстрых множественных вычислений и манипуляций плюс множество пакетов для таких вещей как линейная алгебра, преобразования Фурье, нелинейные вычислители, раздачи случайных чисел, статистический анализ и тому подобное.

Связанные с Python вопросы и отчеты по проблемам вы можете отправлять новостной группе comp.lang.python или послать их списком рассылки [email protected]. Новостная группа и список рассылки — шлюз. Поэтому сообщения будут автоматически перенаправлены другим. Приходят сотни сообщений в день, спрашивающих (и отвечающих) вопросов, предложений новых возможностей и анонса новых модулей. Архивы списка рассылки доступны на https://mail.python.org/pipermail/.

Прежде чем писать сообщение, проверьте список Часто Спрашиваемых Вопросов (docs.python.org/3/faq/index.html#faq-index) (также называемый FAQ). Он отвечает на многие вопросы, которые приходят снова и снова. Они могут уже содержать решение вашей проблемы.

Содержание документации Python — документация Python 3.8.6

Что нового в Python
- Что нового в Python 3.8
  - Сводка — основные моменты выпуска
  - Новые возможности
    - Выражения присваивания
    - Позиционные параметры
    - Кэш параллельной файловой системы для скомпилированных файлов байт-кода
    - использует тот же ABI, что и сборка выпуска
    - Поддержка f-строк = для самодокументируемых выражений и отладки
    - PEP 578: Хуки для аудита времени выполнения Python
    - PEP 587: конфигурация инициализации Python
    - Vectorcall: протокол быстрого вызова для CPython
    - Протокол Pickle 5 с внеполосными буферами данных
  - Другие языковые изменения
  - Новые модули
  - Улучшенные модули
    - ast
    - asyncio
    - встроенных
    - коллекций
    - cПрофиль
    - CSV
    - проклятий
    - cтипов
    - дата и время
    - функций
    - gc
    - gettext
    - gzip
    - IDLE и idlelib
    - осмотреть
    - io
    - itertools
    - json.инструмент
    - лесозаготовка
    - математика
    - mmap
    - многопроцессорность
    - ос
    - os.path
    - pathlib
    - рассол
    - плистлиб
    - стр.
    - py_compile
    - шлекс
    - шутиль
    - розетка
    - SSL
    - статистика
    - систем
    - tarfile
    - нарезание резьбы
    - токенизировать
    - tkinter
    - время
    - набор
    - unicodedata
    - юниттест
    - Венв
    - weakref
    - xml
    - xmlrpc
  - Оптимизация
  - Изменения в сборке и C API
  - Устарело
  - API и удаление функций
  - Перенос на Python 3.8
    - Изменения в поведении Python
    - Изменения в Python API
    - Изменения в C API
    - Изменения байт-кода CPython
    - Демонстрации и инструменты
  - Заметные изменения в Python 3.8.1
  - Заметные изменения в Python 3.8.2
  - Заметные изменения в Python 3.8.3
- Что нового в Python 3.7
  - Резюме — основные моменты выпуска
  - Новые функции
    - PEP 563: отложенная оценка аннотаций
    - PEP 538: Принуждение устаревшего языка C
    - PEP 540: принудительный режим выполнения UTF-8
    - PEP 553: встроенная точка останова ()
    - PEP 539: новый C API для локального хранилища потоков
    - PEP 562: Настройка доступа к атрибутам модуля
    - PEP 564: Новые функции времени с наносекундным разрешением
    - PEP 565: Показать предупреждение об устаревании в __main__
    - PEP 560: основная поддержка , набирающего модуль и универсальных типов
    - PEP 552: на основе хэша.pyc Файлы
    - PEP 545: Перевод документации Python
    - Режим времени разработки: -X dev
  - Другие языковые изменения
  - Новые модули
    - contextvars
    - классы данных
    - importlib.resources
  - Улучшенные модули
    - argparse
    - asyncio
    - binascii
    - календарь
    - коллекций

Содержание документации Python — документация Python 3.3.7

Что нового в Python
- Что нового в Python 3.3
  - Резюме — основные моменты выпуска
  - PEP 405: виртуальные среды
  - PEP 420: неявные пакеты пространства имен
  - PEP 3118: новая реализация memoryview и документация протокола буферизации
    - Features
    - Изменения API
  - PEP 393: гибкое представление строки
    - Функциональность
    - Производительность и использование ресурсов
  - PEP 397: программа запуска Python для Windows
  - PEP 3151: переработка иерархии исключений ОС и ввода-вывода
  - PEP 380: синтаксис для делегирования субгенератору
  - PEP 409: контекст исключения исключения
  - PEP 414: явные литералы Unicode
  - PEP 3155: Полное имя для классов и функций
  - PEP 412: Словарь совместного использования ключей
  - PEP 362: объект сигнатуры функции
  - PEP 421: Добавление sys.реализация
    - SimpleNamespace
  - Использование importlib как реализация импорта
    - Новые API
    - Видимые изменения
  - Другие языковые изменения
  - Мелкозернистый импортный фиксатор
  - Встроенные функции и типы
  - Новые модули
    - Обработчик неисправностей
    - IP-адрес
    - lzma
  - Улучшенные модули
    - abc
    - массив
    - base64
    - binascii
    - bz2
    - кодеков
    - коллекций
    - contextlib
    - склеп
    - проклятий
    - дата и время
    - десятичное
      - Характеристики
      - Изменения API
    - электронная почта
      - Основы политики
      - Предварительная политика с новым API заголовков
      - Другие изменения API
    - ftplib
    - функций
    - gc
    - hmac
    - http
    - html
    - imaplib
    - осмотреть
    - io
    - itertools
    - лесозаготовка
    - математика
    - mmap
    - многопроцессорность
    - ннтплиб
    - ос
    - PDB
    - рассол
    - pydoc
    - re
    - sched
    - выберите
    - шлекс
    - шутиль
    - сигнал
    - smtpd
    - смтплиб
    - розетка
    - сервер сокетов
    - sqlite3
    - SSL
    - стат
    - структура
    - подпроцесс
    - систем
    - tarfile
    - временный файл
    - текст
    - нарезание резьбы
    - время
    - типов
    - юниттест
    - urllib
    - веб-браузер
    - xml.etree.ElementTree
    - злиб
  - Оптимизация
  - Изменения в сборке и C API
  - Устарело
    - Операционные системы, не поддерживаемые
    - Устаревшие модули, функции и методы Python
    - Устаревшие функции и типы C API
    - Устарело f

Стандартная библиотека Python — документация Python 2.7.18

Хотя справочник по языку Python описывает точный синтаксис и
семантика языка Python, это справочное руководство по библиотеке
описывает стандартную библиотеку, которая распространяется вместе с Python. Это также
описывает некоторые из дополнительных компонентов, которые обычно включены
в дистрибутивах Python.

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

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

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

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

1. Введение
2.Встроенные функции
3. Несущественные встроенные функции
4. Встроенные константы
5. Встроенные типы
- 5.1. Проверка истинности
- 5.2. Логические операции — и , или , не
- 5.3. Сравнения
- 5.4. Числовые типы — int , float , long , сложный
- 5.5. Типы итераторов
- 5.6. Типы последовательностей — str , unicode , list , tuple , bytearray , buffer , xrange
- 5.7. Типы наборов — набор , морозильник
- 5,8. Типы отображения — dict
- 5.9. Файловые объекты
- 5.10. Тип памяти
- 5.11. Типы диспетчера контекста
- 5.12. Другие встроенные типы
- 5.13. Специальные атрибуты
6. Встроенные исключения
7. Строковые службы
8. Типы данных

7. Документирование Python — Руководство разработчика Python

Язык Python содержит значительный объем документации, большая часть которой
предоставлено различными авторами. Разметка документации Python:
reStructuredText, разработанный в рамках проекта Docutils, измененный пользовательскими
директивы и с помощью набора инструментов Sphinx для постобработки вывода HTML.

Этот документ описывает руководство по стилю для нашей документации, а также
настраиваемая разметка reStructuredText, представленная Sphinx для поддержки Python
документацию и как ее использовать.

7.1. Введение

Документация

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

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

Этот документ предназначен для авторов и потенциальных авторов документации по
Python. В частности, это для людей, вносящих свой вклад в стандарт
документации и разработки дополнительных документов с использованием тех же инструментов, что и
стандартные документы. Это руководство будет менее полезным для авторов, использующих Python.
инструменты документации по темам, отличным от Python, и менее полезные для
авторы вообще не используют инструменты.

Если вы заинтересованы в разработке документации Python, но не
есть время или желание изучить reStructuredText и структуры разметки
задокументировано здесь, среди авторов Python найдется место для вас.
также.Каждый раз, когда вы чувствуете, что можете уточнить существующую документацию или
предоставит недостающую документацию, существующая группа документации предоставит
с радостью поработаем с вами, чтобы интегрировать ваш текст, занимаясь разметкой за вас.
Пожалуйста, не позволяйте материалу этого документа стоять между документами.
и ваше желание помочь!

7.2. Руководство по стилю

7.2.1. Использование пробелов

Во всех файлах reST используется отступ в 3 пробела; вкладки не допускаются. В
максимальная длина строки составляет 80 символов для обычного текста, но таблицы, глубоко
примеры кода с отступом и длинные ссылки могут выходить за рамки этого.Пример кода
тела должны использовать обычный Python 4-пробельный отступ.

По возможности используйте пустые строки; они помогают группировать вещи
вместе.

Точка в конце предложения может сопровождаться одним или двумя пробелами; в то время как reST
игнорирует второй пробел, он обычно вставляется некоторыми пользователями, например
для помощи в режиме автозаполнения Emacs.

7.2.3. Капитализация

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

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

Примечание

Разделы, описывающие библиотечный модуль, часто имеют заголовки в
форма «имя модуля — Краткое описание модуля». В этом
случае, описание должно быть написано с заглавной буквы как отдельное
предложение.

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

Отдельного упоминания заслуживают и другие термины и слова; эти конвенции должны
использоваться для обеспечения единообразия всей документации:

ЦП: Для «центрального процессора».»Многие руководства по стилю говорят, что это должно быть
прописано при первом использовании (и если вы должны его использовать, сделайте это!). За
в документации Python этого сокращения следует избегать, поскольку
нет разумного способа предсказать, какое событие будет
впервые увиденное читателем. Лучше использовать слово «процессор».
вместо.
POSIX: Название, присвоенное определенной группе стандартов. Это всегда
верхний регистр.
Python: Название нашего любимого языка программирования всегда пишется с большой буквы.
reST: Для «reStructuredText»: простой для чтения синтаксис разметки открытого текста.
используется для создания документации Python. Когда прописано, это
всегда одно слово, и обе формы начинаются со строчной буквы «r».
Юникод: Название системы кодировки символов. Это всегда пишется
заглавные.
Unix: Название операционной системы, разработанной в AT&T Bell Labs в начале
1970-е годы.

7.2.4. Утвердительный тон

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

За исключением определенных рисков безопасности или segfault, в документации следует избегать
формулировки «признак x опасен» или «только для экспертов». Эти
виды оценочных суждений относятся к внешним блогам и вики, а не к ядру
документация.

Плохой пример (вызывающий беспокойство у читателя):

Предупреждение: неспособность явно закрыть файл может привести к потере данных или
чрезмерное потребление ресурсов. Никогда не полагайтесь на подсчет ссылок на
автоматически закрыть файл.

Хороший пример (установление уверенных знаний об эффективном использовании
язык):

Лучшим способом использования файлов является использование пары try / finally для явного
закрыть файл после его использования. В качестве альтернативы использование оператора with может
добиться того же эффекта. Это гарантирует, что файлы будут сброшены и
ресурсы дескриптора высвобождаются своевременно.

7.2.5. Экономия выражения

Больше документации не обязательно означает лучшую документацию.Ошибка на стороне
быть лаконичным.

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

7.2.6. Соображения безопасности (и другие проблемы)

Некоторые модули, поставляемые с Python, по своей сути подвержены проблемам безопасности.
(е.г. уязвимости, связанные с внедрением оболочки) из-за назначения модуля
(например, ssl ). Засорять документацию этих модулей красным
окна с предупреждениями о проблемах, которые связаны с выполняемой задачей, а не
конкретно для поддержки Python для этой задачи, не способствует хорошему
опыт чтения.

Вместо этого, эти проблемы безопасности должны быть собраны в специальный
Раздел «Вопросы безопасности» в документации модуля и
перекрестная ссылка из документации затронутых интерфейсов с примечанием
аналогично "См. раздел: ref:` security-considerations` для получения важной информации о том, как избежать типичных ошибок.«.

Аналогично, если есть общая ошибка, которая влияет на многие интерфейсы в
модуль (например, заполнение буферов канала уровня ОС и остановка дочерних процессов),
их можно задокументировать в разделе «Распространенные ошибки» и дать ссылки на них.
а не повторяться для каждого затронутого интерфейса.

7.2.7. Примеры кода

Примеры сокращенного кода c