Exhale Utils Module

exhale.utils.AVAILABLE_KINDS = ['class', 'define', 'dir', 'enum', 'enumvalue', 'file', 'function', 'group', 'namespace', 'struct', 'typedef', 'union', 'variable', 'page']

All potential input kind values coming from Doxygen.

The "group" and "enumvalue" kinds are currently detected, but unused.

exhale.utils.LEAF_LIKE_KINDS = ['define', 'enum', 'function', 'class', 'struct', 'typedef', 'union', 'variable']

All kinds that can be generated using ExhaleRoot.generateSingleNodeRST.

This more or less corresponds to the kinds that Exhale uses a Breathe directive. This is everything in AVAILABLE_KINDS, except for

  • "enumvalue" and "group" (unused in framework), and

  • "dir", "file", and "namespace" since they require special treatment.


Generates a string .. contents:: directives according to the rules outlined in the Using Contents Directives section.

kind (str)

The kind of the compound (one of AVAILABLE_KINDS).

str or None

If this kind should have a .. contents:: directive, it returns the string that can be written to file. Otherwise, None is returned.

Breathe Customization Support


Creates the “pickleable” dictionary that will be used with customSpecificationsMapping supplied to exhale_args in your conf.py.

func (types.FunctionType)

A callable function that takes as input a string from AVAILABLE_KINDS and returns a list of strings.

The empty list [] indicates to use the Breathe defaults.


A dictionary where the keys are every value in AVAILABLE_KINDS, and the values are the list returns of the input func.


To help ensure the dictionary has everything it needs for the rest of Exhale to function, a “secret” key-value pair is inserted to the returned dictionary.

Unsorted Misc


cleanup / reorder these

exhale.utils.heading_mark(title, char)[source]

Given an input title and character, creates the reStructuredText underline according to the length of the title.

title (str)

The title that is being underlined, length assumed to be >= 1.

char (str)

The single character being used for this heading, e.g. SECTION_HEADING_CHAR.


Returns len(title) * char.


Qualifies the breathe kind and returns an qualifier string describing this to be used for the text output (e.g. in generated file headings and link names).

The output for a given kind is as follows:

Input Kind

Output Qualifier

























The following breathe kinds are ignored:

  • “autodoxygenfile”

  • “doxygenindex”

  • “autodoxygenindex”

Note also that although a return value is generated, neither “enumvalue” nor “group” are actually used.

kind (str)

The return value of a Breathe compound object’s get_kind() method.

Return (str)

The qualifying string that will be used to build the reStructuredText titles and other qualifying names. If the empty string is returned then it was not recognized.


Returns the appropriate breathe restructured text directive for the specified kind. The output for a given kind is as follows:

Input Kind

Output Directive



























The following breathe kinds are ignored:

  • “autodoxygenfile”

  • “doxygenindex”

  • “autodoxygenindex”

Note also that although a return value is generated, neither “enumvalue” nor “group” are actually used.

kind (str)

The kind of the breathe compound / ExhaleNode object (same values).

Return (str)

The directive to be used for the given kind. The empty string is returned for both unrecognized and ignored input values.



update docs for new list version rather than string returns

class exhale.utils.AnsiColors[source]

A simple wrapper class for convenience definitions of common ANSI formats to enable colorizing output in various formats. The definitions below only affect the foreground color of the text, but you can easily change the background color too. See ANSI color codes for a concise overview of how to use the ANSI color codes.

exhale.utils.indent(text, prefix, predicate=None)[source]

This is a direct copy of textwrap.indent for availability in Python 2.

Their documentation:

Adds ‘prefix’ to the beginning of selected lines in ‘text’. If ‘predicate’ is provided, ‘prefix’ will only be added to the lines where ‘predicate(line)’ is True. If ‘predicate’ is not provided, it will default to adding ‘prefix’ to all non-empty lines that do not consist solely of whitespace characters.

exhale.utils.prefix(token, msg)[source]

Wrapper call to indent() with an always-true predicate so that empty lines (e.g. n) still get indented by the token.

token (str)

What to indent the message by (e.g. "(!) ").

msg (str)

The message to get indented by token.


The message msg, indented by the token.

exhale.utils.colorize(msg, ansi_fmt)[source]
exhale.utils._use_color(msg, ansi_fmt, output_stream)[source]

Based on alwaysColorize, returns the colorized or non-colorized output when output_stream is not a TTY (e.g. redirecting to a file).

msg (str)

The message that is going to be printed by the caller of this method.

ansi_fmt (str)

The ANSI color format to use when coloring is supposed to happen.

output_stream (file)

Assumed to be either sys.stdout or sys.stderr.


The message msg in color, or not, depending on both alwaysColorize and whether or not the output_stream is a TTY.

