Я пишу контент для AWS, Kubernetes, Python, JavaScript и многое другое. Чтобы просмотреть весь последний контент, обязательно Посетите мой блог и подписаться на мою рассылку. Подпишись на меня в Твиттере .
Это день 19 #100daysOfpython Challenge.
Этот пост будет использовать pydoc Модуль из стандартной библиотеки, чтобы изучить, как мы можем ориентироваться в документации, а также создать свою собственную.
Код можно найти на моем GitHub Repo Анкет
Начиная
Давайте создадим Hello-Pydoc каталог и настройте необходимые файлы.
# Make the `hello-pydoc` directory $ mkdir hello-pydoc $ cd hello-pydoc # Create a folder to place our example files $ mkdir src # Create the required files $ touch src/math.py main.py src/__init__.py
На этом этапе у нас есть сортированные файлы, и мы можем начать писать какой -то код.
Изучение Pydoc из командной строки
Pydoc – это инструмент, который позволяет нам исследовать документацию модуля.
В качестве простого стартера мы можем использовать Pydoc для изучения документации DateTime модуль из командной строки.
Для этого мы можем запустить python -m pydoc [module] И мы должны увидеть выход на основе строк DOC для каждой из функций в модуле.
Давайте рассмотрим это для DateTime модуль. Из командной строки мы можем запустить следующую команду:
$ python -m pydoc datetime
Help on module datetime:
NAME
datetime - Fast implementation of the datetime type.
FILE
/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/lib-dynload/datetime.so
MODULE DOCS
https://docs.python.org/library/datetime
CLASSES
__builtin__.object
date
datetime
time
timedelta
tzinfo
class date(__builtin__.object)
| date(year, month, day) --> date object
|
| Methods defined here:
|
| __add__(...)
x.__add__(y) <==> x+y
|
| __eq__(...)
# ... reset omitted for brevity ...
Когда вы запускаете команду, она открывает документацию для DateTime модуль, который можно пройти в командной строке.
Это дает нам информацию о следующем:
| ИМЯ | Имя модуля. |
| ФАЙЛ | Файл, который модуль определяется в. |
| Модульные документы | Ссылка на документацию для модуля. |
| Классы | Классы, определенные в модуле. |
Мы можем искать в документах, используя / или ? оператор с последующим поисковым термином.
Например, в моем предыдущем сообщении в блоге DateTime в Python , мы сильно полагались на datetime.datetime.now функция
Чтобы найти эту документацию, я могу запустить / с последующим в настоящее время и один из результатов поиска вернет следующее:
now(tz=None) from builtins.type
Returns new datetime object representing current time local to tz.
tz
Timezone object.
If no tz is specified, uses local timezone.
Совет: после поиска вы можете использовать n Ключ, чтобы перейти к следующему результату.
Приведенная выше документация говорит нам, что Теперь Функция возвращает DateTime объект с местным временем и датой часового пояса (с необязательным аргументом часового пояса).
Учитывая это, мы знаем, что можем функция как с аргументом, так и без этого:
from datetime import datetime, timezone datetime.now() # datetime.datetime(2021, 8, 7, 7, 22, 37, 216899) datetime.now(timezone.utc) # datetime.datetime(2021, 8, 6, 21, 22, 30, 841500, tzinfo=datetime.timezone.utc)
Если мы пойдем на поиски синонимичной функции utcnow , мы можем увидеть следующее:
utcnow(...) from builtins.type
Return a new datetime representing UTC day and time.
Это говорит нам о том, что нет никаких аргументов, но возвращаемое значение – это DateTime Объект с часовым поясом UTC.
from datetime import datetime datetime.utcnow() # datetime.datetime(2021, 8, 6, 21, 24, 2, 865402)
Теперь, когда мы знаем основы поиска Pydoc, давайте теперь документируем наш Математика модуль.
Написание нашего документированного кода
Мы можем написать и искать наши собственные Docstrings Анкет
Чтобы продемонстрировать, добавьте следующий код в src/math.py :
def add(x, y):
"""add together two numbers
Args:
x (int): First number to add
y (int): Second number to add
Returns:
int: sum of x and y
"""
return x + y
Docstring это строка, которая используется для документирования функции и обозначается как комментарий между строк 2 и 10 кода выше.
Совет: если вы используете VSCODE, проверьте докстронг генератор
Как только у нас появится этот код, достаточно, чтобы просмотреть нашу собственную документацию для модуля!
Изучение нашего задокументированного кода
Мы можем запустить Python -m Pydoc src.math и мы должны увидеть вывод Docstring :
Help on module src.math in src:
NAME
src.math
FUNCTIONS
add(x, y)
add together two numbers
Args:
x (int): First number to add
y (int): Second number to add
Returns:
int: sum of x and y
FILE
/path/to/code/blog-projects/hello-pydoc/src/math.py
Как это было легко!
Просмотр Pydoc в браузере
Если мы запустим pydoc -h , мы видим следующее:
-h pydoc - the Python documentation tool pydoc... Show text documentation on something. may be the name of a Python keyword, topic, function, module, or package, or a dotted reference to a class or function within a module or module in a package. If contains a '/', it is used as the path to a Python source file to document. If name is 'keywords', 'topics', or 'modules', a listing of these things is displayed. pydoc -k Search for a keyword in the synopsis lines of all available modules. pydoc -p Start an HTTP server on the given port on the local machine. Port number 0 can be used to get an arbitrary unused port. pydoc -g Pop up a graphical interface for finding and serving documentation. pydoc -w ... Write out the HTML documentation for a module to a file in the current directory. If contains a '/', it is treated as a filename; if it names a directory, documentation is written for all the contents.
Это дает нам список вариантов, которые мы можем использовать для просмотра нашей собственной документации.
Прежде всего, мы будем использовать pydoc -p 4000 Опция запустить сервер на порту 4000.
Отсюда вы можете открыть http://localhost: 4000 в вашем браузере и изучите документацию. Интерфейс не симпатичен, но работа выполняется.
Вывод Pydoc как HTML
Наконец, мы можем вывести документацию как HTML, передавая -W опция на pydoc Анкет
Бег Пидок -w src.math Выходы HTML в src.math.html который содержит следующее:
Python: module src.math
| src.math | /path/to/code/blog-projects/hello-pydoc/src/math.py |
| Functions | ||
|
||
Резюме
Сегодняшний пост продемонстрировал, как использовать pydoc Пакет для изучения встроенной и пользовательской документации.
Несмотря на неглубокое исследование, лучший способ улучшить вашу возможность поиска – использовать командную строку на практике.
Ресурсы и дальнейшее чтение
Кредит фото: Milada_vigerova
Первоначально опубликовано на моем блог . Чтобы увидеть новые сообщения без промедления, прочитайте сообщения там и подпишитесь на мою рассылку.
Оригинал: “https://dev.to/okeeffed/how-pydoc-helps-your-python-development-432h”