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. Read it through get_default_printer() rather than importing the name, because set_default_printer() replaces it.

Type:: Printer

graphtage.printer.NULL_PRINTER

A Printer instance that discards everything written to it.

Type:: Printer

printer classes

ANSIContext

class graphtage.printer.ANSIContext(stream: RawWriter | ANSIContext, fore: AnsiFore | None = None, back: AnsiBack | None = None, style: AnsiStyle | None = None)

Bases: object

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

__init__(stream: RawWriter | ANSIContext, fore: AnsiFore | None = None, back: AnsiBack | None = None, style: AnsiStyle | None = 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: AnsiBack | None: The computed background color of this context.

background(bg_color: AnsiBack) → ANSIContext: Returns a new context with the given background color.

bright() → ANSIContext: Returns a new context with the bright style enabled.

color(foreground_color: AnsiFore) → ANSIContext: Returns a new context with the given foreground color.

dim() → ANSIContext: Returns a new context with the dim style enabled.

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

property fore: AnsiFore | None: 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: ANSIContext | None: This context’s parent context.

property root: The root context.

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

property style: AnsiStyle | None: The computed style of this context.

CombiningMarkContext

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

Bases: object

A context returned by CombiningMarkWriter.context().

__init__(writer: CombiningMarkWriter, *combining_marks: str)

CombiningMarkWriter

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

Bases: RawWriter

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

__init__(parent: 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) → 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: 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: RawWriter | ANSIContext, fore: AnsiFore | None = None, back: AnsiBack | None = None, style: AnsiStyle | None = None)

Bases: ANSIContext

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

__init__(stream: RawWriter | ANSIContext, fore: AnsiFore | None = None, back: AnsiBack | None = None, style: AnsiStyle | None = 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: AnsiBack | None: The computed background color of this context.

background(bg_color: AnsiBack) → ANSIContext: Returns a new context with the given background color.

bright() → ANSIContext: Returns a new context with the bright style enabled.

color(foreground_color: AnsiFore) → ANSIContext: Returns a new context with the given foreground color.

dim() → ANSIContext: Returns a new context with the dim style enabled.

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

property fore: AnsiFore | None: The computed foreground color of this context.

static get_back(color: AnsiBack) → str

static get_fore(color: AnsiFore) → str

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

property parent: ANSIContext | None: This context’s parent context.

property root: The root context.

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

stream: RawWriter

property style: AnsiStyle | None: The computed style of this context.

HTMLPrinter

class graphtage.printer.HTMLPrinter(*args, title: str | None = None, **kwargs)

Bases: Printer

A Printer that outputs in HTML.

__init__(*args, title: str | None = 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: AnsiBack) → ANSIContext: Returns a new context for this printer with the given background color.

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

close()

property closed: bool

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

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

dim() → 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) → HTMLPrinter: A convenience function for printing an element.

indent() → 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[AnyStr]

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: Returns a tqdm.tqdm object.

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

truncate(size: int | None = 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: Printer)

Bases: object

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

__init__(printer: Printer)

NullWriter

class graphtage.printer.NullWriter

Bases: Writer

__init__()

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

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

write(s: str) → int

Writes a given string.

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

Printer

class graphtage.printer.Printer(out_stream: Writer | None = None, ansi_color: bool | None = None, quiet: bool = False, options: dict[str, Any] | None = None)

Bases: StatusWriter, RawWriter

An ANSI color and status printer.

__init__(out_stream: Writer | None = None, ansi_color: bool | None = None, quiet: bool = False, options: dict[str, Any] | None = 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: AnsiBack) → ANSIContext: Returns a new context for this printer with the given background color.

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

close()

property closed: bool

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

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

dim() → 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() → 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[AnyStr]

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

seekable() → bool

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

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

tell() → int

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

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

truncate(size: int | None = 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: Writer, Protocol

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

__init__(*args, **kwargs)

abstractmethod flush() → Any: Flushes any buffered bytes, if necessary.

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

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

abstractmethod 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)

abstractmethod flush() → Any: Flushes any buffered bytes, if necessary.

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

abstractmethod 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

enable_ansi_support

graphtage.printer.enable_ansi_support(force_color: bool = False)

Prepares sys.stdout and sys.stderr to receive ANSI escape sequences.

On a legacy Windows console, colorama replaces both streams with wrappers that translate the escape sequences into Win32 console calls. A Printer captures its output stream when it is constructed, so call this function first; a printer constructed beforehand writes past the wrapper and its color is lost.

This function mutates global state, so call it from an application entry point rather than from library code.

Parameters:: force_color – If True, keep the escape sequences even when the output stream is not a terminal. colorama strips them in that case by default, which would discard color that the user explicitly requested.

get_default_printer

graphtage.printer.get_default_printer() → Printer

Returns the printer that library code uses when the caller does not supply one.

Call this instead of importing DEFAULT_PRINTER by name. set_default_printer() rebinds the module attribute, which a name bound by from .printer import DEFAULT_PRINTER never observes: such a name keeps referring to the printer that was current when the importing module was first loaded.

Returns:: The printer most recently passed to set_default_printer(), or DEFAULT_PRINTER if that function was never called.
Return type:: Printer

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.

set_default_printer

graphtage.printer.set_default_printer(printer: Printer)

Installs printer as the printer returned by get_default_printer().

This mutates global state, so call it from an application entry point rather than from library code.

Parameters:: printer – The printer to install.