Init project

Author: DIMFLIX

README.md

@@ -0,0 +1,50 @@
+<img src="./ru-docs/assets/main.png"/>
+
+# Содержание
+## Модуль 1: Основы типизации в Python
+* **[1.1 Введение в типизацию: зачем, когда и как?](./ru-docs/Введение_в_типизацию.md)**
+    * Динамическая и статическая типизация: плюсы и минусы
+    * Типизация в Python: история и эволюция
+    * Инструменты для статической типизации: mypy, PyCharm, другие
+* **[1.2 Базовые типы данных:](./ru-docs/Базовые_типы_данных.md)**
+    * int, float, str, bool: основы работы с типами
+    * None: отсутствие значения и его особенности
+    * Duck typing: неявная типизация в Python
+* **[1.3 Коллекции и их типизация:](./ru-docs/Коллекции_и_их_типизация.md)**
+    * list, tuple, dict, set: работа с коллекциями
+    * Типизация коллекций: List\[int\], Tuple\[str, int\], Dict\[str, float\]
+    *  Генераторы и итераторы: типизация и особенности
+* **[1.4 Функции и типизация:](./ru-docs/Функции_и_типизация.md)**
+    * Аннотация типов для аргументов и возвращаемого значения
+    * Перегрузка функций и типы
+    * Callable: работа с функциональными объектами
+* **[1.5 Классы и типизация:](./ru-docs/Классы_и_типизация.md)**
+    * Аннотация типов для атрибутов класса
+    * Методы класса и типизация
+    * Наследование и типизация: как типы взаимодействуют с наследованием
+ 
+## Модуль 2: Продвинутая типизация
+* **[2.1 Типизация с ипользованием TypeVar:](./ru-docs/Типизация_с_использованием_TypeVar.md)**
+    * Создание универсальных функций и классов
+    * Ограничение типов с помощью TypeVar
+    * Практические примеры использования TypeVar
+* **[2.2 Типы объединений (Union) и опциональные типы (Optional):](./ru-docs/Типы_объединений_и_опциональные_типы.md)**
+    * Работа с переменными, которые могут иметь разные типы
+    *  Использование Optional для обозначения  возможности отсутствия значения
+* **[2.3 Типы псевдонимов:](./ru-docs/Типы_псевдонимов.md)**
+    * Создание собственных имён для сложных типов
+    * Повышение читаемости и удобства работы с кодом
+* **[2.4 Типы Any, NoReturn:](./ru-docs/Типы_Any_и_NoReturn.md)**
+    * Any:  отключение проверки типов для конкретной переменной
+    * NoReturn: указание на то, что функция не возвращает значение
+* **[2.5 Типы протоколов:](./ru-docs/Типы_протоколов.md)**
+    * Определение интерфейсов для классов без явного наследования
+    *  Structural typing: проверка типов по структуре, а не по имени
+## Модуль 3:  Типизация в реальных проектах
+* **[3.1 Интеграция mypy в рабочий процесс:](./ru-docs/Интеграция_mypy.md)**
+    * Настройка mypy для проверки типов в проекте
+    *  Интерпретация ошибок mypy и их исправление
+* **[3.2 Stub файлы:](./ru-docs/Stub_файлы.md)**
+    *  Что это такое и зачем нужны?
+    *  Как типизировать сторонние модули
+    * Генерация stub файлов

ru-docs/Stub_файлы.md

