epyparse 0.2.5

Generate API info for Python Packages via Epydoc

Formatting and serialization of epydoc-parsed Python source code. Source code is only ever parsed textually, never imported.

Command line Usage

prettyprint

Pretty print a representation of the API of a named object or file:

$ epyparse print -path <name_or_path> [options]

which can be shortened to:

$ epyparse <name_or_path> [options]

By default, output is colored for the terminal, you can turn this off with the -nocolor option.

serialize

Flatten the recursive API structure of a named object or file to a sequence of individual dictionaries. Each dictionary is JSON-serialized and saved to its own file:

$ epyparse serialize -path <name_or_path> [options]

By default, files are written to the current working directory, you can specify another directory with the -out option:

$ epyparse serialize -path <name_or_path> -out docs/api

Programmatic Usage

Top-level functions are parsed, flattened, pprint and objectify:

>>> from epyparse import parsed, flattened, pprint, objectify

Input can be a file path:

>>> pprint('setup.py')
################################################################################
#    setup
################################################################################
"""
"""
<BLANKLINE>
import distutils.core.setup
import sys
import os
import epyparse
<BLANKLINE>

which must exist:

>>> parsed('does/not/exist')
Traceback (most recent call last):
    ...
IOError: No such file does/not/exist

Or a named object:

>>> pprint('os.getenv')
def getenv(key, default=None):
    """
    Get an environment variable, return None if it doesn't exist.
    The optional second argument can specify an alternate default.
    """
<BLANKLINE>

which must be accessible:

>>> pprint('does.not.exist')
Traceback (most recent call last):
    ...
ImportError: No Python source file found.

and not a builtin or c-based object:

>>> pprint('cStringIO.StringIO')
Traceback (most recent call last):
    ...
ImportError: No Python source file for builtin modules.

Modules, functions, classes or methods can be accessed:

>>> pprint('StringIO.StringIO.write')
def write(self, s):
    """
    Write a string to the file.
<BLANKLINE>
    There is no return value.
    """
<BLANKLINE>

Parse to a nested dictionary

Parse module:

>>> d = parsed('epydoc.apidoc')
>>> sorted(d.keys())
['children', 'docstring', 'fullname', 'imports', 'type']
>>> d['type']
'module'
>>> for item in sorted(d['children'], key=lambda d: (d['type'], d['fullname'])):
...     print item['type'], ' -> ', item['fullname']
class  ->  epydoc.apidoc.APIDoc
class  ->  epydoc.apidoc.ClassDoc
class  ->  epydoc.apidoc.ClassMethodDoc
class  ->  epydoc.apidoc.DocIndex
class  ->  epydoc.apidoc.DottedName
class  ->  epydoc.apidoc.GenericValueDoc
class  ->  epydoc.apidoc.ModuleDoc
class  ->  epydoc.apidoc.NamespaceDoc
class  ->  epydoc.apidoc.PropertyDoc
class  ->  epydoc.apidoc.RoutineDoc
class  ->  epydoc.apidoc.StaticMethodDoc
class  ->  epydoc.apidoc.ValueDoc
class  ->  epydoc.apidoc.VariableDoc
class  ->  epydoc.apidoc._Sentinel
function  ->  epydoc.apidoc._flatten
function  ->  epydoc.apidoc._pp_apidoc
function  ->  epydoc.apidoc._pp_dict
function  ->  epydoc.apidoc._pp_list
function  ->  epydoc.apidoc._pp_val
function  ->  epydoc.apidoc.pp_apidoc
function  ->  epydoc.apidoc.reachable_valdocs

Flatten and JSON-serialize

For the Object.get_parent and Object.get_children deserialization methods to work, we rely on the convention that api objects have been saved to the same directory with the canonical name as file name and with no file extension:

