[Перевод] Учимся читать код, изучая стандартную библиотеку Python05.07.2021 15:31

Итак, вы уже продвинутый новичок — вы изучили основы Python и способны решать реальные задачи.

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

Наверно, вы слышали, что нужно нарабатывать понимание чтением и написанием больших объёмов кода. Это правда.

Но какой же код нужно читать?

«Просто читай то, что нравится». А если вы не знаете, что вам нравится? А если вам не нравится что-то правильное?

Или хуже того — если вам нравится что-то неправильное и из-за этого у вас выработаются вредные привычки?

В конечном итоге, для этого ведь необходимо понимание… Но именно его мы и стремимся обрести.

«На GitHub куча проектов — выберите понравившийся и изучайте, как его реализовали разработчики». Однако самые успешные проекты довольно объёмны — с чего начинать?

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

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

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

В этой статье мы рассмотрим некоторые модули стандартной библиотеки Python.

Примечание о стандартной библиотеке

В целом, стандартная библиотека Python неидеальна для изучения «хорошего» стиля.

Хотя все её модули полезны, они не особо однородны:

их писали разные авторы;
некоторые из них старые (стиль Python 10–20 лет назад был другим);
им нужно было сохранять обратную совместимость (то есть невозможно провести рефакторинг багов и вносить крупные изменения в API).

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

Мы рассмотрим как раз некоторые из них.

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

Любопытно изучить различия в возможностях stdlib и её новых внешних альтернатив — разница между ними демонстрирует дефицит, который испытывают разработчики (ведь в противном случае они бы не заморачивались созданием альтернативы). Хорошим примером этого является разница между urllib и requests.

Как читать модули

Приблизительно в таком порядке:

Познакомьтесь с библиотекой как пользователь: прочитайте документацию, поэкспериментируйте с примерами.
Прочитайте соответствующее Python Enhancement Proposal (PEP). Интересное обычно содержится в разделах Abstract, Rationale, Design Decisions, Discussion и Rejected Ideas.
Прочитайте код; ссылка на него приведена в начале каждой страницы документации.

statistics

Модуль statistics добавляет в стандартную библиотеку статистические функции; он не создавался в качестве конкурента таких библиотек, как NumPy, а «находится на уровне построителя графиков и научного калькулятора».

Он был внедрён в PEP 450. Если вы незнакомы с этим предложением, то это очень любопытное чтиво:

В разделе Rationale предложение сравнивается с NumPy и самодельными решениями; он особенно хорошо демонстрирует, что и почему было добавлено в стандартную библиотеку.
Также там есть раздел Design Decisions, в котором объясняется, какой была общая философия проектирования; в разделах Discussion и FAQ тоже есть интересные подробности.

Кроме того, документация очень удобна. Это сделано нарочно; цитата из предложения:

«Большая часть документации предназначена для читателей, понимающих базовые концепции, но которые могут не знать (например), какую дисперсию им стоит использовать […] Однако документация избегает скучных математических подробностей».

Код относительно прост, а когда это не так, то в нём есть комментарии и ссылки на подробные объяснения или статьи. Это может быть полезным, если вы изучаете все эти концепции и вам проще читать код, чем математическиe условные обозначения.

pathlib

Модуль pathlib обеспечивает простую иерархию классов для работы с путями файловой системы; он является высокоуровневой альтернативой os.path.

Модуль был внедрён в PEP 428. Большинство примеров используется для иллюстрации лежащей в основе модуля философии, а код оставлен в качестве спецификации.

Код хорошо читается по следующим причинам:

Вероятно, вы уже знакомы с этой тематикой; даже если вы не пользовались раньше pathlib, то могли работать с os.path, или с похожей библиотекой в каком-то другом языке.
Это хорошее объектно-ориентированное решение. Оно использует объектно-ориентированное программирование с абстрактными (читай: изобретёнными) концепциями, чтобы улучшить структуру кода и его многократное использование. Наверно, это гораздо лучший пример, чем старый Animal–Dog–Cat–Duck–speak ().
Это хорошая тема для сравнительного изучения: pathlib и os.path решают одну задачу, однако в совершенно разных стилях программирования. Кроме того, существовало ещё одно предложение, которое было отклонено, а ещё есть не меньше пяти похожих библиотек; pathlib позаимствовал что-то от каждой из них.

dataclasses

Модуль dataclasses снижает объём бойлерплейта при написании классов, генерируя специальные методы наподобие __init__ и __repr__. (См. в качестве введения этот туториал, потому что в нём используются гораздо более конкретные примеры, чем в официальной документации.)

Он был внедрён в PEP 557 в качестве упрощённой версии attrs. Раздел Specification схож с документацией; интересные вещи встречаются в Rationale, Discussion и Rejected Ideas.

Код превосходно откомментирован; особенно любопытно это использование таблиц решений
(ASCII-версия, версия со вложенными if).

Кроме того, это отличный пример метапрограммирования; этот аспект подробно рассматривается в докладке Реймонда Хеттингера Dataclasses: The code generator to end all code generators. [Слайды с доклада в HTML и PDF.] Если у вас возникли проблемы с пониманием кода, то сначала посмотрите доклад; для меня оказалось довольно полезным объяснение генерируемого кода.

Бонус: graphlib

Модуль graphlib был добавлен в Python 3.9, и на данный момент содержит только одну вещь: реализацию алгоритма топологической сортировки (вот описание того, что это такое, и почему он полезен).

Он появился не через PEP; однако у него есть issue со множеством комментариев от разных разработчиков ядра, в том числе Реймонда Хеттингера и Тима Питерса (известного своим «Дзен языка Python»).

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

В обсуждении пытаются примирить два различных способа использования модуля:

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

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

По сравнению с обсуждением issue, сам код очень мал — меньше 250 строк, и в основном состоит из комментариев и документации.

На правах рекламы

Серверы для разработчиков и не только! Дешёвые VDS на базе новейшего «железа» для размещения проектов любой сложности, от корпоративных сетей и игровых проектов до лендингов и VPN.

Подписывайтесь на наш чат в Telegram.