Путеводитель по Python. Пишем великолепный код

Доброго времени суток, Хабрахабр. Сегодня на крыле принес еще один перевод я (pdf ^[1]-ки гугловского стайл гайда ^[2] выложены). Хотя, кто знает, если кто-то оценит сию работу — быть может появится и продолжение. Как-то днём одним, предложил мне мой широко известный в узких кругах коллега scraplesh ^[3] почитать ресурс — The Hitchhiker’s Guide to Python! ^[4] называемый. Ресурс этот понравился мне. Понравились советы выдаваемые там. Понравилась канва повествования и вообще понравилось направление мысли автора. А если что-то хорошо на Ваш вкус, то нужно передавать это из уст в уста:) Итак, решил я сделать перевод данного ресурса. Но не всё так сразу — сначала будет пробная статья «на отклик» хабрасообщества. Если уважаемым гикам понравится сия тематика и изложение — будем стараться выпускать новые части. На первый «отклик» я выбрал раздел — "Writing Great Code ^[5]" и в нем два подпункта «Structure is Key» и «Modules». Откликнемся под катом.

Но перед тем, как окунуться с головой в чужие мысли относительно любимого Python, нужно представить собственно автора ресурса. Зовут его Kenneth Reitz ^[6]. Как я понял по собранной информации — он профессиональный фотограф (об этом мы можем узнать на его личном сайте ^[7]), евангелист языка Python и просто гуру разного рода разработки. Работает он на данный момент (по неподтвержденным данным) в Heroku. Так же перепризываю всех форкать его проект на гитхаб ^[8].

Далее — собственно сама статья. (При обнаружении ошибок, как водится — сразу кричите о них! Ошибки требуют исправления.)

Структурируйте свой проект

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

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

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

Структура решает

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

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

• Множественные и грязные циклические зависимости. Если Ваши классы Table и Chair нуждаются в импорте класса Carpenter из модуля workers.py, для того, чтобы ответить на вопрос table.isdoneby(), и наоборот, если класс Carpenter нуждается в импорте класса Table и класса Chair, чтобы ответить на вопрос carpenter.whatdo() — Вы получаете циклическую зависимость. В этом случае Вам придется прибегнуть к хитрым уловкам, таким как использование оператора импорта внутри методов или функций.
• Скрытые связи. Все и каждое изменение в классе Table проваливает 20 тестов в несвязанных тестах, т.к. оно извращает выполнение кода класса Carpenter, который требует хирургически тонкого адаптивного изменения кода. Это означает, что у Вас слишком много «договоренностей» относительно класса Table в коде класса Carpenter или наоборот.
• Интенсивное использование глобального пространства имен или контекста. Вместо явной передачи (высота, ширина, тип, дерево) друг другу переменных классами Table и Carpenter, Вы полагаетесь на глобальные переменные, которые могут быть изменены и модифицированы на лету разными «товарищами». Вы должны внимательно изучить все места, откуда можно получить доступ к этим глобальным переменным, чтобы понять, почему прямоугольный стол стал квадратным и обнаружить, что удаленный код так же подвергся изменению в данном контексте, подменив размеры стола.
• Спагетти-код. Несколько страниц вложенных друг в друга конструкций if и циклов for с большим количеством повторяющегося кода и вообще не сегментированного, известного как спагетти, кода. Благодаря значащим отступам в Python (одной из самых обсуждаемых особенностей), очень сложно писать такой код на данном языке. Так что есть хорошие новости — Вы не будете наблюдать такой код часто.
• Равиоли-код. Такой код более типичен для Python. Он состоит из сотен одинаковых (или подобных друг другу) кусочков логики, классов или объектов без надлежащей структуризации. Если Вы никак не можете запомнить не использовать FurnitureTable, AssetTable или Table, или даже TableNew для решения Вашей задачи — Вы будете купаться в равиоли-коде.

Модули

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

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

Как только Вы начинаете использовать выражение import — Вы начинаете использовать модули. Это могут быть встроенные модули, такие как os и sys, сторонние модули, которые Вы установили в свою среду, или внутренние модули Вашего проекта.

Чтобы придерживаться стиля руководства, старайтесь давать модулям короткие имена, содержащие только буквы нижнего регистра и уверяться, что Вы не используете специальные символы, такие как точка(.) или знак вопроса (?). Так как имя файла подобное my.spam.py, Вы должны избегать. Именование таким образом будет мешать Python искать модули.

В данном примере Python ожидает найти «spam.py» в папке по имени «my», которой не существует. Существует пример того, как точечная нотация должна быть использована в документах Python.

Если Вы хотите, Вы можете назвать файл my_spam.py, но даже нашего друга — Подчеркивание — не стоит часто использовать в именах модулей.

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

Откровенно говоря, оператор импорта будет искать соответствующий файл module.py в той же директории, где находится импортирующий файл. Если он не будет найден, интерпретатор Python будет искать module.py в переменной «path» рекурсивно и возбудит исключение ImportError, если последний не будет найден.

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

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

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

Это позволяет моделировать более стандартное поведение с помощью специального синтаксиса выражения import: from module import *. Обычно это считается плохой практикой. Использование «import *» делает код трудным для чтения и делает зависимости менее разобщенными.

Использование from module import func это способ точно указать функцию, которую вы ходите импортировать и поместить в глобальную область видимости. А так же это намного менее вредно, чем «import *» т.к. тут ясно видно что импортируется в глобальную область видимости, преимущество более простой записи import module заключается в экономии нажатий клавиш.

# Very bad

[...]
from modu import *
[...]
x = sqrt(4)  # Is sqrt part of modu? A builtin? Defined above?
# Better

from modu import sqrt
[...]
x = sqrt(4)  # sqrt may be part of modu, if not redefined in between
# Best

import modu
[...]
x = modu.sqrt(4)  # sqrt is visibly part of modu's namespace

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

Автор: Lovesuper

Источник ^[9]