graphtage.printer¶

A module for abstracting printing.

There are several reasons for using this abstraction when printing in Graphtage:

to globally toggle ANSI color output without having to implement that logic in every print function;
to provide an API for automatically handling indentation and pretty-printing;
to handle concurrency when using a status printer like tqdm; and
to permit extensibility (e.g., the HTMLPrinter extends Printer to output in HTML rather than to the command line).

graphtage.printer.DEFAULT_PRINTER¶

A default Printer instance printing to sys.stdout.

Type: Printer

printer classes¶

ANSIContext¶

class graphtage.printer.ANSIContext(stream: Union[graphtage.printer.RawWriter, graphtage.printer.ANSIContext], fore: Optional[colorama.ansi.AnsiFore] = None, back: Optional[colorama.ansi.AnsiBack] = None, style: Optional[colorama.ansi.AnsiStyle] = None)¶

Bases: object

A context for printing to the terminal with ANSI color escapes.

__init__(stream: Union[graphtage.printer.RawWriter, graphtage.printer.ANSIContext], fore: Optional[colorama.ansi.AnsiFore] = None, back: Optional[colorama.ansi.AnsiBack] = None, style: Optional[colorama.ansi.AnsiStyle] = None)¶

Initializes a context.

Parameters

stream – The writer or parent context that this context will wrap.
fore – An optional foreground color.
back – An optional background color.
style – An optional style.

If any of the color or style options are omitted, they will default to the parent context’s options.

property back: Optional[colorama.ansi.AnsiBack]¶: The computed background color of this context.

background(bg_color: colorama.ansi.AnsiBack) → graphtage.printer.ANSIContext¶: Returns a new context with the given background color.

bright() → graphtage.printer.ANSIContext¶: Returns a new context with the bright style enabled.

color(foreground_color: colorama.ansi.AnsiFore) → graphtage.printer.ANSIContext¶: Returns a new context with the given foreground color.

dim() → graphtage.printer.ANSIContext¶: Returns a new context with the dim style enabled.

property end_code: str¶: Returns the ANSI end code for this context.

property fore: Optional[colorama.ansi.AnsiFore]¶: The computed foreground color of this context.

is_applied: bool¶: Keeps track of whether this context’s options have already been applied to the underlying stream.

property parent: Optional[graphtage.printer.ANSIContext]¶: This context’s parent context.

property root¶: The root context.

property start_code: str¶: Returns the ANSI start code for this context.

property style: Optional[colorama.ansi.AnsiStyle]¶: The computed style of this context.

CombiningMarkContext¶

class graphtage.printer.CombiningMarkContext(writer: graphtage.printer.CombiningMarkWriter, *combining_marks: str)¶

Bases: object

A context returned by CombiningMarkWriter.context().

__init__(writer: graphtage.printer.CombiningMarkWriter, *combining_marks: str)¶

CombiningMarkWriter¶

class graphtage.printer.CombiningMarkWriter(parent: graphtage.printer.RawWriter)¶

Bases: graphtage.printer.RawWriter

A writer that automatically adds combining marks to the bytes that are written.

__init__(parent: graphtage.printer.RawWriter)¶

Initializes the writer.

Parameters: parent – The parent writer to wrap.

add(combining_mark: str)¶: Adds a combining mark to this writer.

context(*combining_marks: str) → graphtage.printer.CombiningMarkContext¶: Returns an __enter__ -able context for interacting with this writer, with the given combining marks.

enabled: bool¶: Whether or not combining marks will be added.

flush()¶: Flushes any buffered bytes, if necessary.

isatty() → bool¶: Returns whether this writer is a TTY.

property marks: Set[str]¶: Returns the set of combining marks in this writer.

property marks_str: str¶: Returns a string representation of this writer’s combining marks.

parent: graphtage.printer.RawWriter¶: This writer’s parent.

raw_write(s: str) → int¶: Writes the string to the underlying stream without any modifications.

remove(combining_mark: str)¶: Removes a combining mark from this writer.

write(s: str) → int¶

Writes a string to self.parent.

If self.enabled, self.marks_str will be appended to each character in s.

Parameters: s – The string to write.
Returns: The number of bytes written.
Return type: int

HTMLANSIContext¶

class graphtage.printer.HTMLANSIContext(stream: Union[graphtage.printer.RawWriter, graphtage.printer.ANSIContext], fore: Optional[colorama.ansi.AnsiFore] = None, back: Optional[colorama.ansi.AnsiBack] = None, style: Optional[colorama.ansi.AnsiStyle] = None)¶

Bases: graphtage.printer.ANSIContext

A context that sets HTML colors instead of ANSI terminal escapes.

__init__(stream: Union[graphtage.printer.RawWriter, graphtage.printer.ANSIContext], fore: Optional[colorama.ansi.AnsiFore] = None, back: Optional[colorama.ansi.AnsiBack] = None, style: Optional[colorama.ansi.AnsiStyle] = None)¶

Initializes a context.

Parameters