>>> import os, json
>>> assert not os.path.exists('TESTOUT')
>>> os.mkdir('TESTOUT')
>>> for item in flattened('epydoc.apidoc'):
...     print item['fullname']
...     with open('TESTOUT/' + item['fullname'], 'w+b') as fp:
...         json.dump(item, fp)
...
epydoc.apidoc._flatten
epydoc.apidoc._pp_apidoc
epydoc.apidoc._pp_dict
epydoc.apidoc._pp_list
epydoc.apidoc._pp_val
epydoc.apidoc.pp_apidoc
epydoc.apidoc.reachable_valdocs
epydoc.apidoc.APIDoc.__cmp__
epydoc.apidoc.APIDoc.__hash__
epydoc.apidoc.APIDoc.__init__
epydoc.apidoc.APIDoc.__repr__
epydoc.apidoc.APIDoc._debug_setattr
epydoc.apidoc.APIDoc._debug_setattr
epydoc.apidoc.APIDoc.apidoc_links
epydoc.apidoc.APIDoc.is_detailed
epydoc.apidoc.APIDoc.merge_and_overwrite
epydoc.apidoc.APIDoc.pp
epydoc.apidoc.APIDoc.pp
epydoc.apidoc.APIDoc.specialize_to
epydoc.apidoc.APIDoc
epydoc.apidoc.ClassDoc._c3_merge
epydoc.apidoc.ClassDoc._c3_mro
epydoc.apidoc.ClassDoc._dfs_bases
epydoc.apidoc.ClassDoc._report_bad_base
epydoc.apidoc.ClassDoc.apidoc_links
epydoc.apidoc.ClassDoc.is_exception
epydoc.apidoc.ClassDoc.is_newstyle_class
epydoc.apidoc.ClassDoc.is_type
epydoc.apidoc.ClassDoc.mro
epydoc.apidoc.ClassDoc.select_variables
epydoc.apidoc.ClassDoc
epydoc.apidoc.ClassMethodDoc
epydoc.apidoc.DocIndex.__init__
epydoc.apidoc.DocIndex._get
epydoc.apidoc.DocIndex._get_from
epydoc.apidoc.DocIndex._get_module_classes
epydoc.apidoc.DocIndex._update_funcid_to_doc
epydoc.apidoc.DocIndex.container
epydoc.apidoc.DocIndex.find
epydoc.apidoc.DocIndex.get_valdoc
epydoc.apidoc.DocIndex.get_vardoc
epydoc.apidoc.DocIndex.reachable_valdocs
epydoc.apidoc.DocIndex.read_profiling_info
epydoc.apidoc.DocIndex
epydoc.apidoc.DottedName.InvalidDottedName
epydoc.apidoc.DottedName.__add__
epydoc.apidoc.DottedName.__cmp__
epydoc.apidoc.DottedName.__getitem__
epydoc.apidoc.DottedName.__hash__
epydoc.apidoc.DottedName.__init__
epydoc.apidoc.DottedName.__len__
epydoc.apidoc.DottedName.__radd__
epydoc.apidoc.DottedName.__repr__
epydoc.apidoc.DottedName.__str__
epydoc.apidoc.DottedName.container
epydoc.apidoc.DottedName.contextualize
epydoc.apidoc.DottedName.dominates
epydoc.apidoc.DottedName
epydoc.apidoc.GenericValueDoc.is_detailed
epydoc.apidoc.GenericValueDoc
epydoc.apidoc.ModuleDoc.apidoc_links
epydoc.apidoc.ModuleDoc.init_submodule_groups
epydoc.apidoc.ModuleDoc.select_variables
epydoc.apidoc.ModuleDoc
epydoc.apidoc.NamespaceDoc.__init__
epydoc.apidoc.NamespaceDoc._init_grouping
epydoc.apidoc.NamespaceDoc.apidoc_links
epydoc.apidoc.NamespaceDoc.group_names
epydoc.apidoc.NamespaceDoc.init_sorted_variables
epydoc.apidoc.NamespaceDoc.init_variable_groups
epydoc.apidoc.NamespaceDoc.is_detailed
epydoc.apidoc.NamespaceDoc.report_unused_groups
epydoc.apidoc.NamespaceDoc
epydoc.apidoc.PropertyDoc.apidoc_links
epydoc.apidoc.PropertyDoc.is_detailed
epydoc.apidoc.PropertyDoc
epydoc.apidoc.RoutineDoc.all_args
epydoc.apidoc.RoutineDoc.is_detailed
epydoc.apidoc.RoutineDoc
epydoc.apidoc.StaticMethodDoc
epydoc.apidoc.ValueDoc.__getstate__
epydoc.apidoc.ValueDoc.__repr__
epydoc.apidoc.ValueDoc.__setstate__
epydoc.apidoc.ValueDoc.apidoc_links
epydoc.apidoc.ValueDoc.pyval_repr
epydoc.apidoc.ValueDoc.summary_pyval_repr
epydoc.apidoc.ValueDoc
epydoc.apidoc.VariableDoc.__init__
epydoc.apidoc.VariableDoc.__repr__
epydoc.apidoc.VariableDoc._get_defining_module
epydoc.apidoc.VariableDoc.apidoc_links
epydoc.apidoc.VariableDoc.is_detailed
epydoc.apidoc.VariableDoc
epydoc.apidoc._Sentinel.__init__
epydoc.apidoc._Sentinel.__nonzero__
epydoc.apidoc._Sentinel.__repr__
epydoc.apidoc._Sentinel
epydoc.apidoc

Deserialize to Object

>>> from epyparse import objectify
>>> obj = objectify('TESTOUT/epydoc.apidoc.APIDoc.merge_and_overwrite')

The returned Object type is a dict subclass:

>>> sorted(obj.keys())
[u'args', u'attributes', u'fullname', u'is_method', u'lineno', u'params', 'src', u'type']

with attribute-style access:

>>> obj.args
[u'self', u'other']
>>> obj.is_method
True
>>> obj.lineno * 0
0
>>> obj.params
[[u'ignore_hash_conflict', False]]
>>> obj.name
u'merge_and_overwrite'

