Python как оформить программу

Правила оформления программ на Python

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

2. Функции разделяйте двумя пустыми строками. Смысловые блоки внутри одной функции разделяйте одной пустой строкой.

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

spam(ham[1], ) # Правильно spam ( ham [ 1 ], < eggs: 2 >) # Неправильно

4. Перед запятой и двоеточием пробел не ставится, после — ставится.

# Правильно if x == 4: print(x, y) x, y = y, x # Неправильно if x == 4 : print(x , y) x,y = y,x

5. Не располагайте несколько инструкций в одной строке. Разнесите их по разным строкам.

# Правильно x = 35 func(10) # Неправильно x = 35; func(10)

6. Ширина строки не должна превышать 80-100 символов.

Модули

1. Пишите import каждого модуля в отдельной строке.

# Правильно import math import sys # Неправильно import sys, math

2. Располагайте все import 'ы в верхней части файла перед любыми глобальными объявлениями.

3. Не используйте конструкцию from . import * .

# Правильно import math from sys import stdin, stdout stdin.write(str(math.sqrt(4.0))) # Неправильно from sys import *

Комментарии

1. Комментарии, противоречащие коду, хуже, чем их отсутствие.

2. Располагайте однострочные комментарии после кода в той же строке и отделяйте их от кода двумя пробелами. Комментарии должны начинаться с # и одного пробела.

Имена

1. Не используйте символы «l», «O», «o», и «I» как имена переменных. В некоторых шрифтах они могут быть очень похожи на цифры.

2. Название переменной должно содержать информацию о ее назначении, не допускается использование названий из одной буквы, за исключением счетчиков в циклах (i, j, k) и переменных, хранящих размер входных данных (n, m).

3. Давайте переменным говорящие английские имена, не используйте транслит.

num_letters = int(input()) # Правильно kolvo_bukv = int(input()) # Неправильно

4. Имена переменных и функций должны содержать только маленькие буквы. Слова разделяются символами подчёркивания. Примеры: name , name_with_several_words_in_it . Допускается также записывать начальные буквы каждого слова с заглавной буквы, при этом символы подчёркивания не ставятся: wordLength .

5. Имена констант должны содержать только заглавные буквы. Слова разделяются символами подчёркивания. Примеры: NAME , NAME_WITH_SEVERAL_WORDS_IN_IT .

Урок 6. Как запускать Python программы

В прошлом уроке мы запустили свою первую программу на Python, она вывела фразу "Hello, World!". И эту программу мы запустили с помощью PyCharm.

Однако это не единственный способ выполнять Python-скрипты. Рассмотрим еще несколько вариантов.

И первый — это запуск программ из командной строки. Введем в строке поиска введем cmd и кликнем по найденной программе. Появилось черное окно — это командная строка. Мы уже запускали её ранее, когда проверяли установлен ли Python.

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

Чтобы в командной строке запустить Python-программу нужно сперва перейти в каталог, где эта программа расположена.

По умолчанию после открытия терминала мы находимся в домашней папке активного Windows-пользователя. И так как все наши проекты хранятся в каталоге PycharmProjects, то нужно ввести:

cd PycharmProjects

cd — это команда для смены текущего каталога. Сокращение от Change dir. Нажмем Enter. И мы в каталоге с проектами. Теперь перейдем непосредственно в наш проект. Снова ведем команду cd после которой укажем имя проекта (sepython):

cd sepyhton

Нажму Enter. Командная строка вывела, что системе не удается найти указанный путь. Если вы видите такую же надпись, то причин может быть две:

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

Чтобы проверить какие файлы или каталоги есть в текущей директории, надо набрать команду dir.

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

Для этого надо снова ввести команду cd, за ней пробел, а после написать se и нажать клавишу Tab. Командная строка сама дополнит имя каталога до правильного. После чего нужно снова нажать Enter и нас сразу переместит в каталог с проектом.

Если мы еще раз выполним комунд dir, то увидим каталоги Lessons и Tasks, а также файл main.py.

Что ж, нам надо запустить нашу программу hello_world.py, а она находится в папке Lessons. Перейдем в неё:

cd Lessons

Теперь надо запустить hello_world.py и для этого надо сперва написать python, а затем через пробел имя программы hello_world.py:

python hello_world.py

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

Что ж, нажму Enter! Программа вывела фразу "Hello, world! Отлично, у нас всё получилось.

Теперь давайте рассмотрим несколько распространенных ошибок, которые у вас могут возникнуть на данном этапе. Первая — это снова опечатка. Если поменять два последних символа местами и снова попробовать запустить программу, то мы увидим ошибку, что файл hello_world.yp не найден в текущем каталоге. Когда вы видите такую ошибку, то это повод проверить имя файла, а также его реальное присутствие в данной директории.

