gluetool.help module

Command-line --help helpers (muhaha!).

gluetool uses docstrings to generate help for command-line options, modules, shared functions and other stuff. To generate good looking and useful help texts a bit of work is required. Add the Sphinx which we use to generate nice documentation of gluetool‘s API and structures, with its directives, and it’s even more work to make readable output. Therefore these helpers, separated in their own file to keep things clean.

gluetool.help.C_ARGNAME(text)

gluetool.help.C_FUNCNAME(text)

gluetool.help.C_LITERAL(text)

class gluetool.help.DummyTextBuilder

Sphinx TextWriter (and other writers as well) requires an instance of Builder class that brings configuration into the rendering process. The original TextBuilder requires Sphinx application which brings a lot of other dependencies (e.g. source paths and similar stuff) which are impractical in our use case (“render short string to plain text”). Therefore this dummy class which just provides minimal configuration - TextWriter requires nothing else from Builder instance.

See sphinx/writers/text.py for the original implementation.

class DummyConfig

text_newlines = '\n'

text_sectionchars = '*=-~"+`'

DummyTextBuilder.config

alias of DummyConfig

DummyTextBuilder.translator_class = None

class gluetool.help.LineWrapRawTextHelpFormatter(*args, **kwargs)

Bases: argparse.RawDescriptionHelpFormatter

_split_lines(text, width)

class gluetool.help.TextTranslator(document, builder)

Bases: sphinx.writers.text.TextTranslator

depart_field_name(node)

depart_literal(node)

visit_field_name(node)

visit_literal(node)

gluetool.help.doc_role_handler(role, rawtext, text, lineno, inliner, options=None, context=None)

Format :doc: roles, used to reference another bits of documentation.

gluetool.help.docstring_to_help(docstring, width=None, line_prefix=' ')

Given docstring, process and render it as a plain text. This conversion function is used to generate nice and readable help strings used when printing help on command line.

Parameters:

• docstring (str) – raw docstring of Python object (function, method, module, etc.).
• width (int) – Maximal line width allowed.
• line_prefix (str) – prefix each line with this string (e.g. to indent it with few spaces or tabs).

Returns:

formatted docstring.

gluetool.help.eval_context_help(source)

Generate and format help for an evaluation context of a module. Looks for context content, and gives it a nice header, suitable for command-line help, applying formatting along the way.

Parameters:source (gluetool.glue.Configurable) – object whose eval context help we should format. Returns:Formatted help.

gluetool.help.extract_eval_context_info(source, logger=None)

Extract information of evaluation context content from the source - a module or any other object with eval_context property. The information we’re looking for is represented by an assignment to special variable, __content__, in the body of eval_context getter. __content__ is expected to be assigned a dictionary, listing context variables (keys) and their descriptions (values).

If it’s not possible to find such information, or an exception is raised, the function returns an empty dictionary.

Parameters:source (gluetool.glue.Configurable) – object to extract information from. Return type:dict(str, str)

gluetool.help.function_help(func, name=None)

Uses function’s signature and docstring to generate a plain text help describing the function.

Parameters:

• func (callable) – Function to generate help for.
• name (str) – If not set, func.__name__ is used by default.

Returns:

(signature, body) pair.

gluetool.help.functions_help(functions)

Generate help for a set of functions.

Parameters:callable) functions (list(str,) – Functions to generate help for, passed as name and the corresponding callable pairs. Return type:str Returns:Formatted help.

gluetool.help.option_help(txt)

Given option help text, format it to be more suitable for command-line help. Options can provide a single line of text, or mutiple lines (using triple quotes and docstring-like indentation).

Parameters:txt (str) – Raw option help text. Returns:Formatted option help text.

gluetool.help.py_default_role(role, rawtext, text, lineno, inliner, options=None, content=None)

Default handler we use for py:... roles, translates text to literal node.

gluetool.help.rst_to_text(text)

Render given text, written with RST, as plain text.

Parameters:text (str) – string to render. Return type:str Returns:plain text representation of text.

gluetool.help.trim_docstring(docstring)

Quoting PEP 257 <https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation>:

Docstring processing tools will strip a uniform amount of indentation from the second and further lines of the docstring, equal to the minimum indentation of all non-blank lines after the first line. Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained. Blank lines should be removed from the beginning and end of the docstring.

Code bellow follows the quote.

This method does exactly that, therefore we can keep properly aligned docstrings while still use them for reasonably formatted help texts.

Parameters:docstring (str) – raw docstring. Return type:str Returns:docstring with lines stripped of leading whitespace.