pocketutils.core.dot_dict

Module Contents

class pocketutils.core.dot_dict.NestedDotDict(x: Mapping[str, Any])

A thin wrapper around a nested dict to make getting values easier. This was designed as a wrapper for TOML, but it works more generally too.

Keys must be strings that do not contain a dot (.). A dot is reserved for splitting values to traverse the tree. For example, dotdict["pet.species.name"].

Constructor.

Raises

XValueError – If a key (in this dict or a sub-dict) is not a str or contains a dot

classmethod read_json(path: pocketutils.core.PathLike) → NestedDotDict

Reads JSON from a file, into a NestedDotDict. If the JSON data is a list type, converts into a dict with keys "1", "2", ... . Can read .json or .json.gz.

classmethod read_pickle(path: Union[pathlib.PurePath, str]) → NestedDotDict

Note that this function has potential security concerns. This is because it relies on the pickle module.

classmethod parse_json(data: str) → NestedDotDict

Parses JSON from a string, into a NestedDotDict. If the JSON data is a list type, converts into a dict with the key data.

write_json(path: pocketutils.core.PathLike, *, indent: bool = False, mkdirs: bool = False) → str

Writes to a json or .json.gz file.

Returns

The JSON text

write_toml(path: pocketutils.core.PathLike, mkdirs: bool = False) → str

Writes to a toml or .toml.gz file.

Returns

The JSON text

write_pickle(path: pocketutils.core.PathLike) → None

Writes to a pickle file.

to_json(*, indent: bool = False) → str

Returns JSON text.

to_toml() → str

Returns TOML text.

leaves() → Mapping[str, Any]

Gets the leaves in this tree.

Returns

A dict mapping dot-joined keys to their values

sub(items: str) → NestedDotDict

Returns the dictionary under (dotted) keys items.

See also

sub_opt()

sub_opt(items: str) → NestedDotDict

Returns the dictionary under (dotted) keys items, or empty if a key is not found.

See also

sub()

exactly(items: str, astype: Type[T]) → T

Gets the key items from the dict if it has type astype.

Parameters

• items – The key hierarchy, with a dot (.) as a separator

• astype – The type, which will be checked using isinstance

Returns

The value in the required type

Raises

XTypeError – If not isinstance(value, astype)

get_as(items: str, astype: Callable[[Any], T], default: Optional[T] = None) → Optional[T]

Gets the value of an optional key, or default if it doesn’t exist. Calls astype(value) on the value before returning.

See also

req_as() exactly()

Parameters

• items – The key hierarchy, with a dot (.) as a separator. Ex: animal.species.name.

• astype – Any function that converts the found value to type T. Can be a Type, such as int. Despite the annotated type, this function only needs to accept the actual value of the key as input, not Any.

• default – Return this value if the key is not found (at any level)

Returns

The value of found key in this dot-dict, or default.

Raises

XValueError – Likely exception raised if calling astype fails

req_as(items: str, astype: Optional[Callable[[Any], T]]) → T

Gets the value of a required key. Calls astype(value) on the value before returning.

See also

req_as() exactly()

Parameters

• items – The key hierarchy, with a dot (.) as a separator. Ex: animal.species.name.

• astype – Any function that converts the found value to type T. Can be a Type, such as int. Despite the annotated type, this function only needs to accept the actual value of the key as input, not Any.

Returns

The value of found key in this dot-dict.

Raises

• XKeyError – If the key is not found (at any level).

• XValueError – Likely exception raised if calling astype fails

get_list_as(items: str, astype: Callable[[Any], T], default: Optional[Sequence[T]] = None) → Optional[Sequence[T]]

Gets list values from an optional key. Note that astype here converts elements within the list, not the whole list. Also see req_list_as.

Parameters

• items – The key hierarchy, with a dot (.) as a separator. Ex: animal.species.name.

• astype – Any function that converts the found value to type T. Ex: int.

• default – Return this value if the key wasn’t found

Returns

[astype(v) for v in self[items]], or default if items was not found.

Raises

• XValueError – Likely exception raised if calling astype fails

• XTypeError – If the found value is not a (non-str) Sequence

req_list_as(items: str, astype: Optional[Callable[[Any], T]]) → Sequence[T]

Gets list values from a required key. Note that astype here converts elements within the list, not the whole list. Also see get_list_as.

Parameters

• items – The key hierarchy, with a dot (.) as a separator. Ex: animal.species.name.

• astype – Any function that converts the found value to type T. Ex: int.

Returns

[astype(v) for v in self[items]]

Raises

• XValueError – Likely exception raised if calling astype fails

• XTypeError – If the found value is not a (non-str) Sequence

• XKeyError – If the key was not found (at any level)

get(items: str, default: Any = None) → Any

Gets a value from an optional key. Also see __getitem__.

items() → Sequence[Tuple[str, Any]]

D.items() -> a set-like object providing a view on D’s items

keys() → Sequence[str]

D.keys() -> a set-like object providing a view on D’s keys

values() → Sequence[Any]

D.values() -> an object providing a view on D’s values

pretty_str() → str

Pretty-prints the leaves of this dict using json.dumps.

Returns

A multi-line string