azely.utils module

Azely’s utils module (low-level utilities).

This module provides series of utility related to exception and I/O: (1) AzelyError class as Azely’s base exception class (2) open_toml function to open (and update if any) a TOML file (3) cache_to decorator which caches returns of a function to a TOML file (4) set_defaults decorator which replaces default values of a function

exception AzelyError

Bases: Exception

Azely’s base exception class.

class cache_to(path: Union[Path, str], query: str = 'query')

Bases: object

Decorator which cache returns of a function to a TOML file.

Suppose there is a function which takes a long time to get a result and it is decorated by this function:

>>> import time
>>> @azely.utils.cache_to('cache.toml')
... def func(query: str) -> str:
...     # simulates a long-time processing
...     time.sleep(10)
...     return query

Then the following function calls:

>>> func('aaa')
>>> func('bbb')
>>> func('ccc')

would take ~30 seconds to finish. But at the same time, the results are cached to cache.toml like:

# cache.toml

aaa = "aaa"
bbb = "bbb"
ccc = "ccc"

Then the second calls would take much shorter time because cached values are simply read and returned by the decorator. If a query argument is given with ‘!’ at the end of it (e.g., 'aaa!'), cached values are forcibly updated by an immediate call of the original function.

Parameters:

• path (Union[Path, str]) –

• query (str) –

pattern = re.compile('^\\s*([\\w\\s]*\\w)\\s*!$')

open_toml(path: Union[Path, str], alt_dir: Union[Path, str] = '.')

Open a TOML file and get contents as a dictionary.

If this function is used in a with context management, any updates to the dictionary is also reflected on the TOML file.

Parameters:

• path (Union[Path, str]) – Path or filename (without suffix) of a TOML file. If the latter is specified and if it does not exist in a current directory, then the function tries to find it in alt_dir.

• alt_dir (Union[Path, str]) – Path of a directory where the function tries to find the TOML file if it does not exist in a current directory.

Returns:

Dictionary equivalent to the contents of the TOML file.

Raises:

AzelyError – Raised if the TOML file is not found anywhere.

Examples

To simply open a TOML file (for example, ./user.toml):

>>> dic = azely.utils.open_toml('user.toml')

or:

>>> dic = azely.utils.open_toml('user')

To open and update a TOML file:

>>> with azely.utils.open_toml('user.toml') as dic:
...     dic['new_key'] = new_value

class set_defaults(path: Union[Path, str], key: str = '')

Bases: object

Decorator which replaces default values of a function.

The alternative default values are read from a TOML file. Suppose there is a function with some parameters and it is decorated by this function:

>>> @azely.utils.set_defaults('defaults.toml')
... def func(a: int, b: int = 0) -> int:
...     return a + b

Suppose the content of defaults.toml is like:

# defaults.toml

a = 1
b = 2

Then the following function calls results in:

>>> func(0, 1) # -> 1
>>> func(0) # -> 2
>>> func() # -> 3

This is because now the function is equivalent to:

>>> def func(a: int = 1, b: int = 2) -> int:
...     return a + b

Parameters:

• path (Union[Path, str]) –

• key (str) –

static update(sig: Signature, defaults: Dict[str, Any]) → Signature

Parameters:

• sig (Signature) –

• defaults (Dict[str, Any]) –

Return type:

Signature