В целом с hello_world мы закончили, и осовная проблема данной прогарммы в том, что она всегда будет выводить фразу, которую мы задали внутри программы, а это делает код абсолютно бесполезным. Другое дело hello_user.py, которую я добавил самостоятельно (у вас этой программы пока нет).

Сейчас я покажу как она работает, а в следующем уроке покажу и объясню её исходный код. То есть то, что находится внутри скрипта.

Итак давайте введем:

python hello_user.py

Программа вывела что-то непонятное. На самом деле она завершилась с ошибкой. Дело в том, что скрипт hello_user.py нужно запускать с передачей аргументов или другими словами с передачей дополнительных параметров.

Это значит, что нужно писать python hello_user.py плюс еще какой-то текст, например такой:

python hello_user.py Nikita

В этом случае слово Nikita — это аргумент командной строки, который при запуске будет отправлен в программу hello_user.py.

То есть сейчас в строке три элемента: сам python, имя программы hello_user.py и аргумент командной строки Niktia.

Python запустит программу hello_user.py и передаст в неё слово Nikita. Программа в свою очередь примет это слово и что-то с ним сделает. Давайте посмотрим, что именно, нажмем Enter..

Скрипт отработал без ошибок и поздоровался с нами: "Hello Nikita. Отлично.

Если при запуске передать другой параметр, например Nikita заменить Alena, то скрипт поздоровается с Аленой:

python hello_user.py Alena

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

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

Следующий урок

Урок 7. Запуск программ с одним аргументом

В этом уроке вы узнаете как писать python-программы, которые принимают аргументы командой строки, а также о том, как из запускать.

Посмотреть

Полный курс с практикой

• 146 уроков
• 306 заданий
• Сертификат
• Поддержка преподавателя
• Доступ к курсу навсегда

• Можно в рассрочку

Как организовать код в Python-проекте, чтобы потом не пожалеть

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

Python — это самый гибкий язык программирования из тех, с которыми мне приходилось сталкиваться. А когда имеешь дело с чем-то «слишком гибким» — возрастает вероятность принятия неправильных решений.

• Хотите держать все классы проекта в единственном файле main.py ? Да, это возможно.
• Надо читать переменную окружения? Берите и читайте там, где это нужно.
• Требуется модифицировать поведение функции? Почему бы не прибегнуть к декоратору!?

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

Но, если вы точно знаете о том, что делаете, последствия гибкости Python не обязательно окажутся плохими.

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

Структура Python-проекта

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

