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

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(*args, **kwargs)

Bases: Writer

__init__(*args, **kwargs)

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() → None

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

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

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.