graphtage.printer

A module for abstracting printing.

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

  1. to globally toggle ANSI color output without having to implement that logic in every print function;

  2. to provide an API for automatically handling indentation and pretty-printing;

  3. to handle concurrency when using a status printer like tqdm; and

  4. 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, 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, 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

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

Returns the ANSI end code for this context.

property fore

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

This context’s parent context.

property root

The root context.

property start_code

Returns the ANSI start code for this context.

property style

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)

Initialize self. See help(type(self)) for accurate signature.

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

Returns the set of combining marks in this writer.

property marks_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: Union[graphtage.printer.RawWriter, 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, 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

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

Returns the ANSI end code for this context.

property fore

The computed foreground color of this context.

static get_back(color: colorama.ansi.AnsiBack)str
static get_fore(color: colorama.ansi.AnsiFore)str
property parent

This context’s parent context.

property root

The root context.

property start_code

Returns the ANSI start code for this context.

property style

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

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
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.

isatty()bool

Returns whether this writer is a TTY.

property mode
property name
newline()
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
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

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)

Initialize self. See help(type(self)) for accurate signature.

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

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
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
property name
newline()
out_stream: CombiningMarkWriter

The stream wrapped by this printer.

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

writelines(lines: Iterable)None

RawWriter

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

Bases: graphtage.printer.Writer, typing.Protocol

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

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

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: typing.Protocol

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

__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

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.