# 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]]]

  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]]]

### Examples using `sphinx_gallery.backreferences.identify_names`

Identifying function names in a script

Identifying function names in a script

## Classes

class sphinx_gallery.backreferences.Backreference(fname, src_dir, target_dir, intro, title)
  fname: str

    Alias for field number 0

  intro: str

    Alias for field number 3

  src_dir: str

    Alias for field number 1

  target_dir: str

    Alias for field number 2

  title: str

    Alias for field number 4

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

  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]]

    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

    Add attributes, including their prefix, to accessed_names.

  visit_Import(node, prefix: str = '') → None

    For ‘import’ add node names to imported_names.

  visit_ImportFrom(node) → None

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

  visit_Name(node) → None

    Add node id to accessed_names.