stringlist

A list of strings that represent lines in a multiline string.

Changed in version 1.0.0: String should now be imported from domdf_python_tools.typing.

Classes:

DelimitedList([iterable])	Subclass of list that supports custom delimiters in format strings.
Indent([size, type])	Represents an indent, having a symbol/type and a size.
StringList([iterable, convert_indents])	A list of strings that represent lines in a multiline string.

Data:

_SL	Invariant TypeVar bound to domdf_python_tools.stringlist.StringList.

Functions:

joinlines(lines)	Given a list of two-element tuples, each containing a line and a newline character (or empty string), return a single string.
splitlines(string)	Split string into a list of two-element tuples, containing the line content and the newline character(s), if any.

class DelimitedList(iterable=(), /)

Bases: List[~_S]

Subclass of list that supports custom delimiters in format strings.

Example:

>>> l = DelimitedList([1, 2, 3, 4, 5])
>>> format(l, ", ")
'1, 2, 3, 4, 5'
>>> f"Numbers: {l:, }"
'Numbers: 1, 2, 3, 4, 5'

New in version 1.1.0.

__format__(format_spec)

Default object formatter.

Return type

str

class Indent(size=0, type='\t')

Bases: object

Represents an indent, having a symbol/type and a size.

Parameters

• size (int) – The indent size. Default 0.

• type (str) – The indent character. Default '\t'.

Methods:

__eq__(other)	Return self == other.
__iter__()	Returns the size and type of the Indent.
__repr__()	Returns the string representation of the Indent.
__str__()	Returns the Indent as a string.

Attributes:

size	The indent size.
type	The indent character.

__eq__(other)

Return self == other.

Return type

bool

__iter__()

Returns the size and type of the Indent.

Return type

Iterator[Union[str, Any]]

__repr__()

Returns the string representation of the Indent.

Return type

str

__str__()

Returns the Indent as a string.

Return type

str

property size

The indent size.

Return type

int

property type

The indent character.

Return type

str

class StringList(iterable=(), convert_indents=False)

Bases: List[str]

A list of strings that represent lines in a multiline string.

Parameters

• iterable (Iterable[String]) – Content to populate the StringList with. Default ().

• convert_indents (bool) – Whether indents at the start of lines should be converted. Default False.

Methods:

__bytes__()	Returns the StringList as bytes.
__eq__(other)	Returns whether the other object is equal to this StringList.
__getitem__(index)	Returns the line with the given index.
__setitem__(index, line)	Replaces the given line with new content.
__str__()	Returns the StringList as a string.
append(line)	Append a line to the end of the StringList.
blankline([ensure_single])	Append a blank line to the end of the StringList.
copy()	Returns a shallow copy of the StringList.
count_blanklines()	Returns a count of the blank lines in the StringList.
extend(iterable)	Extend the StringList with lines from iterable.
insert(index, line)	Insert a line into the StringList at the given position.
set_indent(indent[, size])	Sets the indent to insert at the beginning of new lines.
set_indent_size([size])	Sets the size of the indent to insert at the beginning of new lines.
set_indent_type([indent_type])	Sets the type of the indent to insert at the beginning of new lines.
splitlines([keepends])	Analagous to str.splitlines().
with_indent(indent[, size])	Context manager to temporarily use a different indent.
with_indent_size([size])	Context manager to temporarily use a different indent size.
with_indent_type([indent_type])	Context manager to temporarily use a different indent type.

Attributes:

convert_indents	Whether indents at the start of lines should be converted.
indent	The indent to insert at the beginning of new lines.
indent_size	The current indent size.
indent_type	The current indent type.

__bytes__()

Returns the StringList as bytes.

New in version 2.1.0.

Return type

bytes

__eq__(other)

Returns whether the other object is equal to this StringList.

Return type

bool

__getitem__(index)

Returns the line with the given index.

Parameters

index (Union[SupportsIndex, slice])

Return type

Union[str, StringList]

Overloads

• __getitem__(index: SupportsIndex) -> str

• __getitem__(index: slice) -> ~_SL

