Module pdoc

Wat wat.

Module pdoc provides types and functions for accessing the public documentation of a Python module. This includes module level variables, modules (and sub-modules), functions, classes and class and instance variables. Docstrings are taken from modules, functions, and classes using special __doc__ attribute. Docstrings for any of the variables are extracted by examining the module's abstract syntax tree.

The public interface of a module is determined through one of two ways. If __all__ is defined in the module, then all identifiers in that list will be considered public. No other identifiers will be considered as public. Conversely, if __all__ is not defined, then pdoc will heuristically determine the public interface. There are two simple rules that are applied to each identifier in the module:

  1. If the name starts with an underscore, it is not public.

  2. If the name is defined in a different module, it is not public.

  3. If the name is a direct sub-module, then it is public.

Once documentation for a module is created, it can be outputted in either HTML or plain text using the covenience functions html and text, or the corresponding methods html and text.

Index

Module variables

var html_module_suffix

The suffix to use for module HTML files. By default, this is set to .m.html, where the extra .m is used to differentiate a package's index.html from a submodule called index.

var html_package_name

The file name to use for a package's __init__.py module.

var import_path

A list of paths to restrict imports to. Any module that cannot be found in import_path will not be imported. By default, it is set to a copy of sys.path at initialization.

var template_path

A list of paths to search for Mako templates used to produce the plain text and HTML output. Each path is tried until a template is found.

Functions

def html(module_name, docfilter=None, allsubmodules=False, external_links=False, link_prefix='')

Returns the documentation for the module module_name in HTML format. The module must be importable.

docfilter is an optional predicate that controls which documentation objects are shown in the output. It is a single argument function that takes a documentation object and returns True or False. If False, that object will not be included in the output.

If allsubmodules is True, then every submodule of this module that can be found will be included in the documentation, regardless of whether __all__ contains it.

If external_links is True, then identifiers to external modules are always turned into links.

If link_prefix is set, then all links will have that prefix. Otherwise, links are always relative.

def import_module(module_name)

A simple wrapper around __import__ and reload, where reload is called when module_name is in sys.modules.

def text(module_name, docfilter=None, allsubmodules=False)

Returns the documentation for the module module_name in plain text format. The module must be importable.

docfilter is an optional predicate that controls which documentation objects are shown in the output. It is a single argument function that takes a documentation object and returns True of False. If False, that object will not be included in the output.

If allsubmodules is True, then every submodule of this module that can be found will be included in the documentation, regardless of whether __all__ contains it.

Classes

class Class

Representation of a class's documentation.

Ancestors (in MRO)

  • __pdoc_file_module__.Class
  • __pdoc_file_module__.Doc
  • __builtin__.object

Instance variables

var cls

The class object.

var doc

A mapping from identifier name to a documentation object.

var doc_init

A special version of self.doc that contains documentation for instance variables found in the init method.

var public

A mapping from identifier name to Python object for all exported identifiers in this class. Exported identifiers are any identifier that does not start with underscore.

var refname

 

Methods

def __init__(self, module, class_obj)

 

def class_variables(self)

Returns all documented class variables in the class, sorted alphabetically.

def functions(self)

Returns all documented static functions as Function objects in the class, sorted alphabetically.

def instance_variables(self)

Returns all documented instance variables in the class, sorted alphabetically.

def is_empty(self)

Returns true if the docstring for this object is empty.

def methods(self)

Returns all documented methods as Function objects in the class, sorted alphabetically with new and init always coming first.

class Doc

A base class for all documentation objects.

Ancestors (in MRO)

  • __pdoc_file_module__.Doc
  • __builtin__.object

Instance variables

var docstring

The docstring for this object.

var module

The module documentation object that this object was defined in.

var name

The identifier name for this object.

var refname

Returns an appropriate reference name for this documentation object. Usually this is its fully qualified path.

e.g., The refname for this property is pdoc.Doc.refname.

Methods

def __init__(self, module, name, docstring)

 

def is_empty(self)

Returns true if the docstring for this object is empty.

class External

A representation of an external identifier. The textual representation is the same as an internal identifier, but the HTML version will lack a link while the internal identifier will link to its documentation.

Ancestors (in MRO)

  • __pdoc_file_module__.External
  • __pdoc_file_module__.Doc
  • __builtin__.object

Instance variables

var refname

 

Methods

def __init__(self, name)

 

def is_empty(self)

Returns true if the docstring for this object is empty.

class Function

Representation of a function's documentation.

