📦 Репозиторий занятия 44

"""
Docstring - простой и удобный способ добавить детальное описание в функцию.
(что-то вроде инструкции пользователя.

Извлечь можно с помощью функции help().
"""


def my_function():
    """
    This is my function: very simple and very useful and very good way to add a description.
    Return nothing.

    :return: None
    """
    print("Hello World")


help(my_function)
help()

def f(x, y):
    """
    Adds two numbers and returns the result.

    This function takes two numerical inputs and adds them together. It
    is expected that both parameters are valid numbers that can be added.
    The result of the addition will be returned.

    :param x: The first number to be added.
    :type x: int or float
    :param y: The second number to be added.
    :type y: int or float
    :return: The sum of the two numbers.
    :rtype: int or float
    """

## Что такое аннотации в Python?

**Аннотации** — это специальный синтаксис в Python, позволяющий указывать типы данных.

Они не влияют напрямую на выполнение программы, а служат **подсказками** для разработчиков,  
IDE и систем статического анализа (например, `mypy`, `pyright`, `pylance`).

Пример:

```python
def greeting(name: str, age: int) -> str:
    return f"Hi, {name}! Your age is {age}."
```

Здесь:

* `name: str` — аннотации типов аргументов `name` и `age`.
* `-> str` — аннотация возвращаемого значения.

---

## Зачем нужны аннотации?

Аннотации не влияют на выполнение кода. Поэтому ошибку в аннотации Python "не заметит".  
(Если, конечно, это не синтаксическая ошибка).

1. Улучшают читаемость кода

2. Помогают IDE в проверке и раннем предупреждении ошибок

3. Само-документирование кода
   * аннотации выполняют роль документации, не требуя отдельного описания типов в docstring.

4. **Интеграция с автодополнением и статическим анализом**
   IDE (PyCharm, VS Code) и системы автогенерации API (например, FastAPI, Pydantic) используют аннотации для точных подсказок и валидации.

---

## Таблица сравнения аннотаций 


| **Тип данных**              | **Аннотация до 3.9 (`typing`)** | **Аннотация после 3.9 (встроенная)** |
|-----------------------------| ------------------------------- |--------------------------------------|
| Список                      | `List[int]`                     | `list[int]`                          |
| Словарь                     | `Dict[str, int]`                | `dict[str, int]`                     |
| Тюпл                        | `Tuple[int, str]`               | `tuple[int, str]`                    |
| Множество                   | `Set[str]`                      | `set[str]`                           |
| Неизменяемое множество      | `FrozenSet[int]`                | `frozenset[int]`                     |
| Итератор                    | `Iterator[int]`                 | `Iterator[int]`                      |
| Генератор                   | `Generator[int, None, None]`    | `Generator[int, None, None]`         |
| Опциональное значение       | `Optional[int]`                 | `int \| None`                        |
| Объединение типов           | `Union[int, str]`               | `int \| str`                         |
| Любой тип                   | `Any`                           | `Any`                                |
| Вызываемый объект (функция) | `Callable[[int], str]`          | `Callable[[int], str]`               |
| None                        | `None`                          | `None`                               |


## УНИВЕРСАЛЬНОЕ ПРАВИЛО:

Всё, что при аннотации даёт ошибку, следует импортировать из модуля `typing`
…

## 1. Базовые типы

```python
name: str
age: int
price: float
active: bool
data: bytes
```

---

## 2. Коллекции

```python
numbers: list[int]
names: set[str]
user_ids: frozenset[int]
options: dict[str, int]
pairs: tuple[str, int]
```

> 🔹 До Python 3.9 приходилось писать `List[int]`, `Dict[str, int]`, `Tuple[str, int]` через модуль `typing`.

---

## 3. Вложенные структуры

```python
matrix: list[list[int]]
config: dict[str, list[tuple[str, int]]]
```

ВАЖНО: Вложенные структуры усложняют читаемость кода.  
Поэтому указывать вложенный тип желательно, но совсем не обязательно

---

## 4. Опциональные и объединённые типы (Python 3.10+)

### Старый синтаксис (до 3.10):

```python
from typing import Optional, Union

id: Optional[int]  # то же самое, что Union[int, None]
value: Union[int, str]
```

### Новый синтаксис (3.10+):

```python
id: int | None
value: int | str
```

"""
Изменение изменяемых типов данных внутри функции изменит их и снаружи.
Поэтому перед изменением нужно делать их копию.
Глубокую или поверхностную - зависит от типа данных.
"""


def func(lst: list[int]) -> list:
    lst.append(4)
    return lst


lst = [1, 2, 3]

result = func(lst)
print(result)           # [1, 2, 3, 4]
print(lst)              # [1, 2, 3, 4]
print(result == lst)    # True


"""
Это плохой вариант.

===============================================================================

Поэтому функцию func придётся доработать:
"""

def modified_func(lst: list[int]) -> list:
    new_lst = lst[:]
    new_lst.append(4)
    return new_lst


lst = [1, 2, 3]

result = modified_func(lst)
print(result)           # [1, 2, 3, 4]
print(lst)              # [1, 2, 3]
print(result == lst)    # False