Python - Руководство по аннотациям функций для начинающих

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

Что такое аннотации функций?

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

Начнем с простого примера:

def приветствие(имя: str) -> str:
return f"Привет, {имя}!"

В этом примере, : str после имя — это аннотация, указывающая на то, что имя должно быть строкой. А -> str в конце указывает, что функция вернет строку.

Почему использовать аннотации функций?

1. Они делают ваш код более читаемым.
2. Помогают другим разработчикам (и вам в будущем!) лучше понять ваш код.
3. Могут использоваться инструментами для проверки типов, чтобы перехватить потенциальные ошибки.

Теперь давайте поглубже погружемся в различные типы аннотаций!

Аннотации функций с параметрами

Мы можем аннотировать параметры функции, чтобы указать, какого типа данные мы ожидаем. Вот пример:

def вычислить_площадь(длина: float, ширина: float) -> float:
return длина * ширина

В этой функции мы говорим, что как длина, так и ширина должны быть вещественными числами (дécимаUX числами), и функция вернет вещественное число.

Попробуем использовать ее:

площадь = вычислить_площадь(5.5, 3.2)
print(f"Площадь равна: {площадь}")

Вывод:

Площадь равна: 17.6

Помните, эти аннотации не обязывают типы — вы все равно можете вызвать вычислить_площадь("привет", "мир"), но это не будет иметь смысла!

Аннотации функций с типом возвращаемого значения

Мы уже видели аннотацию -> float для типа возвращаемого значения, но давайте рассмотрим более сложный пример:

def get_user_info(user_id: int) -> dict:
# Представьте, что эта функция извлекает данные пользователя из базы данных
return {
"id": user_id,
"name": "Алиса",
"age": 30,
"email": "[email protected]"
}

пользователь = get_user_info(12345)
print(f"Имя пользователя: {пользователь['name']}")

Вывод:

Имя пользователя: Алиса

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

Аннотации функций с выражениями

Аннотации не обязаны быть простыми типами — они могут быть и более сложными выражениями. Вот пример:

from typing import List, Union

def process_items(items: List[Union[int, str]]) -> List[str]:
return [str(item).upper() for item in items]

результат = process_items([1, "привет", 42, "мир"])
print(результат)

Вывод:

['1', 'ПРИВЕТ', '42', 'МИР']

В этом примере List[Union[int, str]] означает, что функция ожидает список, в котором каждый элемент может быть либо целым числом, либо строкой.

Аннотации функций с параметрами по умолчанию

Мы можем комбинировать аннотации с параметрами по умолчанию. Вот как:

def приветствие_пользователя(имя: str = "Гость") -> str:
return f"Добро пожаловать, {имя}!"

print(приветствие_пользователя())
print(приветствие_пользователя("Алиса"))

Вывод:

Добро пожаловать, Гость!
Добро пожаловать, Алиса!

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

Комбинирование всех методов

Теперь давайте рассмотрим более сложный пример, который объединяет различные техники аннотации:

from typing import List, Dict, Union

def анализ_продаж(data: List[Dict[str, Union[str, float]]]) -> Dict[str, float]:
total_sales = 0.0
items_sold = 0

for transaction in data:
total_sales += transaction['amount']
items_sold += 1

return {
"total_sales": total_sales,
"average_sale": total_sales / items_sold if items_sold > 0 else 0
}

sales_data = [
{"item": "Widget A", "amount": 10.99},
{"item": "Widget B", "amount": 5.99},
{"item": "Widget C", "amount": 15.99}
]

результат = анализ_продаж(sales_data)
print(f"Общая продажа: ${результат['total_sales']:.2f}")
print(f"Средняя продажа: ${результат['average_sale']:.2f}")

Вывод:

Общая продажа: $32.97
Средняя продажа: $10.99

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

Резюме методов аннотации функций

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

Метод	Пример	Описание
Аннотация параметра	def func(x: int):	Предлагает тип для параметра
Аннотация типа возвращаемого значения	def func() -> str:	Предлагает тип возвращаемого значения функции
Значение по умолчанию с аннотацией	def func(x: int = 0):	Комбинирует предложение типа с значением по умолчанию
Сложная аннотация типа	def func(x: List[int]):	Использует типы из модуля typing для более специфических подсказок типа
Несколько типов (Union)	def func(x: Union[int, str]):	Предлагает, что параметр может быть одним из нескольких типов

Помните, эти аннотации — это подсказки, а не строгие правила. Python не остановит вас, если вы будете использовать разные типы, но инструменты, такие как mypy, могут использовать эти аннотации, чтобы перехватить потенциальные ошибки перед выполнением вашего кода.

Итак, мои дорогие студенты! Мы путешествовали по земле Python Function Annotations. Я надеюсь, это руководство осветило этот концепт для вас. Помните, лучший способ учиться — это делать, так что не стесняйтесь экспериментировать с этими аннотациями в своем коде. Счастливого кодирования, и пусть ваши функции всегда будут хорошо аннотированы!

Credits: Image by storyset