Changed in version 1.8.0: Now returns a StringList when index is a slice.

Changed in version 3.2.0: Changed int in the type annotation to SupportsIndex.

__setitem__(index, line)

Replaces the given line with new content.

If the new content consists of multiple lines subsequent content in the StringList will be shifted down.

Parameters

• index (Union[SupportsIndex, slice])

• line (Union[String, Iterable[String]])

Changed in version 3.2.0: Changed int in the type annotation to SupportsIndex.

Overloads

• __setitem__(index: SupportsIndex, line: String) -> None

• __setitem__(index: slice, line: Iterable[String] ) -> None

__str__()

Returns the StringList as a string.

Return type

str

append(line)

Append a line to the end of the StringList.

Parameters

line (String)

blankline(ensure_single=False)

Append a blank line to the end of the StringList.

Parameters

ensure_single (bool) – Ensure only a single blank line exists after the previous line of text. Default False.

convert_indents

Type:    bool

Whether indents at the start of lines should be converted.

Only applies to lines added after this is enabled/disabled.

Can only be used when the indent is '\t' or '␣'.

copy()

Returns a shallow copy of the StringList.

Equivalent to a[:].

Return type

StringList

count_blanklines()

Returns a count of the blank lines in the StringList.

New in version 0.7.1.

Return type

int

extend(iterable)

Extend the StringList with lines from iterable.

Parameters

iterable (Iterable[String]) – An iterable of string-like objects to add to the end of the StringList.

indent

Type:    Indent

The indent to insert at the beginning of new lines.

property indent_size

The current indent size.

Return type

int

property indent_type

The current indent type.

Return type

str

insert(index, line)

Insert a line into the StringList at the given position.

Parameters

• index (SupportsIndex)

• line (String)

Changed in version 3.2.0: Changed int in the type annotation to SupportsIndex.

set_indent(indent, size=0)

Sets the indent to insert at the beginning of new lines.

Parameters

• indent (Union[String, Indent]) – The Indent to use for new lines, or the indent type.

• size (int) – If indent is an indent type, the indent size to use for new lines. Default 0.

set_indent_size(size=0)

Sets the size of the indent to insert at the beginning of new lines.

Parameters

size (int) – The indent size to use for new lines. Default 0.

set_indent_type(indent_type='\t')

Sets the type of the indent to insert at the beginning of new lines.

Parameters

indent_type (str) – The type of indent to use for new lines. Default '\t'.

splitlines(keepends=False)

Analagous to str.splitlines().

New in version 3.8.0.

Return type

List[str]

with_indent(indent, size=0)

Context manager to temporarily use a different indent.

>>> sl = StringList()
>>> with sl.with_indent("    ", 1):
...     sl.append("Hello World")

Parameters

• indent (Union[String, Indent]) – The Indent to use within the with block, or the indent type.

• size (int) – If indent is an indent type, the indent size to use within the with block. Default 0.

with_indent_size(size=0)

Context manager to temporarily use a different indent size.

>>> sl = StringList()
>>> with sl.with_indent_size(1):
...     sl.append("Hello World")

Parameters

size (int) – The indent size to use within the with block. Default 0.

with_indent_type(indent_type='\t')

Context manager to temporarily use a different indent type.

>>> sl = StringList()
>>> with sl.with_indent_type("    "):
...     sl.append("Hello World")

Parameters

indent_type (str) – The type of indent to use within the with block. Default '\t'.

splitlines(string)

Split string into a list of two-element tuples, containing the line content and the newline character(s), if any.

New in version 3.2.0.

Parameters

string (str)

Return type

List[Tuple[str, str]]

See also

str.splitlines() and joinlines()

joinlines(lines)

Given a list of two-element tuples, each containing a line and a newline character (or empty string), return a single string.

New in version 3.2.0.

Parameters

lines (List[Tuple[str, str]])

Return type

str

See also

splitlines()

_SL = TypeVar(_SL, bound=StringList)

Type:    TypeVar

Invariant TypeVar bound to domdf_python_tools.stringlist.StringList.