🔥 Как правильно писать документацию для кода на Python?

Есть несколько основных способов задокументировать свой код и сделать его более понятным:

→ Обычные комментарии
→ Докстринги
→ Полноценная документация

Давайте рассмотрим каждый способ в отдельности.

✅ ОБЫЧНЫЕ КОММЕНТАРИИ

Обычные комментарии - части кода, которые начинаются в Python с решетки # и содержат небольшие пояснительные сообщения.

Например:

 # проверяем тип полученного ответа
 if isinstance(response): …

Такие комментарии нужны для того, чтобы ваш код было проще читать и понимать. Полноценной документацией они не являются.

✅ ДОКСТРИНГИ

Докстринг (строка документации) - это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками """<denoscription>""" в начале модуля, класса, метода или функции, который описывает, что делает функция.

Только в случае, если это первый оператор в функции, он может быть распознан Python и доступен как атрибуты с помощью метода doc или функции help().

Пример смотрите в карточках 👆🏻


❗️Докстринги могут быть как однострочными, так и многострочными.

Однострочные докстринги обычно дают саммари - кратко описывают: что функция делает и что возвращает. Для шаблона используйте фразу «делает то, возвращает это».

В многострочных докстрингах принято описывать:

→ краткое описание того, что функция делает
→ аргументы - их типы и «физический» смысл
→ информация о возвращаемых значениях
→ какие ошибки возбуждаются
→ заметки
→ что рекомендуется почитать
→ предупреждения

Примеры однострочного и многострочного докстринга ищите в карточках!


✅ SPHINX

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

Этот стиль является стандартом в Python.

‼️Основные ключевые слова Sphinx:

→ param и type: значение параметра и тип его переменной
→ return и rtype: возвращаемое значение и его тип
→ :raises: описывает любые ошибки, которые возникают в коде
→ .. seealso::: информация для дальнейшего чтения
→ .. notes::: добавление заметки
→ .. warning::: добавление предупреждения

Общая структура документации Sphinx подробно расписана, как вы уже поняли, в карточках 😉


Пользоваться документацией Sphinx в повседневной жизни очень просто.

✅ В IDE PyCharm от JetBrains это идет по умолчанию - достаточно начать писать докстринг и нажать Enter.

✅ Чтобы использовать Sphinx в VS Code, сделайте так:

1. Установите расширение Python Docstring Generator

2. Как только вы начнете набирать докстринг, IDE предложит вам Generate Docstring. По умолчанию генерируется Sphinx. Поменять тип можно в настройках расширения

🔥 Задача с собеседования по Python [СБЕР]

Разместили на платформе новую задачу с собеседования по Python на должность Junior Data Engineer & Data Science.

Подробнее здесь 👉🏻 https://vk.cc/caVejr

​​Что такое CodeCoins? 💰

CodeCoins - внутренняя валюта на платформе IT Resume. За нее вы можете покупать некоторые задачи, тесты, подсказки и решения!

Подробнее о том, как получить ее бесплатно, тут 👉🏻 https://vk.cc/caSkOK

🔥 Разбор тестового задания для аналитика с [Avito Weekend Offer]

Сегодня вместе с онлайн-университетом SF Education подготовили разбор задачи по Python с [Avito Weekend Offer].

Кстати, попробуйте сначала решить эту задачу самостоятельно 👉🏻 https://vk.cc/cb8QbP 😉

# Задача

Вам дано 2 набора чисел arr1 и arr2 в виде списка Python. Необходимо вернуть список, состоящий из элементов пересечения. Дубликаты необходимо удалить.

Важно: Если пересечение пустое, то возвращаем пустой список.

Пример:

 arr1 = [1, 2, 3], arr2 = [1, 1, 5]
 Ответ: [1]

Пример:

 arr1 = [1, 2, 3], arr2 = [6, 7, 5]
 Ответ: []

Пример:

 arr1 = [1, 2, 3], arr2 = [1, 2, 15, 3, 3]
 Ответ: [1, 2, 3]

# Попытка 1

Самый простой подход - пробежаться по элементам каждого массива и проверить вхождение во второй массив. Если элемент есть в обоих массивах - добавляем к результату.

 
 res = []
 for el in arr1:
     if el in arr2 and el not in res:
         res.append(el)
 for el in arr2:
     if el in arr1 and el not in res:
         res.append(el)

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

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

Чтобы убрать дубликаты, мы можем использовать множества - set. Они хранят уникальные значения в неупорядоченном виде.

 st1 = set(arr1)

# Попытка 2

У множеств в Python есть встроенный метод intersection - он как раз находит пересечение двух множеств.

Таким образом, решение задачи сводится к следующему:

1. Переводим оба списка в множества
2. С помощью метода intersection находим пересечение
3. На выходе intersection получается снова множество, поэтому переводим его в список с помощью функции list

Итоговый код:

 def PureIntersection(arr1, arr2):
         return list(set(arr1).intersection(set(arr2)))