Skip to content

Help messages¤

seali.Help ¤

Defines the message that appears when a command is ran with -h or --help.

__init__(help: str, style: seali.Style, arguments: dict[str, str], option_prompts: dict[str, str]) ¤

Arguments:

  • help: the documentation to appear when running with -h or --help.

    Use ANSI escape codes to create bold, colour, etc. If the string $USAGE, $POSITIONAL or $OPTIONS_AND_FLAGS appear then they will be replaced with autogenerated descriptions of how the program should be called.

    Text will flow like Markdown: spaces and newline are equivalent, and two adjacent newlines mark the start of a paragraph.

    Use a \v anywhere within a paragraph to create a hard line break, and up to one \f per paragraph to mark the indent which text should wrap to.

  • style: a seali.Style object describing how headings etc. should be formatted.

  • arguments: a dictionary, mapping argument name to the description that appears in the $POSITIONAL and $OPTIONS_AND_FLAGS substitutions. All positional arguments, options, and flags must be present.

  • option_prompts: a dictionary, mapping option name to prompt name. This is the 'foo' that appears in the -o, --output <foo> in the $OPTIONS_AND_FLAGS substitution.

seali.Style ¤

Defines the styles (what to bold, what to colour, etc.) within a help message.

This is a separate class to seali.Help to allow for manually calling its methods whilst constructing the help message, e.g. to insert a custom heading.

__init__(*, cmd: str | Callable[[str], str] = '', heading: str | Callable[[str], str] = '', positional: str | Callable[[str], str] = '', option_or_flag: str | Callable[[str], str] = '', indent: int = 2, width: int = 80) ¤

Most of the following arguments are prefixed to some part of the help message. This can be used either to add raw characters (e.g. use 'heading="# " to add a '#' before all headings) or to add ANSI escape codes (e.g. use heading=seali.BOLD to make all headings both) – or both (e.g. heading=seali.BOLD + "# ")!

Arguments:

  • cmd: prefix applied to, or function called on, the name of the command in the help message.
  • heading: prefix applied, or function called on, every heading in the help message.
  • positional: prefix applied, or function called on, every positional argument in the help message.
  • option_or_flag: prefix applied, or function called on, every option and flag in the help message.
  • indent: how much to automatically indent body text below headings.
  • width: at what width to wrap text.
cmd(x: str) -> str ¤

Format a string with the value provided to __init__(cmd=...)

heading(x: str) -> str ¤

Format a string with the value provided to __init__(heading=...)

positional(x: str) -> str ¤

Format a string with the value provided to __init__(positional=...)

option_or_flag(x: str) -> str ¤

Format a string with the value provided to __init__(option_or_flag=...)

Example

The following: 

import seali

style = seali.Style(
  cmd=seali.BOLD,
  heading=lambda x: seali.BOLD + x + ":",
  positional=seali.RED,
  option_or_flag=seali.RED,
  indent=2,
  width=80,
)

help = seali.Help(
  f"""
  Help message here. Text flows like Markdown: spaces
  and newlines are equivalent, and paragraphs reflow to the
  specified width.

  Paragraphs are separated by two newlines.

  Hard line breaks can be inserted with a backslash-v:\v
  This text will be in the same paragraph but on a new line.

  (a) \fa backslash-f can be used to insert up to one tabstop per
   line. So if the text here flows for a really really long time
   then that is fine, it will be indented to reflow after the
  '(a)' label.

  (b) \fwhich can be useful when building bulleted lists.

  The usage summary can be inserted with:

  $USAGE

  The list of all positional arguments, and their documentation,
  can be inserted with:

  $POSITIONAL

  The list of all options and flags, and their documentation,
  can be inserted with:

  $OPTIONS_AND_FLAGS

  Use ANSI escape codes to create bold, colour, etc:
  {seali.BOLD}{seali.RED}This text will be bold and in red{seali.RESET}
  """,
  style=style,
  arguments=dict(
      pos="Some position, this is its docstring, it goes on for a short while.",
      opt="Some option, this is its docstring, it goes on for a short while.",
      flag="Some flag, this is its docstring, it goes on for a short while.",
  ),
  option_prompts=dict(opt="foo"),
)

@seali.command(help=help)
def my_program(pos: str, /, *, opt: int, flag: bool = False): ...

if __name__ == "__main__":
    my_program()

produces:

Help message here. Text flows like Markdown: spaces and newlines are equivalent,
and paragraphs reflow to the specified width.

Paragraphs are separated by two newlines.

Hard line breaks can be inserted with a backslash-v:
This text will be in the same paragraph but on a new line.

(a) a backslash-f can be used to insert up to one tabstop per line. So if the
    text here flows for a really really long time then that is fine, it will be
    indented to reflow after the '(a)' label.

(b) which can be useful when building bulleted lists.

The usage summary can be inserted with:

Usage:

  my_program [POSITIONAL] [OPTIONS AND FLAGS]

The list of all positional arguments, and their documentation, can be inserted
with:

Positional:

  pos: Some position, this is its docstring, it goes on for a short while.

The list of all options and flags, and their documentation, can be inserted with:

Options and flags:

  -f, --flag: Some flag, this is its docstring, it goes on for a short while.

  -o, --opt <foo>: Some option, this is its docstring, it goes on for a short
    while.

Use ANSI escape codes to create bold, colour, etc: This text will be bold and in
red