Docstring

Содержание
Введение
Пример написания
Тестирование с doctest
help: чтение
Похожие статьи

Введение

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

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

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

По-видимому, он был впервые представлен в оригинальной реализации Emacs TECO.

PEP 256 , PEP 257 , PEP 258

Языки, поддерживающие docstrings, включают Python (см. PEP 257 ) , Lisp, Elixir, Clojure, Gherkin, Julia и Haskell.

Примеры

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

Например, PyCharm предлагает использовать термин param то есть параметры и я считаю, что это правильно.

def sum(first: float, second: float) -> float: """ Adds two float values :param first: float first addend :param second: float second addend :return: float first + second """ return first + second

Некоторые авторы, в том числе в популярных библиотеках Python вроде datetime , или например, на Pluralsight используют термин Args или Arguments то есть аргументы я считаю это некорректным. Даже в PEP постоянно проскакивают именно аргументы, хотя мы описываем функцию до получения аргументов, то есть говорим про параметры. Если вы можете объяснить почему пишут Arguments - напишите в чат

"""Retrieve and print words from a URL. Usage: python3 words.py <URL> """ import sys from urllib.request import urlopen def fetch_words(url): """Fetch a list of words from a URL. Args: url: The URL of a UTF-8 text document. Returns: A list of strings containing the words from the document """ # PEP 257 # story = urlopen("http://sixty-north.com/c/t.txt") story = urlopen(url) story_words = [] for line in story: line_words = line.decode("utf8").split() for word in line_words: story_words.append(word) story.close() return story_words def print_items(story_words): """Print items one per line. Args: An iterable series of printable items. """ for word in story_words: print(word) def main(url): words = fetch_words(url) print_items(words) if __name__ == "__main__": main(sys.argv[1])

Я бы переписал докстринг так

"""Fetch a list of words from a URL. Returns a list of strings containing the words from the document :param url: string The URL of a UTF-8 text document. :returns: list[str] """

Созданный нами docstring будет хорошо выглядеть в выводе help()

doctest

Если в docstring записать вызов фукнции как-будто в интерактивном режиме а затем ожидаемое значение - это можно протестировать с помощью doctest

""" Adds two float values >>> sum(0, 1.0) 1.0 """ def sum(first: float, second: float) -> float: """Adds two float values :param first: float first addend :param second: float second addend :return: first + second """ return first + second

python -m doctest .\docstring.py -v

Как вариант можно было задать такую инструкцию

if __name__ == '__main__': import doctest doctest.testmod()

Тогда можно запускать следующим способом

python .\docstring.py -v

Trying: sum(0, 1.0) Expecting: 1.0 ok 1 items had no tests: __main__.sum 1 items passed all tests: 1 tests in __main__ 1 tests in 2 items. 1 passed and 0 failed. Test passed.

РЕКЛАМА от Яндекса. Может быть недоступна в вашем регионе

Конец рекламы от Яндекса. Если в блоке пусто считайте это рекламой моей телеги

Изучение help

python

Python 3.9.5 (default, Jun 15 2021, 15:30:04) [GCC 9.3.0] on linux Type "help", "copyright", "credits" or "license" for more information.

>>> import words
>>> help(words)

Help on module words: NAME words - Retrieve and print words from a URL. DESCRIPTION Usage: python3 words.py <URL> FUNCTIONS fetch_words(url) Fetch a list of words from a URL. Args: url: The URL of a UTF-8 text document. Returns: A list of strings containing the words from the document main(url) print_items(story_words) Print items one per line. Args: An iterable series of printable items. FILE /home/andrei/python/words.py

Похожие статьи
Основы Python
Type Hints
__future__
configparser
Менеджер контекста
docstring
#!: Shebang
Объекты
Итерация
os
pathlib

РЕКЛАМА от Яндекса. Может быть недоступна в вашем регионе

Конец рекламы от Яндекса. Если в блоке пусто считайте это рекламой моей телеги

Поиск по сайту

Подпишитесь на Telegram канал @aofeed чтобы следить за выходом новых статей и обновлением старых

Перейти на канал

@aofeed

Задать вопрос в Телеграм-группе

@aofeedchat

Контакты и сотрудничество:
Рекомендую наш хостинг beget.ru
Пишите на info@urn.su если Вы:
1. Хотите написать статью для нашего сайта или перевести статью на свой родной язык.
2. Хотите разместить на сайте рекламу, подходящую по тематике.
3. Реклама на моём сайте имеет максимальный уровень цензуры. Если Вы увидели рекламный блок недопустимый для просмотра детьми школьного возраста, вызывающий шок или вводящий в заблуждение - пожалуйста свяжитесь с нами по электронной почте
4. Нашли на сайте ошибку, неточности, баг и т.д. ... .......
5. Статьи можно расшарить в соцсетях, нажав на иконку сети: