ВУЗ: Не указан
Категория: Не указан
Дисциплина: Не указана
Добавлен: 03.12.2023
Просмотров: 385
Скачиваний: 1
ВНИМАНИЕ! Если данный файл нарушает Ваши авторские права, то обязательно сообщите нам.
СОДЕРЖАНИЕ
232
Глава 11.Комментарии, doc-строки и аннотации типов
Чтобы объявить типы данных значений, хранящихся в списке, используйте анно- тацию типа
List модуля typing
. Обратите внимание:
List начинается с буквы
L
в верхнем регистре, что отличает ее от типа данных list
:
from typing import List, Union catNames: List[str] = ['Zophie', 'Simon', 'Pooka', 'Theodore']
❶
numbers: List[Union[int, float]] = [42, 3.14, 99.9, 86]
❷
В этом примере переменная catNames содержит список строк, поэтому после импортирования
List из модуля typing мы задаем аннотацию типа
List[str]
❶
Система проверки типов перехватывает все вызовы методов append()
или insert()
или любого другого кода, который помещает в список значения, не являющиеся строками. Если список должен содержать данные разных типов, используйте
Union в аннотации типов. Например, список numbers может содержать целые числа и чис- ла с плавающей точкой, поэтому для него задается аннотация
List[Union[int,
float]]
❷
Модуль typing имеет отдельный псевдоним типа (type alias) для каждой разновид- ности контейнеров. Ниже перечислены псевдонимы для всех распространенных контейнерных типов Python:
List для типа данных list
;
Tuple для типа данных tuple
;
Dict для типа данных словаря (
dict
);
Set для типа данных set
;
FrozenSet для типа данных frozenset
;
Sequence для list
, tuple и любых других типов данных последователь- ностей;
Mapping для словарей (
dict
), set
, frozenset и любых других типов данных отображений;
ByteString для типов данных bytes
, bytearray и memoryview
Полный перечень этих типов доступен по адресу https://docs.python.org/3/library/
typing.html#classes-functions-and-decorators.
Обратное портирование аннотаций типов
Обратным портированием (backporting) называется процесс выделения некоторой функциональности из новой версии программного продукта и портирование ее
Аннотации типов
233
(то есть адаптация и добавление) в более раннюю версию. Аннотации типов Python появились только в версии 3.5. Но в коде Python, который должен выполняться в версиях интерпретатора ниже 3.5, все равно можно использовать аннотации типов, размещая информацию о типах в комментариях. Для переменных используется встроенный комментарий после команды присваивания. Для функций и методов аннотации типов записываются в строке после команды def
. Комментарий начи- нается с type:
, а затем указывается тип данных. Пример кода с аннотациями типов в комментариях:
from typing import List
❶
spam = 42 # type: int
❷
def sayHello():
# type: () -> None
❸
"""Doc-строка следует за комментарием с аннотацией типа."""
print('Hello!')
def addTwoNumbers(listOfNumbers, doubleTheSum):
# type: (List[float], bool) -> float
❹
total = listOfNumbers[0] + listOfNumbers[1]
if doubleTheSum:
total *= 2
return total
Обратите внимание: даже если вы используете стиль аннотаций типов в ком- ментариях, все равно необходимо импортировать модуль typing
❶
, а также все псевдонимы типов, которые вы будете использовать в комментариях. В версиях до 3.5 стандартная библиотека не включала модуль typing
, его следует установить отдельно следующей командой:
python -m pip install --user typing
В macOS и Linux используйте команду python3
вместо python
Чтобы связать переменную spam с целым типом, мы добавляем
#
type:
int в ком- ментарий в конце строки
❷
. Для функций комментарий должен включать круглые скобки со списком аннотаций типов, разделенных запятыми, порядок которых соответствует порядку параметров. Функции без параметров должны иметь пу- стой набор круглых скобок
❸
. Если параметров несколько, разделите их запятыми в круглых скобках
❹
Аннотации типов в комментариях читаются хуже, чем просто аннотации типов, поэтому они используются только для кода, который может выполняться версиями
Python до 3.5.
234
Глава 11.Комментарии, doc-строки и аннотации типов
Итоги
Программисты часто забывают о документировании своего кода. Но потратив не- много времени на добавление комментариев, doc-строк и аннотаций типов в ваш код, вы избежите временных затрат в будущем. Хорошо документированный код также проще сопровождать.
Соблазнительно принять точку зрения, что комментарии и документация не важны или даже приносят вред при написании программ. (Такая позиция также избавляет программистов от работы по написанию документации — очень удобно.) Не обма- нывайте себя: хорошо написанная документация всегда экономит гораздо больше времени и усилий, чем требуется на ее создание. Программистам намного чаще приходится иметь дело со страницами невразумительного кода без комментариев, чем с избытком полезной информации.
Хорошие комментарии предоставляют полезную, краткую и точную информацию тем, кому придется читать код позднее и разбираться в том, что код делает. Коммен- тарии должны объяснять намерения программиста и обобщать смысл небольших блоков кода, а не пересказывать очевидный смысл одной строки кода. Иногда в ком- ментариях содержится подробное описание информации, полученной и усвоенной программистом во время написания кода. В будущем эти ценные сведения избавят тех, кто занимается сопровождением кода, от горькой участи заново добывать ее, тратя время и силы.
Doc-строки — разновидность комментариев, специфическая для Python, — пред- ставляют собой многострочные тексты, следующие непосредственно за командами class или def или расположенные в начале модуля. Средства документирования
(например, встроенная функция Python help()
) могут извлекать doc-строки из кода, чтобы предоставить конкретные сведения о предназначении класса, функции или модуля.
Аннотации типов, появившиеся в Python 3.5, дают Python механизм постепенной типизации. Постепенная типизация позволяет программисту пользоваться пре- имуществами статической типизации по определению типов без потери гибкости динамической типизации. Интерпретатор Python игнорирует аннотации типов, потому что в Python отсутствует проверка типов на стадии выполнения. Тем не менее средства статической разработки типов используют аннотации типов для анализа исходного кода до его выполнения. Средства проверки типов — такие как
Mypy — следят за тем, чтобы переменным, передаваемым функциям, не присваива- лись недопустимые значения. Это экономит время и усилия за счет предотвращения самых разнообразных ошибок.
1 ... 20 21 22 23 24 25 26 27 ... 40
12
Git и организация
программных проектов
Системы контроля версий представляют собой программ- ные средства, которые регистрируют все изменения в ис- ходном коде и позволяют легко восстановить старые версии.
Рассматривайте их как сильно усовершенствованную функ- цию отмены (undo). Например, если вы заменяете функцию, а потом решаете, что старая версия нравится вам больше, вы можете восстановить исходный фрагмент кода. Или при обнаружении новой ошибки вы можете вернуться к более ранним версиям, чтобы определить, когда она впервые появилась и какие изменения ее вызвали.
Система контроля версий управляет файлами при внесении в них изменений.
Пользоваться ею удобнее, чем, скажем, работать с копией папки myProject
. Первой копии вы присвоите имя myProject-copy
. Затем, если вы продолжите вносить из- менения, вам потребуется создать новую копию с именем myProject-copy2
, потом myProject-copy3
, myProject-copy3b
, myProject-copyAsOfWednesday и т. д. Возможно, копирование папок — простой метод, но он не масштабируется. Умение пользовать- ся системой контроля версий сэкономит ваше время и избавит от многих хлопот в долгосрочной перспективе.
Git, Mercurial и Subversion — популярные приложения контроля версий, хотя система Git остается самой популярной. В этой главе вы узнаете, как подготовить файлы для программного проекта и как использовать Git для отслеживания в них изменений.
236
Глава 12.Git и организация программных проектов
Коммиты и репозитории
Git позволяет сохранить состояние файлов проекта при внесении в них изменений.
Такие сохранения называются снимками (snapshots) или коммитами (commits).
Благодаря этому вы сможете, если потребуется, вернуться к любой предшеству- ющей версии.
Системы контроля версий также позволяют команде разработчиков синхронизиро- вать свою работу при внесении изменений в исходный код проекта. Когда каждый программист закрепляет свои изменения, другие могут извлекать эти обновления на своих компьютерах. Система контроля версий следит за тем, какие изменения были внесены, кто и когда их сделал, а также сохраняет комментарии разработчиков, описывающие эти изменения.
Система контроля версий управляет исходным кодом проекта, который хранится в специальной папке — репозитории (repo). Как правило, для каждого проекта, над которым вы работаете, следует создать отдельный репозиторий Git. Предпо- ложим, вы работаете в основном самостоятельно над своей частью программы и вам не нужны расширенные возможности Git (такие как ветвление и слияние), упрощающие работу с остальными участниками. Но даже если вы работаете в одиночку, самый маленький проект все равно выиграет от применения системы контроля версий.
Создание новых проектов Python
с использованием Cookiecutter
В терминологии Git папка, содержащая весь исходный код, документацию, тесты и другие файлы, относящиеся к проекту, называется рабочим каталогом или рабо-
чим деревом, а в более общей терминологии — папкой проекта. Файлы в рабочем каталоге в совокупности называются рабочей копией. Прежде чем создавать репо- зиторий Git, следует создать файлы для проекта Python.
У каждого программиста есть свой способ выполнения этой операции. Тем не менее для проектов Python действуют определенные соглашения по поводу имен папок и иерархий. Более простая программа может содержать один файл
.py
Но когда проекты усложнятся, в них будут включаться дополнительные файлы
.py
, файлы данных, документация, модульные тесты и т. д. Как правило, корневая папка проекта содержит папку src для файлов с исходным кодом
.py
, папку tests для модульных тестов и папку docs для документации (например, сгенерирован- ной системой документирования Sphinx). Другие файлы содержат информацию о проекте и конфигурации системы:
README.md для общей информации,
.coveragerc для конфигурации покрытия кода,
LICENSE.txt для текста программной лицензии
Создание новых проектов Python с использованием Cookiecutter
237
проекта и т. д. Описание этих средств и файлов выходит за рамки книги, но они заслуживают вашего внимания. С появлением практического опыта программиро- вания необходимость заново создавать одни и те же базовые файлы для всех новых проектов надоедает и утомляет. Чтобы ускорить выполнение рутинных операций, можно использовать модуль Python cookiecutter для автоматического создания этих файлов и папок. Полная документация по модулю и программе командной строки Cookiecutter доступна на https://cookiecutter.readthedocs.io/.
Чтобы установить Cookiecutter, выполните команду pip install
--user cookiecutter
(в системе Windows) или pip3
install
--user cookiecutter
(в macOS и Linux).
В установку включаются программа командной строки Cookiecutter и модуль
Python cookiecutter
. В процессе установки вы можете получить предупреждение о том, что программа командной строки устанавливается в папку, не входящую в переменную окружения
PATH
:
Installing collected packages: cookiecutter
WARNING: The script cookiecutter.exe is installed in 'C:\Users\Al\AppData\
Roaming\Python\Python38\Scripts' which is not on PATH.
Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
Возможно, вам стоит включить папку (
C:\Users\Al\AppData\Roaming\Python\Py- thon38\Scripts в данном случае) в переменную среды
PATH
; инструкции приведены в разделе «Переменные среды и PATH», с. 60. В противном случае вам придется запускать Cookiecutter как модуль Python командой python
-m cookiecutter
(в Win dows) или python3
–m cookiecutter
(в macOS или Linux) вместо простой команды cookiecutter
В этой главе мы создадим репозиторий для модуля wizcoin
, предназначенного для работы с различными видами волшебной валюты. Модуль cookiecutter ис- пользует шаблоны для создания начальных файлов для различных видов проек- тов. Часто шаблон представляет собой простую ссылку на GitHub.com. Например, в папке
C:\Users\Al можно ввести приведенную ниже команду из окна терминала для создания папки
C:\Users\Al\wizcoin с заготовками файлов для базового проекта
Python. Модуль cookiecutter загружает шаблон с GitHub и задает серию вопросов о создаваемом проекте:
C:\Users\Al>cookiecutter gh:asweigart/cookiecutter-basicpythonproject
project_name [Basic Python Project]: WizCoin
module_name [basicpythonproject]: wizcoin
author_name [Susie Softwaredeveloper]: Al Sweigart
author_email [susie@example.com]: al@inventwithpython.com
github_username [susieexample]: asweigart
project_version [0.1.0]:
project_short_description [A basic Python project.]: A Python module to
represent the galleon, sickle, and knut coins of wizard currency.
238
Глава 12.Git и организация программных проектов
Если вы получите ошибку, попробуйте выполнить команду python
-m cookiecutter вместо cookiecutter
. Команда загружает созданный мной шаблон на https://
github.com/asweigart/cookiecutter-basicpythonproject. В разделе https://github.com/
cookiecutter/cookiecutter вы найдете шаблоны для многих языков программирования.
Так как шаблоны Cookiecutter часто размещаются на GitHub, вы также можете ввести gh:
как сокращение для https://github.com/ в аргументе командной строки.
Когда Cookiecutter задает свои вопросы, следует либо ввести ответ, либо просто нажать ENTER, чтобы использовать ответ по умолчанию, приведенный в квадрат- ных скобках. Например, запрос project_name
[Basic
Python
Project]
: предлагает ввести имя проекта. Если не указать ничего, Cookiecutter использует имя проекта
Basic Python Project. Значения по умолчанию также подсказывают, какой ответ предполагается. В подсказке project_name
[Basic
Python
Project]:
в имени про- екта используются символы верхнего регистра, тогда как из подсказки module_name
[basicpythonproject]:
видно, что имя модуля записывается в нижнем регистре и не содержит пробелов. Мы не ввели ответ на запрос project_version
[0.1.0]:
, поэтому по умолчанию используется ответ
0.1.0
После ответов на вопросы Cookiecutter создает папку wizcoin в текущем рабочем каталоге с базовыми файлами, необходимыми для проекта Python (рис. 12.1).
Рис. 12.1. Файлы в папке wizcoin, созданной Cookiecutter
Если вы не знаете, для чего нужны те или иные файлы, не огорчайтесь. Хотя полное описание назначения каждого файла выходит за рамки книги, на странице https://
github.com/asweigart/cookiecutter-basicpythonproject присутствуют ссылки и нужная информация. Итак, базовые файлы созданы, и мы переходим к отслеживанию из- менений в них в системе Git.