solprop.recipe.paths

Parameter paths: the canonical name of every value in a recipe.

A path is a keyword, then any number of steps: .name for a keyword of an object, [i] for an element of an array and ["key"] for a key of a mapping, as in pressure, pulses[1].energy or launch["HE1,1:even"].share. Paths are what Recipe.set and Recipe.get take, what errors name, what a scan varies and what a pin sets.

In the tree a TOML document reads into, an object and a mapping are both dictionaries, so .name and ["name"] address the same entry; the parsed path keeps them apart (Attribute and Key) because they are different texts, and the canonical text is the one format_path() writes. An index is a non-negative integer with no leading zero, and a key is a JSON string, so ["a\"b"] is the key a"b.

Module Attributes

Step	One step of a parameter path.

Functions

format_path(steps)	Write the canonical text of a parameter path.
get_path(tree, path)	Return the value at a parameter path of a recipe table.
parse_path(text)	Read a parameter path into its steps.
set_path(tree, path, value)	Return a copy of a recipe table with the value at a parameter path replaced.

Classes

Attribute(name)	A keyword, or a keyword of an object: name or .name in a path.
Index(position)	An element of an array: [i] in a path.
Key(key)	A key of a mapping: ["key"] in a path.

class solprop.recipe.paths.Attribute(name)

Bases: object

A keyword, or a keyword of an object: name or .name in a path.

Attributes:

namestr

A Python identifier.

name: str

class solprop.recipe.paths.Index(position)

Bases: object

An element of an array: [i] in a path.

Attributes:

positionint

The zero-based position, at least 0.

position: int

class solprop.recipe.paths.Key(key)

Bases: object

A key of a mapping: ["key"] in a path.

Attributes:

keystr

The key, any string.

key: str

type solprop.recipe.paths.Step = Attribute | Index | Key

One step of a parameter path.

solprop.recipe.paths.format_path(steps)

Write the canonical text of a parameter path.

Parameters:

stepssequence of Attribute, Index or Key

The steps, starting with an Attribute.

Returns:

str

The canonical text, which parse_path() reads back to steps.

Raises:

RecipeError

If steps is empty, does not start with a keyword, or holds a name that is not an identifier or a negative index.

Examples

>>> format_path((Attribute("pulses"), Index(1), Attribute("energy")))
'pulses[1].energy'
>>> format_path((Attribute("launch"), Key("HE1,1:even")))
'launch["HE1,1:even"]'

solprop.recipe.paths.get_path(tree, path)

Return the value at a parameter path of a recipe table.

Parameters:

treeMapping

The table the path starts in (a recipe’s [build] table), as tomllib reads it: dictionaries, lists and values.

pathstr or sequence of Attribute, Index or Key

The path, as text or steps. .name and ["name"] both address the key name of a dictionary.

Returns:

object

The value; a table or array is returned itself, not a copy.

Raises:

RecipeError

If a step finds no entry, naming the path and the step.

Examples

>>> tree = {"pulses": [{"energy": "1 uJ"}, {"energy": "10 uJ"}]}
>>> get_path(tree, "pulses[1].energy")
'10 uJ'

solprop.recipe.paths.parse_path(text)

Read a parameter path into its steps.

Parameters:

textstr

The path, such as 'pulses[1].energy'.

Returns:

tuple of Attribute, Index or Key

The steps; the first is always an Attribute, the keyword.

Raises:

RecipeError

If text is not a path, naming the column where reading stopped.

Examples

>>> parse_path('launch["HE1,1:even"].share')
(Attribute(name='launch'), Key(key='HE1,1:even'), Attribute(name='share'))
>>> parse_path("pulses[1].energy")
(Attribute(name='pulses'), Index(position=1), Attribute(name='energy'))

solprop.recipe.paths.set_path(tree, path, value)

Return a copy of a recipe table with the value at a parameter path replaced.

The tables and arrays on the path are copied and everything else is shared, so tree is not changed. The last step may add a key to a table, but every earlier step must exist, and an index must name an existing element: an array is never extended.

Parameters:

treeMapping

The table the path starts in, as for get_path().

pathstr or sequence of Attribute, Index or Key

The path, as text or steps.

valueobject

The new value.

Returns:

dict

The new table.

Raises:

RecipeError

If a step before the last finds no entry, or an index is past the end, naming the path and the step.

Examples

>>> tree = {"pulses": [{"energy": "1 uJ"}]}
>>> set_path(tree, "pulses[0].energy", "2 uJ")
{'pulses': [{'energy': '2 uJ'}]}
>>> tree
{'pulses': [{'energy': '1 uJ'}]}