stream – The writer or parent context that this context will wrap.
fore – An optional foreground color.
back – An optional background color.
style – An optional style.

If any of the color or style options are omitted, they will default to the parent context’s options.

property back: Optional[colorama.ansi.AnsiBack]¶: The computed background color of this context.

background(bg_color: colorama.ansi.AnsiBack) → graphtage.printer.ANSIContext¶: Returns a new context with the given background color.

bright() → graphtage.printer.ANSIContext¶: Returns a new context with the bright style enabled.

color(foreground_color: colorama.ansi.AnsiFore) → graphtage.printer.ANSIContext¶: Returns a new context with the given foreground color.

dim() → graphtage.printer.ANSIContext¶: Returns a new context with the dim style enabled.

property end_code: str¶: Returns the ANSI end code for this context.

property fore: Optional[colorama.ansi.AnsiFore]¶: The computed foreground color of this context.

static get_back(color: colorama.ansi.AnsiBack) → str¶

static get_fore(color: colorama.ansi.AnsiFore) → str¶

is_applied: bool¶: Keeps track of whether this context’s options have already been applied to the underlying stream.

property parent: Optional[graphtage.printer.ANSIContext]¶: This context’s parent context.

property root¶: The root context.

property start_code: str¶: Returns the ANSI start code for this context.

stream: graphtage.printer.RawWriter¶

property style: Optional[colorama.ansi.AnsiStyle]¶: The computed style of this context.

HTMLPrinter¶

class graphtage.printer.HTMLPrinter(*args, title: Optional[str] = None, **kwargs)¶

Bases: graphtage.printer.Printer

A Printer that outputs in HTML.

__init__(*args, title: Optional[str] = None, **kwargs)¶

Initializes a Printer.

Parameters

out_stream – The stream to which to print. If omitted, it defaults to sys.stdout.
ansi_color – Whether or not color should be enabled in the output. If omitted, it defaults to out_stream.isatty.
quiet – If True, progress and status messages will be suppressed.
options – An optional dict, the keys of which will be set as attributes of this class. This is used to provide additional formatting options to functions that use this printer.

property ansi_color: bool¶: Returns whether this printer has color enabled.

background(bg_color: colorama.ansi.AnsiBack) → graphtage.printer.ANSIContext¶: Returns a new context for this printer with the given background color.

bright() → graphtage.printer.ANSIContext¶: Returns a new context for this printer with the bright style enabled.

close()¶

property closed: bool¶

color(foreground_color: colorama.ansi.AnsiFore) → graphtage.printer.ANSIContext¶: Returns a new context for this printer with the given foreground color.

context() → graphtage.printer.ANSIContext¶: Returns the context for this printer.

dim() → graphtage.printer.ANSIContext¶: Returns a new context for this printer with the dim style enabled.

fileno() → int¶

flush(final=False)¶

Flushes this writer.

If final is True, any extra bytes will be flushed along with a final newline.

html_element(element_name, inline=False, **kwargs) → graphtage.printer.HTMLPrinter¶: A convenience function for printing an element.

indent() → graphtage.printer.Printer¶: Returns a new context that is indented one step.

indent_str: str¶: The string used for each indent step (default is four spaces).

indents: int¶: The number of indent steps.

isatty() → bool¶: Returns whether this writer is a TTY.

property mode: str¶

property name: str¶

newline()¶

out_stream: CombiningMarkWriter¶: The stream wrapped by this printer.

quiet¶: Whether or not tqdm status messages and progress should be suppressed.

raw_write(s: str) → int¶: Writes the string to the underlying stream without any modifications.

read(n: int = Ellipsis) → AnyStr¶

readable() → bool¶

readline(limit: int = Ellipsis) → AnyStr¶

readlines(hint: int = Ellipsis) → List¶

seek(offset: int, whence: int = Ellipsis) → int¶

seekable() → bool¶

status_stream: TextIO¶: The status stream to which to print.

strike()¶: Returns a new context for this printer where printed strings will be striked out.

tell() → int¶

tqdm(*args, **kwargs) → tqdm.std.tqdm¶: Returns a tqdm.tqdm object.

trange(*args, **kwargs) → tqdm.std.trange¶: Returns a tqdm.trange object.

truncate(size: Optional[int] = Ellipsis) → int¶

under_plus()¶: Returns a new context for this printer where printed strings will have a plus underneath.

writable() → bool¶

write(s: str) → int¶

Writes a given string.

Parameters: s – The string to write.
Returns: The number of bytes written.
Return type: int

write_raw¶

If True, this writer will not buffer output and use tqdm.write().

This defaults to:

self.write_raw = self.quiet or (
    out_stream.fileno() != sys.stderr.fileno() and out_stream.fileno() != sys.stdout.fileno()
)

writelines(lines: Iterable) → None¶

NullANSIContext¶

class graphtage.printer.NullANSIContext(printer: graphtage.printer.Printer)¶

Bases: object

A “fake” ANSIContext that has the same functions but does not actually emit any colors.

