Formatting Help

The way the Base classes format help is determined by a help formatter class. By changing a base’s help_formatter attribute, you can make it display help in a different way.

The Base Formatter

All help formatters should subclass from BaseHelpFormatter.

class clap.help.BaseHelpFormatter(stream=None, width=None)

HelpFormatters are constructed with a stream. They should format the help when certain methods are called. Note that BaseHelpFormatter itself does not implement these methods, but HelpFormatter does.

usage()

Called with one string argument, the usage string. It should print it.

text()

Again, called with one argument, a paragraph of text. It should word-wrap the given text and print it.

cmd_list()

This is called with a list/tuple of tuples in the form (name, description). It should print them out, in order.

option_list()

This is called with an iterable of clap.parser.Option instances. It should print them out, again, in order.

start_section()

This is called with a section title. This should print a header for that section, then set up for any indentation that needs to be done.

Parameters:

• stream – The stream to print to. It defaults to sys.stdout.
• width – The width of the screen. It will default to the value of the environment variable COLUMNS.

dedent()

This will decrease the current indentation level by indent_by spaces.

Raises:RuntimeError if you try to dedent past 0.

ewidth

A property for the screen width minus the current indentation level.

indent()

This will increase the current indentation level by indent_by spaces. Any calls to write() will be prepended by that much indentation.

indent_by

The amount each call to indent() will indent by.

indentation

A property that returns indent number of spaces.

write(data='', newline=True, indent=True)

This writes the given data to the stream. Under normal circumstances, the data printed will be indented to the current indentation level.

Parameters:

• data – The data to write.
• newline – Whether to add a newline to the end. (The default is True.)
• indent – Whether to indent the line. (The default is True.)

Included Formatters

The HelpFormatter class has some sensible defaults for formatting help. It’s not the nicest looking help ever, but it works. If you want indented sections, you can use the IndentedHelpFormatter class. The ANSIHelpFormatter uses ANSI boldface effects on section titles and usage strings.

Of course, you can always implement your own help formatters.