snakeoil.formatters module

Classes wrapping a file-like object to do fancy output on it.

class snakeoil.formatters.Formatter

Bases: object

Abstract formatter base class.

The types of most of the instance attributes is undefined (depends on the implementation of the particular Formatter subclass).

Variables:

• bold – object to pass to write() to switch to bold mode.

• underline – object to pass to write() to switch to underlined mode.

• reset – object to pass to write() to turn off bold and underline.

• wrap – boolean indicating we auto-linewrap (defaults to off).

• autoline – boolean indicating we are in auto-newline mode (defaults to on).

bg(color: str | None = None) → str

Change background color.

Parameters:

color – color to change to. A default is used if omitted. if passed None, resets to the default color.

Returns:

object representing changing the background to the requested color, if possible for this formatter.

error(message: None | str | Callable[[Formatter], None])

Format a string as an error message.

fg(color: str | None = None) → str

Change foreground color.

Parameters:

color – color to change to. A default is used if omitted. if passed None, resets to the default color.

Returns:

object representing changing the foreground to the requested color, if possible for this formatter.

flush()

Flush the underlying stream buffer.

title(string: None | str | Callable[[Formatter], None])

Set the title to string

warn(message: None | str | Callable[[Formatter], None])

Format a string as a warning message.

write(*args: None | str | Callable[[Formatter], None], **kwargs)

Write something to the stream.

Acceptable arguments are:

• Strings are simply written to the stream.

• None is ignored.

• Functions are called with the formatter as argument. Their return value is then used the same way as the other arguments.

• Formatter subclasses might special-case certain objects.

Accepts wrap and autoline as keyword arguments. Effect is the same as setting them before the write call and resetting them afterwards.

Accepts first_prefixes and later_prefixes as keyword arguments. They should be sequences that are temporarily appended to the first_prefix and later_prefix attributes.

Accepts prefixes as a keyword argument. Effect is the same as setting first_prefixes and later_prefixes to the same value.

Accepts first_prefix, later_prefix and prefix as keyword argument. Effect is the same as setting first_prefixes, later_prefixes or prefixes to a one-element tuple.

The formatter has a couple of attributes that are useful as argument to write.

class snakeoil.formatters.PlainTextFormatter(stream: IO, width: int = 79, encoding: str | None = None)

Bases: Formatter

Formatter writing plain text to a file-like object.

Variables:

• width – contains the current maximum line length.

• encoding – the encoding unicode strings should be converted to.

• first_prefix – prefixes to output at the beginning of every write.

• later_prefix – prefixes to output on each line after the first of every write.

bg(color=None)

change bg color

Compatibility method- no coloring escapes are returned from it.

bold = ''

fg(color=None)

change fg color

Compatibility method- no coloring escapes are returned from it.

flush()

Flush the underlying stream buffer.

reset = ''

underline = ''

write(*args, **kwargs)

Write something to the stream.

Acceptable arguments are:

• Strings are simply written to the stream.

• None is ignored.

• Functions are called with the formatter as argument. Their return value is then used the same way as the other arguments.

• Formatter subclasses might special-case certain objects.

Accepts wrap and autoline as keyword arguments. Effect is the same as setting them before the write call and resetting them afterwards.

Accepts first_prefixes and later_prefixes as keyword arguments. They should be sequences that are temporarily appended to the first_prefix and later_prefix attributes.

Accepts prefixes as a keyword argument. Effect is the same as setting first_prefixes and later_prefixes to the same value.

Accepts first_prefix, later_prefix and prefix as keyword argument. Effect is the same as setting first_prefixes, later_prefixes or prefixes to a one-element tuple.

The formatter has a couple of attributes that are useful as argument to write.

snakeoil.formatters.decorate_forced_wrapping(setting=True)

Decorator to force a specific line wrapping state for the duration of invocation.

snakeoil.formatters.get_formatter(stream: IO, force_color: bool = False)

TerminfoFormatter if the stream is a tty, else PlainTextFormatter.