API Reference

This page provides detailed API documentation for all functions and classes in snick.

snick

Conjoiner dataclass

Conjoins text parts into a single string.

This is most useful when building multi-line strings where you want to add parts as you go and then produce a final, joined string.

add

add(
    *parts: str,
    should_dedent: bool = True,
    blanks_between: int = 0,
    blanks_before: int = 0,
    blanks_after: int = 0,
) -> None

Add a new part(s) to the conjoiner.

Parameters:

• parts (str, default: () ) –

  One or more string parts to add.

• should_dedent (bool, default: True ) –

  If True, dedent each part before adding it. Defaults to True.

• blanks_between (int, default: 0 ) –

  Number of blanks to insert between each part for multiple parts. Defaults to 0.

• blanks_before (int, default: 0 ) –

  Number of blanks to insert before the first part. Defaults to 0.

• blanks_after (int, default: 0 ) –

  Number of blanks to insert after the last part. Defaults to 0.

add_blank

add_blank() -> None

Add a single blank to the conjoiner.

add_blanks

add_blanks(count: int) -> None

Add blanks to the conjoiner.

Parameters:

• count (int) –

  Number of blank lines to add.

extend

extend(
    parts: Iterable[str],
    should_dedent: bool = True,
    blanks_between: int = 0,
    blanks_before: int = 0,
    blanks_after: int = 0,
) -> None

Add new parts to the conjoiner.

This is just a convenience method that takes a list of parts instead of variadic arguments.

Parameters:

• parts (Iterable[str]) –

  One or more string parts to add.

• should_dedent (bool, default: True ) –

  If True, dedent each part before adding it. Defaults to True.

• blanks_between (int, default: 0 ) –

  Number of blanks to insert between each part for multiple parts. Defaults to 0.

• blanks_before (int, default: 0 ) –

  Number of blanks to insert before the first part. Defaults to 0.

• blanks_after (int, default: 0 ) –

  Number of blanks to insert after the last part. Defaults to 0.

conjoin

conjoin(*items: str, join_str: str = '\n') -> str

Join strings supplied as args.

Thinly wraps str.join() without having to pack strings in an iterable and with a default joining string.

Parameters:

• items (str, default: () ) –

  Positional arguments for strings that should be joined

• join_str (str, default: '\n' ) –

  The string used to join the strings. Defaults to newline character.

dedent

dedent(text: str, should_strip: bool = True) -> str

Dedent a paragraph after removing leading and trailing whitespace.

Parameters:

• text (str) –

  The text to dedent

• should_strip (bool, default: True ) –

  Strip leading whitespace. Useful if you you like the first line of triple-quoted text to start on the next line after the triple-quote. Defaults to True

dedent_all

dedent_all(
    *texts: str,
    should_strip: bool = True,
    join_str: str = "\n",
) -> str

Dedent each blob supplied as an argument and then joins them.

Parameters:

• texts (str, default: () ) –

  Positional text arguments to dedent and then join.

• should_strip (bool, default: True ) –

  Passed along to each call to dedent()

• join_str (str, default: '\n' ) –

  Passed along to the call to conjoin()

enboxify

enboxify(
    text: str,
    boxchar: str = "*",
    hspace: int = 1,
    vspace: int = 0,
    should_strip: bool = True,
) -> str

Draw a box around a block of text.

Parameters:

• text (str) –

  The text to enboxify

• boxchar (str, default: '*' ) –

  The text to use for drawing the box

• hspace (int, default: 1 ) –

  Horizontal padding around text and box

• vspace (int, default: 0 ) –

  Vertical padding around text and box

• should_strip (bool, default: True ) –

  Strip leading whitespace. Passed on to dedent()

indent

indent(
    text: str,
    prefix: str = "    ",
    skip_first_line: bool = False,
    **kwargs: Any,
) -> str

Wrap the textwrap.indent() method but include a default prefix.

Parameters:

• prefix (str, default: ' ' ) –

  The preix to pass to textwrap.indent(). Defaults to 4 spaces

• skip_first_line (bool, default: False ) –

  If True, the first line will not be indented. Defaults to False.

indent_wrap

indent_wrap(text: str, **kwargs: Any) -> str

Wrap a long string using textwrap args and indent all the lines using the same indent as the first line.

pretty_format

pretty_format(data: dict[Any, Any], indent: int = 2) -> str

Pretty-format a python data structure with trailing commas and clean indentation.

Parameters:

• data (dict[Any, Any]) –

  The data to pretty print.

• indent (int, default: 2 ) –

  The number of spaces per indentation level. Defaults to 2.

pretty_print

pretty_print(
    data: dict[Any, Any],
    indent: int = 2,
    stream: TextIO = sys.stdout,
)

Print to a stream (stdout by default) a data item using the pretty_format method.

Parameters:

• data (dict[Any, Any]) –

  The data to pretty print.

• indent (int, default: 2 ) –

  The number of spaces per indentation level. Defaults to 2.

• stream (TextIO, default: stdout ) –

  The stream to print to. Defaults to sys.stdout.

strip_ansi_escape_sequences

strip_ansi_escape_sequences(text: str) -> str

Strip all ansi escape sequences from a string.

To learn more about these sequences, see: https://jakob-bagterp.github.io/colorist-for-python/ansi-escape-codes/

strip_trailing_whitespace

strip_trailing_whitespace(text: str) -> str

Removes trailing whitespace on all lines of a multiline string.

strip_whitespace

strip_whitespace(text: str) -> str

Remove all whitespace from a string.

unwrap

unwrap(text: str, should_strip: bool = True) -> str

Convert a paragraph of (possibly) indented, wrapped text and unwrap it into a single line.

Parameters:

• text (str) –

  The text to unwrap

• should_strip (bool, default: True ) –

  If set to True, strip leading whitespace. Passed on to dedent().