@@ -0,0 +1,53 @@
+# Типизация и сторонние библиотеки
+Работа с типами в Python становится особенно важной, когда вы используете сторонние библиотеки. В этом разделе мы рассмотрим, как эффективно интегрировать типизацию в проекты, использующие внешние зависимости, а также как создавать стаб-файлы для библиотек, которые не предоставляют аннотации типов.
+
+## Что такое стаб-файлы?
+Стаб-файлы (или stub files) — это специальные файлы с расширением `.pyi`, которые используются в **Python** для предоставления информации о типах данных в коде, особенно когда речь идет о внешних библиотеках, которые не содержат аннотаций типов. Они позволяют разработчикам использовать преимущества статической типизации, не изменяя исходный код библиотек.
+
+## Зачем нужны?
+В Python, как и в других языках программирования, типизация помогает избежать ошибок, связанных с неправильным использованием данных. Например, если функция ожидает получить число, а вы передаете строку, это может привести к ошибкам во время выполнения программы. Стаб-файлы помогают:
+- **Указать ожидаемые типы аргументов и возвращаемых значений**: Это позволяет статическим анализаторам кода и IDE (например, PyCharm или VSCode) проверять ваш код на наличие ошибок до его выполнения.
+- **Упростить работу с нетипизированными библиотеками**: Если вы используете стороннюю библиотеку, которая не поддерживает аннотации типов, вы можете создать стаб-файл для этой библиотеки и указать в нем необходимые типы.
+
+## Как работают?
+Стаб-файлы содержат описание функций и классов, которые предоставляет библиотека, но без их реализации. Вместо этого они используют многоточие (`...`), чтобы указать, что реализация находится в другом месте. Например:
+
+```python
+# my_library.pyi 
+def my_function(param: int) -> str: ...
+```
+
+В этом примере мы указываем, что функция `my_function` принимает один аргумент типа `int` и возвращает значение типа `str`.
+
+## Как создать стаб-файл?
+1. **Определите функции и классы**: Изучите исходный код модуля, чтобы понять, какие функции и классы он предоставляет.
+2. **Создайте файл с расширением `.pyi`**: Например, если ваш модуль называется `my_library`, создайте файл `my_library.pyi`.
+3. **Опишите типы**: Внутри файла укажите типы для всех функций и классов.
+
+Пример стаб-файла для простой библиотеки:
+```python
+# my_library.pyi 
+def add(a: int, b: int) -> int: ... 
+
+def greet(name: str) -> str: ...
+```
+
+Если у вас есть сложная структура, организуйте стаб-файлы в подкаталоги с использованием `__init__.pyi` для пакетов.
+
+## Где разместить стаб-файлы?
+Стаб-файлы могут быть размещены в разных местах:
+- **В той же директории, что и библиотека**: Это самый простой способ.
+- **В отдельной папке**: Вы можете создать папку для всех ваших стаб-файлов и добавить её в переменную окружения `MYPYPATH`, чтобы Python мог их найти.
+
+Пример добавления пути к стаб-файлам:
+```bash
+export MYPYPATH=~/path/to/stubs
+```
+
+## Генерация стаб-файлов
+- **Использование `stubgen`**: Вы можете использовать инструмент `stubgen`, который входит в пакет `mypy`, чтобы автоматически генерировать стаб-файлы для сторонних библиотек:
+```bash
+    pip install -U mypy stubgen -m library_name
+``` 
+- Сгенерированные файлы будут сохранены в директории `out/`. Однако имейте в виду, что автоматически сгенерированные файлы могут не содержать полной информации о типах и документации.
+- **Использование сторонних проектов**: Существуют проекты, которые предоставляют готовые стаб-файлы для популярных библиотек. Вы можете скачать их и разместить в директории с установленным модулем.

ru-docs/assets/main.png

@@ -0,0 +1,42 @@
+## int, float, str, bool: основы работы с типами
+***
+Python предлагает следующие базовые типы данных:
+* `int`: Целые числа (например: 10, -5, 0). 
+* `float`: Числа с плавающей точкой (например: 3.14, -2.5, 0.0).
+* `str`: Строки (например: "hello", "world", "123").
+* `bool`: Логический тип, принимающий значения `True` или `False`.
+
+Примеры аннотации типов для базовых типов:
+```python
+age: int = 30
+price: float = 19.99
+name: str = "Alice"
+is_active: bool = True
+```
+
+## None: отсутствие значения и его особенности
+***
+`None` —  специальный тип, который обозначает отсутствие значения. 
+```python
+result: None = None
+```
+
+Важно понимать, что `None` —  не то же самое, что 0, пустая строка или `False`.  Это отдельный тип, который указывает на отсутствие какого-либо значения.
+
+## Duck typing: неявная типизация в Python
+***
+Python также использует концепцию duck typing.  Это неявная типизация, основанная на том, что "если что-то ходит как утка и крякает как утка, то это, вероятно, утка".  
+
+Другими словами, Python не всегда строго проверяет типы объектов, а смотрит на то, какие методы и атрибуты у них есть.  Если объект поддерживает необходимые методы и атрибуты, то он считается подходящим, независимо от его конкретного типа.
+
+```python
+def print_length(obj):
+  print(len(obj))
+
+print_length("hello")  # Вывод: 5
+print_length([1, 2, 3])  # Вывод: 3
+```
+
+В этом примере функция `print_length` принимает любой объект, у которого есть метод `len`.  Она не проверяет конкретный тип объекта, что является примером duck typing.
+
+**Duck typing** делает Python гибким, но может усложнить отладку кода, так как ошибки типов могут проявиться только во время выполнения.  Использование аннотаций типов и статических анализаторов помогает  снизить риски, связанные с duck typing, и повысить надежность кода.