Ancestors (in MRO)

  • __pdoc_file_module__.Function
  • __pdoc_file_module__.Doc
  • __builtin__.object

Class variables

var ClassVariable

Doco for class variable.

Instance variables

var cls

The Class documentation object if this is a method. If not, this is None.

var func

The function object.

var method

Whether this function is a method or not.

Static class methods have this set to False.

var refname

 

Methods

def __init__(self, module, func_obj, cls=None, method=False)

 

def is_empty(self)

Returns true if the docstring for this object is empty.

def params(self)

Returns a nicely formatted list of parameters to this function. This includes argument lists, keyword arguments and default values.

def spec(self)

Returns a nicely formatted spec of the function's parameter list. This includes argument lists, keyword arguments and default values.

class Module

Representation of a module's documentation.

Ancestors (in MRO)

  • __pdoc_file_module__.Module
  • __pdoc_file_module__.Doc
  • __builtin__.object

Instance variables

var doc

A mapping from identifier name to a documentation object.

var name

 

var pkgdir

 

var public

A mapping from identifier name to Python object for all exported identifiers in this module. When __all__ exists, then the keys in this dictionary always correspond to the values in __all__. When __all__ does not exist, then the public identifiers are inferred heuristically. (Currently, all not starting with an underscore are public.)

var refdoc

The same as doc, but maps fully qualified identifier names to documentation objects.

var refname

 

Methods

def __init__(self, module, docfilter=None, allsubmodules=False)

Creates a Module documentation object given the actual module Python object.

docfilter is an optional predicate that controls which documentation objects are returned in the following methods: classes, functions, variables and submodules. The filter is propagated to the analogous methods on a Class object.

If allsubmodules is True, then every submodule of this module that can be found will be included in the documentation, regardless of whether __all__ contains it.

def classes(self)

Returns all documented module level classes in the module sorted alphabetically.

def descendents(self, cls)

Returns a descendent list of documentation objects for cls, which must be a documentation object.

The list will contain objects belonging to Class or External. Objects belonging to the former are exported classes either in this module or in one of its sub-modules.

def find_ident(self, name)

Searches this module and all of its sub-modules for an identifier with name name in its list of exported identifiers according to pdoc. Note that unexported sub-modules are searched.

A bare identifier (without . separators) will only be checked for in this module.

The documentation object corresponding to the identifier is returned. If one cannot be found, then an instance of External is returned populated with the given identifier.

def functions(self)

Returns all documented module level functions in the module sorted alphabetically.

def html(self, external_links=False, link_prefix='', **kwargs)

Returns the documentation for this module as self-contained HTML.

If external_links is True, then identifiers to external modules are always turned into links.

If link_prefix is set, then all links will be absolute with the prefix given. Otherwise, links are always relative.

kwargs is passed to the mako render function.

def is_empty(self)

Returns true if the docstring for this object is empty.

def is_exported(self, name, module)

Returns true if and only if pdoc considers name to be a public identifier for this module where name was defined in the Python module module.

If this module has an __all__ attribute, then name is considered to be exported if and only if it is a member of this module's __all__ list.

If __all__ is not set, then whether name is exported or not is heuristically determined. Firstly, if name starts with an underscore, it will not be considered exported. Secondly, if name was defined in a module other than this one, it will not be considered exported. In all other cases, name will be considered exported.

def is_package(self)

Returns True if this module is a package.

Works by checking if __package__ is not None and whether it has the __path__ attribute.

def is_public(self, name)

Returns True if and only if an identifier with name name is part of the public interface of this module. While the names of sub-modules are included, identifiers only exported by sub-modules are not checked.

name should be a fully qualified name, e.g., is_public.

def is_submodule(self, name)

 

def mro(self, cls)

Returns a method resolution list of documentation objects for cls, which must be a documentation object.

The list will contain objects belonging to Class or External. Objects belonging to the former are exported classes either in this module or in one of its sub-modules.

def submodules(self)

Returns all documented sub-modules in the module sorted alphabetically.

def text(self)

Returns the documentation for this module as plain text.

def variables(self)

Returns all documented module level variables in the module sorted alphabetically.

class Variable

Representation of a variable's documentation. This includes module, class and instance variables.

Ancestors (in MRO)

  • __pdoc_file_module__.Variable
  • __pdoc_file_module__.Doc
  • __builtin__.object

Instance variables

var cls

The Class documentation object if this is a method. If not, this is None.

var refname

 

Methods

def __init__(self, module, name, docstring, cls=None)

 

def is_empty(self)

Returns true if the docstring for this object is empty.

Documentation generated by pdoc.