Использование pydoc для модулей с импортированными функциями

Я создал свой собственный модуль X. Вначале я импортирую функции из некоторых других модулей (например, from math import func). Я заметил, что когда я создаю документацию с помощью:

pydoc -w X

результирующий файл также содержит импортированную функцию function из модуля math, что нежелательно (особенно если я импортирую много функций из нескольких модулей, что я и делаю).

Этого можно избежать, вместо этого вызвав:

import math

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

Есть ли другой способ, с помощью которого я могу избежать заполнения моей документации импортированными функциями, но при этом иметь возможность импортировать функции с помощью from?


python module import pydoc
person Luisa    schedule 12.01.2016    source источник

Ответы (1)


arrow_upward
5
arrow_downward

Заглянув в исходный код Pydoc, вы увидите сделан следующий комментарий:

if all is not None:
     # only document that which the programmer exported in __all__
     return name in all

это означает, что pydoc будет искать атрибут модуля __all__ и, если он определен, будет документировать только определенные в нем функции.

Итак, для вашего модуля X вы можете определить функции для экспорта в __all__, указав их имена. Только они будут задокументированы в соответствующем разделе Функции:

__all__ = ['myfunc1', 'myfunc2', ..., 'myfuncN']

Показательный пример:

Без __all__ следующий простой файл с именем mod.py:

from math import cos

def myfunc():
    """ documentation"""
    pass

Создает файл mod.html, содержащий документацию для определенных пользователем myfunc() и для импортированной встроенной функции cos():

введите здесь описание изображения

Добавив __all__ и указав имена функций, которые вы хотите экспортировать внутри него:

__all__ = ['myfunc']  # visible names
from math import cos

def myfunc():
    """ documentation"""
    pass

Вы «отфильтруете» функцию cos() и получите документацию только для myfunc():

введите здесь описание изображения

Примечание. __all__ может содержать имена функций и переменных, используемых внутри вашего скрипта. pydoc будет различать их и разделять на две разные группы:

  1. Функции в разделе Функции
  2. Переменные в Данные.
person Dimitris Fasarakis Hilliard    schedule 12.01.2016