def extract(py_modules,
base_dir,
private_map,
do_not_descend_map,
visitor_cls=doc_generator_visitor.DocGeneratorVisitor,
callbacks=None):
"""Walks the module contents, returns an index of all visited objects.
The return value is an instance of `self._visitor_cls`, usually:
`doc_generator_visitor.DocGeneratorVisitor`
Args:
py_modules: A list containing a single (short_name, module_object) pair.
like `[('tf',tf)]`.
base_dir: The package root directory. Nothing defined outside of this
directory is documented.
private_map: A {'path':["name"]} dictionary listing particular object
locations that should be ignored in the doc generator.
do_not_descend_map: A {'path':["name"]} dictionary listing particular object
locations where the children should not be listed.
visitor_cls: A class, typically a subclass of
`doc_generator_visitor.DocGeneratorVisitor` that acumulates the indexes of
objects to document.
callbacks: Additional callbacks passed to `traverse`. Executed between the
`PublicApiFilter` and the accumulator (`DocGeneratorVisitor`). The
primary use case for these is to filter the listy of children (see:
`public_api.local_definitions_filter`)
Returns:
The accumulator (`DocGeneratorVisitor`)
"""
if callbacks is None:
callbacks = []
if len(py_modules) != 1:
raise ValueError("only pass one [('name',module)] pair in py_modules")
short_name, py_module = py_modules[0]
api_filter = public_api.PublicAPIFilter(
base_dir=base_dir,
do_not_descend_map=do_not_descend_map,
private_map=private_map)
accumulator = visitor_cls()
# The objects found during traversal, and their children are passed to each
# of these visitors in sequence. Each visitor returns the list of children
# to be passed to the next visitor.
visitors = [api_filter, public_api.ignore_typing
] + callbacks + [accumulator]
traverse.traverse(py_module, visitors, short_name)
return accumulator
def test_private_child_removal(self):
visitor = self.TestVisitor()
api_visitors = [
public_api.PublicAPIFilter(base_dir='/'),
visitor,
]
children = [('name1', 'thing1'), ('_name2', 'thing2')]
path = ('tf', 'test')
parent = 'dummy'
for api_visitor in api_visitors:
children = api_visitor(path, parent, children)
# Make sure the private symbols are removed before the visitor is called.
self.assertEqual([('name1', 'thing1')], visitor.last_children)
self.assertEqual([('name1', 'thing1')], children)
def test_private_map_child_removal(self):
visitor = self.TestVisitor()
api_visitors = [
public_api.PublicAPIFilter(
base_dir='/', private_map={'tf.test': ['mock']}), visitor
]
children = [('name1', 'thing1'), ('mock', 'thing2')]
path = ('tf', 'test')
parent = 'dummy'
for api_visitor in api_visitors:
children = api_visitor(path, parent, children)
# Make sure private aliases are removed.
self.assertEqual([('name1', 'thing1')], visitor.last_children)
self.assertEqual([('name1', 'thing1')], children)
def test_no_descent_child_removal(self):
visitor = self.TestVisitor()
api_visitors = [
public_api.PublicAPIFilter(
base_dir='/', do_not_descend_map={'tf.test': ['mock']}), visitor
]
children = [('name1', 'thing1'), ('name2', 'thing2')]
path = ('tf', 'test', 'mock')
parent = 'dummy'
for api_visitor in api_visitors:
children = api_visitor(path, parent, children)
# Make sure not-to-be-descended-into symbols's children are removed.
self.assertEqual([], visitor.last_children)
self.assertEqual([], children)
def test_call_forward(self):
visitor = self.TestVisitor()
api_visitors = [public_api.PublicAPIFilter(base_dir='/'), visitor]
path = ('tf', 'test')
parent = 'dummy'
children = [('name1', 'thing1'), ('name2', 'thing2')]
for api_visitor in api_visitors:
children = api_visitor(path, parent, children)
self.assertEqual(set([(
'tf',
'test',
)]), visitor.symbols)
self.assertEqual('dummy', visitor.last_parent)
self.assertEqual([('name1', 'thing1'), ('name2', 'thing2')],
visitor.last_children)
