yahp.utils

Interactive

yahp.utils.interactive.query_with_default(name: str, default_response: Optional[str] = None) → str[source]

Query for a string response on the CLI.

Parameters

question (str) – Question to ask.
default_response (Optional[str], optional) – Default response. Set to None to require a response.

Returns

The response.

Return type

str

yahp.utils.interactive.query_with_options(name: str, options: List[str], default_response: Optional[str], multiple_ok: Literal[False]) → str[source]

yahp.utils.interactive.query_with_options(name: str, options: List[str], default_response: Optional[str], multiple_ok: Literal[True]) → List[str]

Interactively queries the user to select from a list of options.

Parameters

name (str) – Prompt for the user.
options (List[str]) – List of options.
default_response (Optional[str]) – Default response. Set to None to require a response.
multiple_ok (bool) – Whether the user can specify multiple options via a comma-seperated response.

Returns

The response, or if multiple_ok is True, a list of responses.

yahp.utils.interactive.query_yes_no(question: str, default: bool = True)[source]

Query for a yes/no response on the CLI.

Parameters

question (str) – Question to ask.
default (bool, optional) – Default response. Defaults to True.

Returns

The response.

Return type

bool

Iter Helpers

class yahp.utils.iter_helpers.ListOfSingleItemDict(data: List)[source]

Simple list wrapper for a list of single-item dicts

This enables string-based gets and sets. If there are duplicate keys in the list, the first one is retrieved/modified.

yahp.utils.iter_helpers.ensure_tuple(x: Union[T, Tuple[T, ...], List[T], Dict[Any, T]]) → Tuple[T, ...][source]

Converts x to a tuple

Parameters: x (Any) – If x is a tuple, it is returned as-is. If x is a list, it is converted to a tuple and returned. If x is a dict, its values are converted to a tuple and returned. Otherwise, x: is wrapped as a one-element tuple and returned.
Returns: x, as a tuple.
Return type: Tuple[Any, …]

yahp.utils.iter_helpers.extract_only_item_from_dict(val: Dict[K, V]) → Tuple[K, V][source]

Extracts the only item from a dict and returns it .

Parameters: val (Dict[K, V]) – A dictionary which should contain only one entry
Raises: ValueError – Raised if the dictionary does not contain 1 item
Returns: The key, value pair of the only item
Return type: Tuple[K, V]

yahp.utils.iter_helpers.is_list_of_single_item_dicts(obj: JSON) → bool[source]

Whether the provided object is a list of single-item dictionaries

Parameters: obj (List[Dict]) –
Returns: True if obj is a list of single-item dictionaries

yahp.utils.iter_helpers.list_to_deduplicated_dict(list_of_dict: List[JSON], allow_str: bool = False, separator: str = '+') → Dict[str, JSON][source]

Converts a list of single-item dictionaries to a dictionary, deduplicating keys along the way

Parameters

list_of_dict (List[Dict[str, Any]]) – A list of single-item dictionaries
allow_str (bool, optional) – If True, list can contain strings, which will be added as keys with None values. Defaults to False.
separator (str, optional) – The separator to use for deduplication. Default ‘+’.

Returns

Deduplicated dictionary

Return type

Dict[str, Dict]

Type Helpers

class yahp.utils.type_helpers.HparamsType(item: Type[Any])[source]

Wrapper to parse type annotations and determine type of field.

HparamsType parses typing annotations and provides convenience methods to determine the field types.

Parameters: item (type) – Type annotation to parse.

types

The allowed types for this annotation, as a list. If the annotation is List[X] or Optional[X], then X is stored in this attributed. If the annotation is a Union[X, Y], then this attribute is [X, Y]. None is never stored here; instead, see is_optional.

Type: List[Type]

is_optional

Whether the annotation allows None.

Type: bool

is_list

Whether the annotation is a list.

Type: bool

convert(val: Any, field_name: str, *, wrap_singletons: bool = True) → Any[source]

Attempt to convert an item into a type allowed by the annotation.

Parameters

val (Any) – Item to convert.
field_name (str) – Name for field being converted.
wrap_singletons (bool, optional) – If True (the default) and the field is a list, singletons will be wrapped into a list. Otherwise, raise a TypeError.

Raises

ValueError – Raised if val is None, but the annotation does not permit None.
TypeError – Raised if val cannot be converted into a type specified by the annotation.

Returns

The converted item.

property is_boolean: bool: Whether the annotation allows for a bool, or a list of bool.

property is_enum: bool: Whether the annotation allows for a subclass of Enum, or a list of Enum.

property is_json_dict: bool: Whether it is a JSON Dictionary.

property is_primitive: bool: Whether the annotation allows for a bool, int, str, or float, a list of such types, or is always None.

property is_recursive: bool: Whether the datatype is recursive (i.e is not JSON, a primitive, or an enum)

property type: Type[Any]

The underlying type allowed by the annotation. If the annotation is a List[x] or Optional[X], then X is returned.

This property is only available if the annotation is not a union of multiple types. For these cases, see types.

yahp.utils.type_helpers.get_default_value(f: Field[Any]) → Any[source]

Returns an instance of a default value for a field.

Parameters: f (Field) – The field.

yahp.utils.type_helpers.is_field_required(f: Field[Any]) → bool[source]

Returns whether a field is required (i.e. does not have a default value).

Parameters: f (Field) – The field.

yahp.utils.type_helpers.is_none_like(x: Any, *, allow_list: bool) → bool[source]

Returns whether a value is None, "none", [""], ["none"], or has been marked as a missing field.

Parameters

x (object) – Value to examine.
allow_list (bool) – Whether to treat [""], or ["none"] as None.

yahp.utils.type_helpers.to_bool(x: Any)[source]

Converts a value to a boolean

Parameters: x (object) – Value to attempt to convert to a bool.