origen_autoapi

Module that provides the module tree node APINode.

This class will load the module identified by name and recursively build a tree with all it’s submodules and subpackages. In the process, each node analyze and fetch the public API of that module.

name can be any node, like the root package, or any subpackage or submodule and a tree will be built from there. name must follow the standard “dot notation” for importing a module.

This class will not assume any special naming, or perform any complex analysis to determine what must be in the public interface. This is because it is not only a difficult problem, but it involves analyzing deeply the namespace of the module which can be quite expensive.

In general it is very difficult to determine in a module namespace what elements are private or public declared locally, private or public but declared in another module and brought into the module local namespace (from x import y), third party library, Python standard library, etc. At the end, any algorithm that tries to determine this will eventually fail to meet the requirements or expectations of the developer, leaving false positives or removing elements expected to be present in the public API.

For example, a common scenario is that some modules, specially package entry points __init__.py, can be setup to expose the public API of their sibling modules, possible causing several objects to be identified as part of the public API of both modules.

Because of this the approach taken by this module follows the rule in PEP20 “Explicit is better than implicit”. In consequence, the node will consider elements as public if they are explicitly listed in the __api__ or __all__ variables. It is up to the developer to list the elements that must be published in the public API.

__api__ is a special variable introduced by this module, and it exists for situation were for whatever reason the developer don’t want to list in the __all__ variable an element that needs to be published in the public API.

This class will extract all elements identified in ONE of those listings (not the union), with __api__ having the precedence. If none of those variables exists in the module then it will be assumed that no public API exists for that module and no futher actions will be taken.

If any of those variables exists this class will iterate all elements listed in them and will catalog them in four categories:

  • Functions.

  • Exceptions.

  • Classes.

  • Variables.

Being Variables the default if it cannot be determined that an element belongs to any of other categories.

Classes

  • APINode: Tree node class for module instrospection.

class origen_autoapi.APINode(name, directory=None, *, prebuilt=False, context={})

Tree node class for module instrospection.

Parameters

  • name (str) – Name of the module to build the tree from. It must follow the “dot notation” of the import mechanism.

  • directory (dict) – Directory to store the index of all the modules. If None, the default, the root node will create one a pass it to the subnodes.

Attributes:

Variables

  • name – Name of the current module.

  • subname – Last part of the name of this module. For example if name is my.module.another the subname will be another.

  • directory – Directory of the tree. This is a OrderedDict that will register all modules name with it’s associated node APINode. All nodes of a tree share this index and thus the whole tree can be queried from any node.

  • module – The loaded module.

  • subnodes – A list of APINode with all child submodules and subpackages.

  • subnodes_failed – A list of submodules and subpackages names that failed to import.

Public API categories:

Variables

  • functions – A OrderedDict of all functions found in the public API of the module.

  • classes – A OrderedDict of all classes found in the public API of the module.

  • exceptions – A OrderedDict of all exceptions found in the public API of the module.

  • variables – A OrderedDict of all other elements found in the public API of the module.

In all categories the order on which the elements are listed is preserved.

Inheritance

Inheritance diagram of APINode