sphinx_gallery.backreferences#

Backreferences Generator.

Parses example file code in order to keep track of used functions.

Functions#

sphinx_gallery.backreferences.identify_names(script_blocks, ref_regex, global_variables=None, node='')[source]#

Build a codeobj summary by identifying and resolving used names.

Parameters:

  • script_blocks (list) – (label, content, line_number) List where each element is a tuple with the label (‘text’ or ‘code’), the corresponding content string of block and the leading line number.

  • ref_regex (str) – Regex to find references to python objects.

  • example_globals (Optional[Dict[str, Any]]) – Global variables for examples. Default=None

  • node (ast.Module or str) – The parsed node. Default=””.

Returns:

example_code_obj – Dict with information about all code object references found in an example. Dict contains the following keys:

  • example_code_obj[‘name’] : function or class name (str)

  • example_code_obj[‘module’] : module name (str)

  • example_code_obj[‘module_short’] : shortened module name (str)

  • example_code_obj[‘is_class’] : whether object is class (bool)

  • example_code_obj[‘is_explicit’]whether object is an explicit

    backreference (referred to by sphinx markup) (bool)

Return type:

Dict[str, Any]

Classes#

class sphinx_gallery.backreferences.NameFinder(global_variables=None)[source]#

Finds the longest form of variable names and their imports in code.

Only retains names from imported modules.

get_mapping()[source]#

Map names used in code, using AST nodes, to their fully qualified names.

Returns:

options – List of tuples, each tuple containing the following information about an accessed_name:

accessed name : str, fully qualified name : str if it is a class attribute (i.e., property or method) : bool if it is a class : bool if it is an explicit backreference : bool (always false here)

Return type:

List[Tuple[str]]

visit_Attribute(node)[source]#

Add attributes, including their prefix, to accessed_names.

visit_Import(node, prefix='')[source]#

For ‘import’ add node names to imported_names.

visit_ImportFrom(node)[source]#

For ‘from import’ add node names to imported_names, incl module prefix.

visit_Name(node)[source]#

Add node id to accessed_names.