ways.parsing.parse module

A module that holds ContextParser - A class fills in Context’s mapping.

class ways.parsing.parse.ContextParser(context)

Bases: object

A class that’s used to fill out missing values in a Context’s mapping.

Some quick terms: If you see the word ‘token’, it means a piece of a string that needs to be filled out, such as ‘some_{TOKEN}_here’.

A field is the token + its information. For example, if the token being filled out is optional or if input to a token is valid.

This class is meant to expand and resolve the tokens inside the mapping of a Context object.

get_all_mapping_details()

Get the combined mapping details of this Context.

Note

The “true” combined mapping details of our Context is actually just Context.get_mapping_details(). This method can produce different results because it is yielding/updating Context.get_mapping_details() with all of its plugin’s data. Use with caution.

Returns:The combined mapping_details of our Context and plugins. Return type:dict[str]

get_child_tokens(token)

Find the child tokens of a given token.

Parameters:token (str) – The name of the token to get child tokens for. Returns:

The child tokens for the given token. If the given token

is not a parent to any child tokens, return nothing.

Return type:list[str]

get_mapping_details()

Get the parse-mapping details of our entire Context.

Basically, we take the collection of all of the mapping details of the Context, as is, which we know is the “sum” of all of the Context’s plugin’s mapping_details. But we also yield each plugin individually, in case some information was lost, along the way.

Yields:dict[str] – The mapping details of this Context.

get_required_tokens()

list[str]: Get the tokens for this Context that must be filled.

get_str(resolve_with='', depth=-1, holdout=None, groups=None, display_tokens=False)

Create a string of the Context’s mapping.

Note

holdout and groups cannot have any common token names.

Parameters:

• resolve_with (iterable[str] or str, optional) – The types of ways that our parser is allowed to resolve a path. These are typically some combination of (‘glob’, ‘regex’, ‘env’) are are defined with our Plugin objects that make up a Context.
• depth (int, optional) – The number of times this method are allowed to expand the mapping before it must return it. If depth=-1, this method will expand mapping until there are no more tokens left to expand or no more subtokens to expand with. Default: -1.
• holdout (set[str], optional) – If tokens (pre-existing or expanded) are in this list, they will not be resolved. Default is None.
• groups (dict[str, str] or iterable[str, str], optional) – A mapping of token names and a preferred token value to substitute it with. This variable takes priority over all types of resolve_with types. Default is None.
• display_tokens (bool, optional) – If True, the original name of the token will be included in the output of the mapping, even it its contents are expanded. Example: ‘/some/{JOB}/here’ -> r’/some/(?P<JOB>w+_d+)/here’. It’s recommended to keep this variable as False because the syntax used is only regex-friendly. But if you really want it, it’s there. Default is False.

Raises:

• ValueError – If groups got a bad value.
• ValueError – If groups and holdout have any common elements. It’s impossible to know what to do in that case because both items have conflicting instructions.

Returns:

The resolved string.

Return type:

str

get_token_parse(name, parse_type)

Get the parse expression for some token name.

Parameters:

• name (str) – The name of the token to get parse details from.
• parse_type (str) – The engine type whose expression will be returned

Returns:

The parse expression used for the given token.

get_tokens(required_only=False)

Get the tokens in this instance.

Parameters:required_only (bool, optional) – If True, do not return optional tokens. If False, return all tokens, required and optional. Default is False. Returns:The requested tokens. Return type:list[str]

get_value_from_parent(name, parent, parse_type)

Get the value of a token using another parent token.

Parameters:

• name (str) – The token to get the value of.
• parent (str) – The parent token that is believed to have a value. If it has a value, it is used to parse and return a value for the name token.
• parse_type (str) – The parse engine to use.

Returns:

The value of the name token.

is_valid(token, value, resolve_with='regex')

Check if a given value will work for some Ways token.

Parameters:

• token (str) – The token to use to check for the given value.
• value – The object to check for validity.
• resolve_with (str, optional) – The parse type to use to check if value is valid for token. Only ‘regex’ is supported right now. Default: ‘regex’.

Returns:

If the given value was valid.

Return type:

bool

classmethod resolve_with_tokens(mapping, tokens, details, options, groups, display_tokens)

Substitute tokens in our mapping for anything that we can find.

Parameters:

• mapping (str) – The path that will be resolved and substituted.
• tokens (list[str]) – The pieces inside of the mapping to resolve.
• details (dict[str]) – All of the token/subtoken information available to resolve the tokens in this mapping.
• options (list[str]) – The different ways to resolve the tokens.
• groups (dict[str, str] or iterable[str, str], optional) – A mapping of token names and a preferred token value to substitute it with. This variable takes priority over all types of resolve_with types. Default is None.
• display_tokens (bool, optional) – Whether or not to add regex (?P<TOKEN_NAME>) tags around all of our resolved text.

Returns:

The resolved mapping.

Return type:

str

ways.parsing.parse.expand_mapping(mapping, details)

Split the tokens in a mapping into subtokens, if any are available.

Parameters:

• mapping (str) – The mapping to expand.
• details (dict[str]) – The information about the mapping that will be used to expand it.

Returns:

The expanded mapping.

Return type:

str

ways.parsing.parse.find_tokens(mapping)

list[str]: The tokens to fill in. inside of a mapping.

ways.parsing.parse.is_done(mapping)

bool: If there are still tokens to fill in, inside the mapping.