soleil.utils#

Module Attributes

temp_dir([suffix, prefix, dir])

User-callable function to create and return a unique temporary directory.

Functions

`derive`(parents, *new_vars)	Derives the specified class, overloading the supplied indicated members. Example::.
`package_overrides`([as_source])	Returns a list of all supplied package overrides.
`root`()	Returns the path to the root config
`root_stem`([root_config])	Returns the stem of the filename name of the root configuration.
`spawn`(rel_module_name[, ...])	Takes the name of a target module that promotes a class, and loads it in a new package (the spawned package), by default providing the calling package's overrides as possible overrides in the spawned package.
`sub_dir`(root[, create])	Returns a sub-directory with a sequential number

Classes

id_str([glue, safe, full, with_root_stem])

A special class that resolves to an id string built from the overrides that are not annotated with noid.

soleil.utils.temp_dir(suffix=None, prefix=None, dir=None)#: Returns a temporary directory

soleil.utils.derive(*parents, **new_vars)#

Derives the specified class, overloading the supplied indicated members. Example:

class Source:
    a = 1
    b = 2

b3 = derive(Source, b=3)

soleil.utils.root_stem(root_config=None) → Path#: Returns the stem of the filename name of the root configuration.

soleil.utils.root() → Path#: Returns the path to the root config

soleil.utils.package_overrides(as_source=True) → List#: Returns a list of all supplied package overrides.

class soleil.utils.id_str(glue=',', safe=True, full=False, with_root_stem=True)#

Bases: RStr

A special class that resolves to an id string built from the overrides that are not annotated with noid.

Parameters:

glue – String that joins all the override strings
safe – Whether the escape characters that are invalid in filenames
full – If False (the default), only the right-most target attribute is used. (e.g., with the default full=False, 'height=2' instead of 'rectangle.dimensions.height=2).
with_root_stem – Whether to include the file path stem of the root config

soleil.utils.sub_dir(root: Path, create=True)#: Returns a sub-directory with a sequential number

soleil.utils.spawn(rel_module_name, use_package_overrides=True, default_overrides: List[str | Dict[str, Any] | Override] | None = None, var_path=None) → Type#

Takes the name of a target module that promotes a class, and loads it in a new package (the spawned package), by default providing the calling package’s overrides as possible overrides in the spawned package.

The target module must expose a promoted class that will then be returned with the specified overrides applied (those that are compatible).

This returned class can then be used as a parent class for a new class in the calling module. The new class will also have the compatible specified overrides applied to it.

For correct transference of overrides to the parent class, the child class must also be promoted in the calling module or the var_path parameter must be set to the child class’s __qualname__ attribute.

For example, assuming file main.solconf promotes a class:

@promoted
class B(A := spawn(".main")):
    type: as_type = lambda **kwargs: kwargs
    c = A.b + 1
    d = c + 1

Note that one can optionally access the parent class’s attributes by assigning it to a local variable

Parameters:

rel_module_name – The module name relative to the calling module, if dot-prefixed, or the current package otherwise.
use_package_overrides – [True] Whether to let the spawned package inherit the calling package’s overrides. Note that the calling package will still be able to process its overrides (e.g., if a a member with the corresponding variable path exists in only the calling package or in both the calling package and the spawned package).
default_overrides – Any default overrides to apply to the spawned package.
var_path – When deriving a spawned class, if the child class is not promoted, set this to the child class’s expected __qualname__ attribute.

Todo

Make spawn() work for chained and/or multiple inheritance, add unit tests.

soleil.utils

Contents

soleil.utils#