Parser¶

Bases: abc.ABC, Generic[configpile.parsers._Value]

Describes a parser, that takes a string and returns either a value or an error

Methods

`as_sequence_of_one`	Returns a parser, that returns a sequence of a single value on success
`choices`	Returns, when relevant, a set of inputs whose parse results cover all possible values
`empty_means_none`	Returns a new parser where the empty string means None
`flat_map`	Maps successful results of the parser through the given function that may fail
`from_choices`	Creates a parser whose values are chosen from a set of strings
`from_function`	Creates a parser from a function that returns a value or an error
`from_function_that_raises`	Creates a parser from a function that raises exceptions on parse errors
`from_mapping`	Creates a parser whose strings correspond to keys in a dictionary
`from_parsy_parser`	Creates a parser from a parsy parser
`map`	Maps successful results of the parser through the given function
`parse`	Parses a string into a result
`separated_by`	Returns a new parser that parses values separated by a string
`validated`	Returns a parser that verifies a predicate after successful parse

List of members of Parser

abstract parse(arg)[source]¶

Parses a string into a result

This method reports parsing errors using a result type instead of raising exceptions.

Example

>>> user_input = "invalid"
>>> float_parser.parse(user_input)
Err1(msg="...", contexts=[])
>>> user_input = 2.0
>>> float_parser.parse(user_input)
2.0

Parameters: arg (str) – String value to parse
Return type: Union[TypeVar(_Value), Err]
Returns: A result containing either the parsed value or a description of an error

choices()[source]¶

Returns, when relevant, a set of inputs whose parse results cover all possible values

The definition above is written carefully: parsers may parse aliases, or normalize input when parsing (by stripping whitespace or normalizing case).

This method returns a set of strings, which does not need to be minimal, so that their parsed values cover the set of possible result values.

Return type: Optional[Sequence[str]]

map(f)[source]¶

Maps successful results of the parser through the given function

Parameters: f (Callable[[TypeVar(_Value)], TypeVar(_Item)]) – Function to map the result through
Return type: Parser[TypeVar(_Item)]
Returns: Updated parser

flat_map(f)[source]¶

Maps successful results of the parser through the given function that may fail

Parameters: f (Callable[[TypeVar(_Value)], Union[TypeVar(_Item), Err]]) – Function to map the result through, may return an error
Return type: Parser[TypeVar(_Item)]
Returns: Updated parser

as_sequence_of_one()[source]¶

Returns a parser, that returns a sequence of a single value on success

Return type: Parser[Sequence[TypeVar(_Value)]]
Returns: Updated parser

empty_means_none(strip=True)[source]¶

Returns a new parser where the empty string means None

Parameters: strip (bool) – Whether to strip whitespace
Return type: Parser[Optional[TypeVar(_Value)]]
Returns: A new parser

separated_by(sep, strip=True, remove_empty=True)[source]¶

Returns a new parser that parses values separated by a string

Parameters

sep (str) – Separator
strip (bool) – Whether to strip whitespace from separated values
remove_empty (bool) – Whether to remove empty strings before parsing them

Return type

Parser[Sequence[TypeVar(_Value)]]

Returns

A new parser

validated(predicate, msg)[source]¶

Returns a parser that verifies a predicate after successful parse

Parameters

predicate (Callable[[TypeVar(_Value)], bool]) – Predicate to check
msg (Union[str, Callable[[str, TypeVar(_Value)], str]]) – Either a string, or a function that constructs a string from the parsed string and the result

Return type

_Validated[TypeVar(_Value)]

Returns

A new parser

static from_parsy_parser(parser)[source]¶

Creates a parser from a parsy parser

Parameters: parser (Parser) – Parser returning a value of type t
Return type: Parser[TypeVar(_Value)]
Returns: Parameter type

static from_function_that_raises(f, *catch)[source]¶

Creates a parser from a function that raises exceptions on parse errors

Parameters

f (Callable[[str], TypeVar(_Value)]) – Function that parses the string
catch (Type[Exception]) – Exception types to catch; if no types are provided, all exceptions will be caught

Return type

Parser[TypeVar(_Value)]

Returns

Parameter type

static from_function(f)[source]¶

Creates a parser from a function that returns a value or an error

Parameters: f (Callable[[str], Union[TypeVar(_Value), Err]]) – Function that parses the string
Return type: Parser[TypeVar(_Value)]
Returns: Parameter type

static from_choices(values, strip=True, force_case=ForceCase.NO_CHANGE)[source]¶

Creates a parser whose values are chosen from a set of strings

Parameters

values (Iterable[str]) – Set of values
strip (bool) – Whether to strip whitespace before looking for choices

Return type

Parser[str]

Returns

Parameter type

static from_mapping(mapping, strip=True, force_case=ForceCase.NO_CHANGE, aliases=None)[source]¶

Creates a parser whose strings correspond to keys in a dictionary

Parameters

mapping (Mapping[str, TypeVar(_Value)]) – Dictionary mapping strings to values
strip (bool) – Whether to strip whitespace before looking for keys
force_case (ForceCase) – Whether to normalize the case of the user string
aliases (Optional[Mapping[str, TypeVar(_Value)]]) – Additional mappings not shown in help

Return type

Parser[TypeVar(_Value)]

Returns

Parameter type

static __new__(cls, *args, **kwds)¶