id_translation.offline.parse_format_string

Utility module for parsing raw Format input strings.

Functions

get_elements(fmt)

Split a format string into elements.

Classes

Element(part, placeholders, required, ...)	Information about a single block in a Format specification.
ParseBlockResult(parsed_block, placeholders)	Output type of Element.parse_block().

Exceptions

BadDelimiterError(format_string, open_idx, idx)	Errors raised due to mismatched delimiters.
MalformedOptionalBlockError	Error raised for improper optional blocks.

exception BadDelimiterError(format_string, open_idx, idx)

Bases: MalformedOptionalBlockError

Errors raised due to mismatched delimiters.

class Element(part, placeholders, required, positional_part)

Bases: object

Information about a single block in a Format specification.

classmethod make(fmt, in_optional_block)

Create an Element from an input string s.

Parameters:

• fmt – Input data.

• in_optional_block – Flag indicating whether s was found inside an optional block.

Returns:

A new Element.

classmethod parse_block(block, defaults=None)

Parse an entire block with optional defaults for placeholders found.

Hint

With defaults, the value of the ParseBlockResult.parsed_block is more or less what you’d expect if the built-in str.format_map()-method allowed missing keys.

Anonymous fields are not permitted.

Output with defaults == None:

When defaults are None, placeholder names are stripped from the parsed_block.

>>> block, placeholders = Element.parse_block("{id!s:.8}:{name!r}")
>>> print(f"{block=} has {placeholders=}")
block='{!s:.8}:{!r}' has placeholders=['id', 'name']

Field names in block are returned as ParseBlockResult.placeholders, in the order in which they appeared in the input block. The field names of parsed_block will be anonymous.

>>> block.format(UUID(int=10**38), "Morran Borran")
"4b3b4ca8:'Morran Borran'"

Output with defaults != None:

When defaults are given, all placeholders in the block which are present in the defaults are replaced with defaults[field_name] in the parsed_block.

>>> block, placeholders = Element.parse_block(
...     "{id!s:.8}:{name!r}",
...     defaults={"name": "Morran Borran"},
... )
>>> print(f"{block=} has {placeholders=}")
block="{id!s:.8}:'Morran Borran'" has placeholders=['id']

Field names without defaults will be present both in placeholders, and as named fields in the parsed_block.

>>> block.format(id=UUID(int=10**38))
"4b3b4ca8:'Morran Borran'"

Parameters:

• block – A block to parse.

• defaults – A dict {placeholder: value}.

Returns:

A ParseBlockResult tuple.

Raises:

ValueError – If block contains anonymous fields.

part

String literal.

placeholders

Placeholder names in part, if any.

positional_part

Return a positional version of the part attribute.

required

Flag indicating whether the element may be excluded.

exception MalformedOptionalBlockError

Bases: ValueError

Error raised for improper optional blocks.

static get_marker_row(format_string, open_idx=-1, idx=-1)

Get a string of length equal to format_string which marks problem locations.

class ParseBlockResult(parsed_block, placeholders)

Bases: NamedTuple

Output type of Element.parse_block().

parsed_block

Processed parts of the block.

placeholders

Names of the Format.placeholders in parsed_block, in the order in which they appear.

get_elements(fmt)

Split a format string into elements.

Parameters:

fmt – User input string.

Returns:

A list of parsed elements.

Raises:

BadDelimiterError – For unbalanced optional block delimitation characters.