Skip to content

API reference

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.

__iadd__ 
__iadd__(part: str) -> Conjoiner

Add a single part to the conjoiner using the += operator.

Parameters:

Name Type Description Default
part str

A string part to add.

 required

Returns:

Type Description
Conjoiner

This conjoiner instance.
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:

Name Type Description Default
parts str

One or more string parts to add.

 ()
should_dedent bool

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

 True
blanks_between int

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

 0
blanks_before int

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

 0
blanks_after int

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

 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:

Name Type Description Default
count int

Number of blank lines to add.

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

Name Type Description Default
parts Iterable[str]

One or more string parts to add.

 required
should_dedent bool

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

 True
blanks_between int

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

 0
blanks_before int

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

 0
blanks_after int

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

 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:

Name Type Description Default
items str

Positional arguments for strings that should be joined

 ()
join_str str

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

 '\n'

dedent 

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

Dedent a paragraph after removing leading and trailing whitespace.

Parameters:

Name Type Description Default
text str

The text to dedent

 required
should_strip bool

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

 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:

Name Type Description Default
texts str

Positional text arguments to dedent and then join.

 ()
should_strip bool

Passed along to each call to dedent()

 True
join_str str

Passed along to the call to conjoin()

 '\n'

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:

Name Type Description Default
text str

The text to enboxify

 required
boxchar str

The text to use for drawing the box

 '*'
hspace int

Horizontal padding around text and box

 1
vspace int

Vertical padding around text and box

 0
should_strip bool

Strip leading whitespace. Passed on to dedent()

 True

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:

Name Type Description Default
prefix str

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

 ' '
skip_first_line bool

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

 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:

Name Type Description Default
data dict[Any, Any]

The data to pretty print.

 required
indent int

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

 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:

Name Type Description Default
data dict[Any, Any]

The data to pretty print.

 required
indent int

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

 2
stream TextIO

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

 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, separator: str = ' ') -> str

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

Parameters:

Name Type Description Default
text str

The text to unwrap

 required
should_strip bool

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

 True
separator str

The separator to use when joining the lines. Defaults to a single space.

 ' '