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: list[Block], ref_regex: str, global_variables: dict[str, Any] | None = None, node='') → dict[str, list[dict[str, Any]]][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.

  • global_variables (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. Keys are the names as used in the example, values are lists of possible resolved objects with the following keys:

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

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

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

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

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

    backreference (referred to by sphinx markup) (bool)

Return type:

dict[str, list[dict[str, Any]]]

Classes#

class sphinx_gallery.backreferences.NameFinder(global_variables: dict[str, Any] | None = None)[source]#

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

Only retains names from imported modules.

get_mapping() → list[tuple[str, str, bool, bool, bool]][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) → None[source]#

Add attributes, including their prefix, to accessed_names.

visit_Import(node, prefix: str = '') → None[source]#

For ‘import’ add node names to imported_names.

visit_ImportFrom(node) → None[source]#

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

visit_Name(node) → None[source]#

Add node id to accessed_names.