ru-docs/Базовые_типы_данных.md

@@ -0,0 +1,37 @@
+## Введение в типизацию: зачем, когда и как?
+***
+В этом разделе мы рассмотрим, почему типизация важна в Python, когда ее стоит применять и как она реализована в языке. 
+## Динамическая и статическая типизация: плюсы и минусы
+***
+Python — язык с динамической типизацией.  Это значит, что тип переменной определяется во время выполнения программы, а не во время написания кода. Такой подход обладает рядом **преимуществ**:
+* Гибкость:  Вы можете легко менять типы переменных на лету, не беспокоясь о строгих ограничениях компилятора. 
+* Быстрое прототипирование:  Динамическая типизация позволяет быстро создавать прототипы, фокусируясь на логике программы, а не на формальностях типов. 
+* Меньше кода: Вам не нужно объявлять типы переменных, что делает код более лаконичным.
+
+Однако у динамической типизации есть и **недостатки**:
+* Ошибки типов во время выполнения:  Ошибки, связанные с неверным использованием типов, могут проявиться только во время работы программы, что усложняет отладку.
+* Снижение читаемости кода:  Без явного указания типов сложнее понять, какие данные хранятся в переменных и как они используются.
+* Проблемы с масштабированием:  В больших проектах с множеством разработчиков отсутствие строгой типизации может привести к путанице и ошибкам, которые сложно отследить.
+
+Статическая типизация решает эти проблемы. Она требует, чтобы типы переменных были объявлены заранее, во время написания кода. Это позволяет:
+* Обнаруживать ошибки типов на этапе компиляции:  Компилятор или статический анализатор кода проверяет типы, предотвращая ошибки во время выполнения программы. 
+* Повысить читаемость кода:  Явное указание типов делает код более понятным и легким для восприятия.
+* Упростить рефакторинг:  Статическая типизация помогает легче и безопаснее изменять код, так как компилятор или анализатор кода может обнаружить несоответствия типов.
+## Типизация в Python: история и эволюция
+***
+Python изначально был языком с динамической типизацией.  Однако с ростом популярности языка и увеличением размеров проектов разработчики начали испытывать необходимость в статической типизации. 
+
+В **Python 3.5** были введены аннотации типов: возможность добавлять информацию о типах к переменным, аргументам функций и возвращаемым значениям.  
+
+>[!warning] Важно!
+>Они никак не влияют на работу программы, но могут использоваться статическими анализаторами кода, например **mypy**.
+
+В Python 3.6 появился новый синтаксис для переменных с объявленными типами.  Это позволяет объявлять тип переменной, используя двоеточие и имя типа:  `age: int = 25`.
+## Инструменты для статической типизации: mypy, PyCharm, другие
+***
+Для работы со статической типизацией в Python существует ряд инструментов:
+* **mypy**:  Самый популярный статический анализатор кода для Python. Он проверяет типы в коде и сообщает об ошибках. 
+* **PyCharm**:  Популярная IDE для Python, которая включает встроенную поддержку статической типизации и интеграцию с mypy. 
+* Другие инструменты:  Существуют и другие инструменты для статической типизации, например Pyre, Pytype, которые предлагают свои особенности и возможности.
+
+В этом курсе мы будем использовать mypy в качестве основного инструмента для статической типизации, так как он является наиболее распространенным и хорошо поддерживаемым инструментом.