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)