Object.parent gives the name of the parent object, if any:

>>> obj.parent
u'epydoc.apidoc.APIDoc'

And, because we have serialized the parent to the same directory, we can retrieve it with the Object.get_parent method:

>>> parent = obj.get_parent()
>>> parent.fullname
u'epydoc.apidoc.APIDoc'
>>> parent.type
u'class'
>>> parent.name
u'APIDoc'

Similarly, Object.members returns the names of the object’s members, if any:

>>> for name in sorted(parent.members):
...     print parent.fullname + '.' + name
epydoc.apidoc.APIDoc.__cmp__
epydoc.apidoc.APIDoc.__hash__
epydoc.apidoc.APIDoc.__init__
epydoc.apidoc.APIDoc.__repr__
epydoc.apidoc.APIDoc._debug_setattr
epydoc.apidoc.APIDoc._debug_setattr
epydoc.apidoc.APIDoc.apidoc_links
epydoc.apidoc.APIDoc.is_detailed
epydoc.apidoc.APIDoc.merge_and_overwrite
epydoc.apidoc.APIDoc.pp
epydoc.apidoc.APIDoc.pp
epydoc.apidoc.APIDoc.specialize_to

and Object.get_members deserializes each member:

>>> for child in sorted(parent.get_members(), key=lambda d: d['fullname']):
...     print child.type, ' -> ', child.name
function  ->  __cmp__
function  ->  __hash__
function  ->  __init__
function  ->  __repr__
alias  ->  _debug_setattr
alias  ->  _debug_setattr
function  ->  apidoc_links
function  ->  is_detailed
function  ->  merge_and_overwrite
function  ->  pp
function  ->  pp
function  ->  specialize_to

Introspection - inspect vs. Inspector

>>> import inspect
>>> from epydoc.apidoc import APIDoc
>>> from epyparse import Inspector
>>> merge_and_overwrite_obj = obj
>>> APIDoc_obj = parent

argspec (not identical but good enough for displaying the function signature):

>>> inspect.getargspec(APIDoc.merge_and_overwrite)
ArgSpec(args=['self', 'other', 'ignore_hash_conflict'], varargs=None, keywords=None, defaults=(False,))
>>> Inspector.getargspec(merge_and_overwrite_obj)
ArgSpec(args=[u'self', u'other', u'ignore_hash_conflict'], varargs=None, keywords=None, defaults=(False,))

>>> inspect.getargspec(APIDoc.apidoc_links)
ArgSpec(args=['self'], varargs=None, keywords='filters', defaults=None)
>>> Inspector.getargspec(APIDoc_obj.get_member('apidoc_links'))
ArgSpec(args=[u'self'], varargs=None, keywords=u'filters', defaults=None)

hasattr:

>>> hasattr(APIDoc, 'merge_and_overwrite')
True
>>> Inspector.hasattr(APIDoc_obj, 'merge_and_overwrite')
True
>>> Inspector.hasattr(APIDoc_obj, 'somethingsomethingorangessomething')
False

dir

>>> dir(merge_and_overwrite_obj)
['__dict__', u'__doc__', u'__name__']
>>> sorted(dir(APIDoc_obj))[:7]
[u'__cmp__', '__dict__', u'__doc__', u'__hash__', u'__init__', u'__name__', u'__repr__']
>>> sorted(dir(APIDoc_obj))[7:13]
[u'_debug_setattr', u'_debug_setattr', u'apidoc_links', u'is_detailed', u'merge_and_overwrite', u'pp']
>>> module_obj = objectify('TESTOUT/epydoc.apidoc')
>>> sorted(dir(module_obj))[:7]
[u'APIDoc', u'ClassDoc', u'ClassMethodDoc', u'DocIndex', u'DottedName', u'GenericValueDoc', u'ModuleDoc']

__doc__

>>> hasattr(APIDoc.merge_and_overwrite, '__doc__')
True
>>> hasattr(merge_and_overwrite_obj, '__doc__')
True
>>> Inspector.hasattr(merge_and_overwrite_obj, '__doc__')
True
>>> actual = ''.join(
...   s.strip() for s in APIDoc.merge_and_overwrite.__doc__.splitlines() if s.strip()
... )
...
>>> serialized = ''.join(
...   s.strip() for s in merge_and_overwrite_obj.__doc__.splitlines() if s.strip()
... )
...
>>> assert len(actual) and len(serialized)
>>> assert actual == serialized

__dict__

>>> Inspector.hasattr(merge_and_overwrite_obj, '__dict__')
True
>>> d = Inspector.getattr(merge_and_overwrite_obj, '__dict__')
>>> d['__name__']
u'merge_and_overwrite'
>>> print d['__doc__'] #doctest: +ELLIPSIS
Combine C{self} and C{other} into a X{merged object}, such
that any changes made to one will affect the other.  Any...

Base classes

Tidy up:

>>> import shutil
>>> shutil.rmtree('TESTOUT')