Рекомендую держать все файлы модулей в директории src , а тесты — в поддиректории tests этой директории:

 ├── src │ ├── /* │ │ ├── __init__.py │ │ └── many_files.py │ │ │ └── tests/* │ └── many_tests.py │ ├── .gitignore ├── pyproject.toml └── README.md

Здесь — это главный модуль проекта. Если вы не знаете точно — какой именно модуль у вас главный — подумайте о том, что пользователи проекта будут устанавливать командой pip install , и о том, как, по вашему мнению, должна выглядеть команда import для вашего модуля.

Часто имя главного модуля совпадает с именем всего проекта. Но это — не некое жёсткое правило.

Аргументы в пользу директории src

Я видел множество проектов, устроенных по-другому.

Например, в проекте может отсутствовать директория src , а все модули будут просто лежать в его корневой директории:

non_recommended_project ├── /* │ ├── __init__.py │ └── many_files.py │ ├── .gitignore │ ├── tests/* │ └── many_tests.py │ ├── pyproject.toml │ ├── /* │ ├── __init__.py │ └── many_files.py │ └── README.md

Уныло смотрится проект, в структуре которого нет никакого порядка из-за того, что его папки и файлы просто расположены по алфавиту, в соответствии с правилами сортировки объектов в IDE.

Главная причина, по которой рекомендуется пользоваться папкой src , заключается в том, чтобы активный код проекта был бы собран в одной директории, а настройки, параметры CI/CD, метаданные проекта находились бы за пределами этой директории.

Единственный минус такого подхода заключается в том, что, без дополнительных усилий, не получится воспользоваться в своём коде командой вида import module_a . Для этого потребуется кое-что сделать. Ниже мы поговорим о том, как решить эту проблему.

Именование файлов

Правило №1: тут нет файлов

Во-первых — в Python нет таких сущностей, как «файлы», и я заметил, что это — главный источник путаницы для новичков.

Если вы находитесь в директории, содержащей файл __init__.py , то это — директория, включающая в себя модули, а не файлы.

Рассматривайте каждый модуль, как пространство имён.

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

Правило №2: если нужно — держите сущности в одном месте

Совершенно нормально, когда в одном модуле имеется несколько классов. Так и стоит организовывать код (но, конечно, только если классы связаны с модулем).

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

Часто встречается мнение, что это — пример неудачного приёма работы. Те, кто так считают, находятся под влиянием опыта, полученного после использования других языков программирования, которые принуждают к другим решениям (например — это Java и C#).

Правило №3: давайте модулям имена, представляющие собой существительные во множественном числе

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

Правда, у этого правила есть и исключение. Модули могут называться core , main.py или похожим образом, что указывает на то, что они представляют собой некую единичную сущность. Подбирая имена модулей, руководствуйтесь здравым смыслом, а если сомневаетесь — придерживайтесь вышеприведённого правила.

Реальный пример именования модулей

Вот мой проект — Google Maps Crawler, созданный в качестве примера.

Этот проект направлен на сбор данных из Google Maps с использованием Selenium и на их представление в виде, удобном для дальнейшей обработки (тут, если интересно, можно об этом почитать).

Вот текущее состояние дерева проекта (тут выделены исключения из правила №3):

gmaps_crawler ├── src │ └── gmaps_crawler │ ├── __init__.py │ ├── config.py (форма единственного числа) │ ├── drivers.py │ ├── entities.py │ ├── exceptions.py │ ├── facades.py │ ├── main.py (форма единственного числа) │ └── storages.py │ ├── .gitignore ├── pyproject.toml └── README.md

Весьма естественным кажется такой импорт классов и функций:

from gmaps_crawler.storages import get_storage from gmaps_crawler.entities import Place from gmaps_crawler.exceptions import CantEmitPlace

Можно понять, что в exceptions может иметься как один, так и множество классов исключений.

Именование модулей существительными множественного числа отличается следующими приятными особенностями:

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

Именование классов, функций и переменных

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

Имена функций и методов должны быть глаголами

Функции и методы представляют собой действия, или нечто, выполняющее действия.

Функция или метод — это не просто нечто «существующее». Это — нечто «действующее».

Действия чётко определяются глаголами.

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

def get_orders(): . def acknowledge_event(): . def get_delivery_information(): . def publish(): . 

А вот — несколько неудачных примеров:

def email_send(): . def api_call(): . def specific_stuff(): . 

Тут не очень ясно — возвращают ли функции объект, позволяющий выполнить обращение к API, или они сами выполняют какие-то действия, например — отправку письма.

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

email_send.title = "title" email_send.dispatch()

У рассмотренного правила есть и некоторые исключения:

• Создание функции main() , которую вызовут в главной точке входа приложения — это хороший повод нарушить это правило.
• Использование @property для того, чтобы обращаться с методом класса как с атрибутом, тоже допустимо.

Имена переменных и констант должны быть существительными

Имена переменных и констант всегда должны быть существительными и никогда — глаголами (это позволяет чётко отделить их от функций).

Вот примеры удачных имён:

plane = Plane() customer_id = 5 KEY_COMPARISON = "abc"

Вот — неудачные имена:

fly = Plane() get_customer_id = 5 COMPARE_KEY = "abc"

А если переменная или константа представляют собой список или коллекцию — им подойдёт имя, представленное существительным во множественном числе:

planes: list[Plane] = [Plane()] # Даже если содержит всего один элемент customer_ids: set[int] = KEY_MAP: dict[str, str] = # Имена словарей остаются существительными в единственном числе

Имена классов должны говорить сами за себя, но использование суффиксов — это нормально

Отдавайте предпочтение именам классов, понятным без дополнительных пояснений. При этом можно использовать и суффиксы, вроде Service , Strategy , Middleware , но — только в крайнем случае, когда они необходимы для чёткого описания цели существования класса.

Всегда давайте классам имена в единственном, а не во множественном числе. Имена во множественном числе напоминают имена коллекций элементов (например — если я вижу имя orders , то я полагаю, что это — список или итерируемый объект). Поэтому, выбирая имя класса, напоминайте себе, что после создания экземпляра класса в нашем распоряжении оказывается единственный объект.

Классы представляют собой некие сущности

Классы, представляющие нечто из бизнес-среды, должны называться в соответствии с названиями связанных с ними сущностей (и имена должны быть существительными!). Например — Order , Sale , Store , Restaurant и так далее.

Пример использования суффиксов

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

Кто-то может решить, что он может олицетворять некую сущность:

email = Email() # Предполагаемый пример использования email.title = "Title" email.body = create_body() email.send_to = "guilatrova.dev" send_email(email)

Такой класс следует назвать EmailSender или EmailService .

Соглашения по именованию сущностей

Следуйте этим соглашениям по именованию сущностей:

Тип

Общедоступный

Внутренний