exhale.utils.progress(msg, ansi_fmt='32;1m', output_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]
exhale.utils.info(msg, ansi_fmt='34;1m', output_stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]
exhale.utils.critical(msg, ansi_fmt='31;1m', output_stream=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)[source]
exhale.utils.verbose_log(msg, ansi_fmt=None)[source]
exhale.utils.__fancy(text, language, fmt)[source]
exhale.utils.fancyError(critical_msg=None, lex='py3tb', singleton_hook=None)[source]
exhale.utils.LANG_TO_LEX = {'C': 'c', 'C#': 'csharp', 'C++': 'cpp', 'D': 'd', 'Fortran': 'fortran', 'FortranFixed': 'fortranfixed', 'FortranFree': 'fortran', 'IDL': 'idl', 'Java': 'java', 'Javascript': 'js', 'Markdown': 'markdown', 'Objecive-C': 'objective-c', 'PHP': 'php', 'Python': 'py', 'VHDL': 'vhdl', 'Verilog': 'verilog'}
    "IDL":          "idl",
    "Java":         "java",
    "Javascript":   "js",
    "C#":           "csharp",
    "C":            "c",
    "C++":          "cpp",
    "D":            "d",
    "PHP":          "php",
    "Objecive-C":   "objective-c",
    "Python":       "py",
    "Fortran":      "fortran",
    "FortranFree":  "fortran",
    "FortranFixed": "fortranfixed",
    "VHDL":         "vhdl",
    "Verilog":      "verilog",
    "Markdown":     "markdown"

Mapping of language="xxx" from the Doxygen programlisting to Pygments Lexers. This mapping is used in doxygenLanguageToPygmentsLexer().

From the Doxygen documentation on EXTENSION_MAPPING:

IDL, Java, Javascript, C#, C, C++, D, PHP, Objective-C, Python,Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: Fortran. In the later case the parser tries to guess whether the code is fixed or free formatted code, this is the default for Fortran type files), VHDL.

We need to take each one of those, and map them to their corresponding Pygments Lexer.


Feel free to make a pull request adding more lanugages here. For example, the Verilog support comes from doxygen-verilog.

exhale.utils.doxygenLanguageToPygmentsLexer(location, language)[source]

Given an input location and language specification, acquire the Pygments lexer to use for this file.

  1. If configs.lexerMapping has been specified, then configs._compiled_lexer_mapping will be queried first using the location parameter.

  2. If no matching was found, then the appropriate lexer defined in LANG_TO_LEX is used.

  3. If no matching language is found, "none" is returned (indicating to Pygments that no syntax highlighting should occur).


Sanitize the specified name for use with breathe directives.


name (str)

The name to be sanitized.



The input name sanitized to use with breathe directives (primarily for use with .. doxygenfunction::). Replacements such as "&lt;" -> "<" are performed, as well as removing spaces "< " -> "<" must be done. Breathe is particularly sensitive with respect to whitespace.


Convenience function to sanitize() all provided names.

names (list of str)

A list of strings to sanitize.

list of str

Each name in names sanitized: [sanitize(n) for n in names].

Template Parsing

exhale.utils.tokenize_template(node_name: str) list[typing.Union[list, str]][source]

Transform node_name into a list representing the templates.


This method may not support all C++ templates, it is only used in exhale to parse when templates occur in the doxygen name. This happens with template structs / classes and specializations.

In order to represent templates (and nested templates), any < template > is tokenized to create a nested list of template parameters (and remove the < and > characters). Some examples:

Input node_name

Returned Tokens





Depth 1

"foo< 12 >"

["foo", ["12"]]

"ns::foo< int, 66 >"

["ns::foo", ["int", "66"]]

Depth 2

"foo< std::array< int > >"

["foo", ["std::array", ["int"]]]

"bar< Cls< x, y, z > >"

["bar", ["Cls", ["x", "y", "z"]]]

Depth 3

"rawr< A< B< C > > >"

["rawr", ["A", ["B", ["C"]]]]

The function will transform any duplicate whitespace to a single space in the final output, as well as remove any leading or trailing whitespace for a given token. To transform back to a string, use join_template_tokens().


node_name (str)

The name of the node to tokenize. It is assumed that this is valid C++, if it is not the results are undefined.

exhale.utils.join_template_tokens(tokens: list[typing.Union[list, str]]) str[source]

Return a C++ type using the output from tokenize_template().


The original input to tokenize_template() and the return of this function are not guaranteed to be equivalent. Whitespace variations will occur.


tokens (list[Union[list, str]])

The tokens to re-join together as a C++ template.

exhale.utils._join_template_args(idx: int, item: Union[str, list[typing.Union[list, str]]], stream: TextIO)[source]

Internal helper function for join_template_tokens().

Recursively writes each item to stream in order, expanding the list to the original C++ template definition.


idx (int)

Recursive item depth level (not recursion call-stack depth). This is element index for when a parent calling function is iterating a list, when greater than 0 a , is needed to be inserted.

item (Union[str, list[Union[list, str]]])

The current item to write to stream. When a str, it is written directly. When a list, the item represents an inner template – < is written, followed by recursive joining of elements in the list, followed by >.

stream (TextIO)

The stream to write the results to.