__init__(printer: graphtage.printer.Printer)¶

Printer¶

class graphtage.printer.Printer(out_stream: Optional[graphtage.printer.Writer] = None, ansi_color: Optional[bool] = None, quiet: bool = False, options: Optional[Dict[str, Any]] = None)¶

Bases: graphtage.progress.StatusWriter, graphtage.printer.RawWriter

An ANSI color and status printer.

__init__(out_stream: Optional[graphtage.printer.Writer] = None, ansi_color: Optional[bool] = None, quiet: bool = False, options: Optional[Dict[str, Any]] = None)¶

Initializes a Printer.

Parameters

out_stream – The stream to which to print. If omitted, it defaults to sys.stdout.
ansi_color – Whether or not color should be enabled in the output. If omitted, it defaults to out_stream.isatty.
quiet – If True, progress and status messages will be suppressed.
options – An optional dict, the keys of which will be set as attributes of this class. This is used to provide additional formatting options to functions that use this printer.

property ansi_color: bool¶: Returns whether this printer has color enabled.

background(bg_color: colorama.ansi.AnsiBack) → graphtage.printer.ANSIContext¶: Returns a new context for this printer with the given background color.

bright() → graphtage.printer.ANSIContext¶: Returns a new context for this printer with the bright style enabled.

close() → None¶

property closed: bool¶

color(foreground_color: colorama.ansi.AnsiFore) → graphtage.printer.ANSIContext¶: Returns a new context for this printer with the given foreground color.

context() → graphtage.printer.ANSIContext¶: Returns the context for this printer.

dim() → graphtage.printer.ANSIContext¶: Returns a new context for this printer with the dim style enabled.

fileno() → int¶

flush(final=False)¶

Flushes this writer.

If final is True, any extra bytes will be flushed along with a final newline.

indent() → graphtage.printer.Printer¶: Returns a new context that is indented one step.

indent_str: str¶: The string used for each indent step (default is four spaces).

indents: int¶: The number of indent steps.

isatty() → bool¶: Returns whether this writer is a TTY.

property mode: str¶

property name: str¶

newline()¶

out_stream: CombiningMarkWriter¶: The stream wrapped by this printer.

quiet¶: Whether or not tqdm status messages and progress should be suppressed.

raw_write(s: str) → int¶: Writes the string to the underlying stream without any modifications.

read(n: int = Ellipsis) → AnyStr¶

readable() → bool¶

readline(limit: int = Ellipsis) → AnyStr¶

readlines(hint: int = Ellipsis) → List¶

seek(offset: int, whence: int = Ellipsis) → int¶

seekable() → bool¶

status_stream: TextIO¶: The status stream to which to print.

strike() → graphtage.printer.CombiningMarkContext¶: Returns a new context for this printer where printed strings will be striked out.

tell() → int¶

tqdm(*args, **kwargs) → tqdm.std.tqdm¶: Returns a tqdm.tqdm object.

trange(*args, **kwargs) → tqdm.std.trange¶: Returns a tqdm.trange object.

truncate(size: Optional[int] = Ellipsis) → int¶

under_plus()¶: Returns a new context for this printer where printed strings will have a plus underneath.

writable() → bool¶

write(s: str) → int¶

Writes a given string.

Parameters: s – The string to write.
Returns: The number of bytes written.
Return type: int

write_raw¶

If True, this writer will not buffer output and use tqdm.write().

This defaults to:

self.write_raw = self.quiet or (
    out_stream.fileno() != sys.stderr.fileno() and out_stream.fileno() != sys.stdout.fileno()
)

writelines(lines: Iterable) → None¶

RawWriter¶

class graphtage.printer.RawWriter(*args, **kwargs)¶

Bases: graphtage.printer.Writer, Protocol

A writer that provides a pass-through for printing bytes to the underlying stream without modification.

__init__(*args, **kwargs)¶

abstract flush() → Any¶: Flushes any buffered bytes, if necessary.

abstract isatty() → bool¶: Returns whether this writer is a TTY.

abstract raw_write(s: str) → int¶: Writes the string to the underlying stream without any modifications.

abstract write(s: str) → int¶

Writes a given string.

Parameters: s – The string to write.
Returns: The number of bytes written.
Return type: int

Writer¶

class graphtage.printer.Writer(*args, **kwargs)¶

Bases: Protocol

A protocol for basic IO writers that is a subset of typing.IO.

__init__(*args, **kwargs)¶

abstract flush() → Any¶: Flushes any buffered bytes, if necessary.

abstract isatty() → bool¶: Returns whether this writer is a TTY.

abstract write(s: str) → int¶

Writes a given string.

Parameters: s – The string to write.
Returns: The number of bytes written.
Return type: int

printer functions¶

only_ansi¶

graphtage.printer.only_ansi(func)¶

A decorator for Printer methods that specifies it should only be called when outputting in color.

If the Printer implementing the decorated method has Printer.ansi_color set to False, then this decorator will have the method automatically return a NullANSIContext.