Parsing

This module provides several parsers that convert (usually user-provided) strings to python objects, or check user input, and throw ValueError in case of any issue.

All parsers are descendants of the Parser class. On the surface, they are just callables that take a string and return a python object. That is, you can use them in any place that expects such callable, for example in flags in argparse, or in ask() method from yuio.io.

When parsing fails, we raise ParsingError.

Base parser

class yuio.parse.Parser

Base class for parsers.

abstract parse(value: str) → T

Parse user input, raise ParsingError on failure.

Don’t forget to call Parser.validate() after parsing a value.

abstract parse_config(value: Any) → T

Parse value from a config, raise ParsingError on failure.

This method accepts python values, i.e. when parsing a json config.

Don’t forget to call Parser.validate() after parsing a value.

abstract validate(value: T)

Verify parsed value, raise ParsingError on failure.

describe() → Optional[str]

Return a human-readable description of an expected input.

describe_value(value: T) → Optional[str]

Return a human-readable description of a given value.

classmethod from_type_hint(ty: Any) → Parser[_t.Any]

Create parser from a type hint.

class yuio.parse.ParsingError

Raised when parsing or validation fails.

This exception is derived from both ValueError and argparse.ArgumentTypeError to ensure that error messages are displayed nicely with argparse, and handled correctly in other places.

Value parsers

class yuio.parse.Str(modifier: Optional[Callable[[str], str]] = None)

Parser for str values.

Applies a modifier to the value, if one is given.

class yuio.parse.StrLower

Parser for str values that converts them to lowercase.

class yuio.parse.StrUpper

Parser for str values that converts them to uppercase.

class yuio.parse.Int

Parser for int values.

class yuio.parse.Float

Parser for float values.

class yuio.parse.Bool

Parser for bool values, such as ‘yes’ or ‘no’.

class yuio.parse.Enum(enum_type: Type[E])

Parser for enums, as defined in the standard enum module.

File system path parsers

class yuio.parse.Path(extensions: Optional[Collection[str]] = None)

Parse a file system path, return a pathlib.Path.

class yuio.parse.NonExistentPath(extensions: Optional[Collection[str]] = None)

Parse a file system path and verify that it doesn’t exist.

class yuio.parse.ExistingPath(extensions: Optional[Collection[str]] = None)

Parse a file system path and verify that it exists.

class yuio.parse.File(extensions: Optional[Collection[str]] = None)

Parse path to a file.

class yuio.parse.Dir

Parse path to a directory.

class yuio.parse.GitRepo

Parse path to a git repository.

This parser just checks that the given directory has a subdirectory named .git.

Validators

class yuio.parse.Bound(inner: Parser[C], *, lower: Optional[C] = None, lower_inclusive: Optional[C] = None, upper: Optional[C] = None, upper_inclusive: Optional[C] = None)

Check that value is upper- or lower-bound by some constraints.

Parameters

• inner – inner parser that will be used to actually parse a value before checking its bounds.

• lower – set lower bound for value, so we require that value > lower. Can’t be given if lower_inclusive is also given.

• lower_inclusive – set lower bound for value, so we require that value >= lower. Can’t be given if lower is also given.

• upper – set upper bound for value, so we require that value < upper. Can’t be given if upper_inclusive is also given.

• upper_inclusive – set upper bound for value, so we require that value <= upper. Can’t be given if upper is also given.

lower_bound(lower: C) → _Self

Set lower bound so we require that value > lower.

lower_bound_inclusive(lower: C) → _Self

Set lower bound so we require that value >= lower.

upper_bound(upper: C) → _Self

Set upper bound so we require that value < upper.

upper_bound_inclusive(upper: C) → _Self

Set upper bound so we require that value <= upper.

class yuio.parse.OneOf(inner: Parser[T], values: Collection[T])

Check if the parsed value is one of the given set of values.

class yuio.parse.Regex(inner: Parser[str], regex: Union[str, Pattern])

Check if the parsed value is one of the given set of values.