From 8ac91ca021584d4235f7d5f9269125a4f7104d44 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 16:41:35 +0200 Subject: [PATCH 1/7] Specify that each field is the name of the field in the constructor and the value to be passed. --- docs/source/explanation/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/explanation/configuration.md b/docs/source/explanation/configuration.md index 1260190..aaf2461 100644 --- a/docs/source/explanation/configuration.md +++ b/docs/source/explanation/configuration.md @@ -25,7 +25,7 @@ The syntax has been chosen to allow configuration and construction of objects fo The whole configuration follows a single rule: ```{important} -Each configuration item names a Python class in its `class` field. **Every other field of the item is an argument of that class's constructor**, with the same name. +Each configuration item names a Python class in its `class` field. **Every other field of the item is an argument to that class's constructor**, with the same name as the field and the value to be passed to the constructor. ``` When pyAML reads an item, it imports the class given by `class` and calls it with the remaining fields as keyword arguments. The configuration below and the Python code next to it build exactly the same object: From d230d26ea77c4330d56c417fc74c2d9854aa11a6 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 16:45:50 +0200 Subject: [PATCH 2/7] Remove the grid since it required scrolling to be able to see both sets of codes at the same time. --- docs/source/explanation/configuration.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/source/explanation/configuration.md b/docs/source/explanation/configuration.md index aaf2461..0c8efa7 100644 --- a/docs/source/explanation/configuration.md +++ b/docs/source/explanation/configuration.md @@ -28,12 +28,8 @@ The whole configuration follows a single rule: Each configuration item names a Python class in its `class` field. **Every other field of the item is an argument to that class's constructor**, with the same name as the field and the value to be passed to the constructor. ``` -When pyAML reads an item, it imports the class given by `class` and calls it with the remaining fields as keyword arguments. The configuration below and the Python code next to it build exactly the same object: +When pyAML reads an item, it imports the class given by `class` and calls it with the remaining fields as keyword arguments. The YAML configuration and Python code below build equivalent objects: -`````{grid} 2 -:gutter: 2 - -````{grid-item} **Configuration** ```yaml @@ -44,9 +40,7 @@ model: unit: 1/m physics: AN01-AR/EM-QP/QF.01/magnetic_strength ``` -```` -````{grid-item} **Python** ```python @@ -61,8 +55,6 @@ Quadrupole( ), ) ``` -```` -````` Consequences of this rule: From f80e3b62be52ef5b57633f53985ea3cd73c831a7 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 16:47:56 +0200 Subject: [PATCH 3/7] Removed unknown fields are rejected since this is only true if validation is turned on and not a general requirement for the configuration. --- docs/source/explanation/configuration.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/explanation/configuration.md b/docs/source/explanation/configuration.md index 0c8efa7..49c9efe 100644 --- a/docs/source/explanation/configuration.md +++ b/docs/source/explanation/configuration.md @@ -60,7 +60,6 @@ Consequences of this rule: - **Nested objects are nested items.** If an argument expects an object (here `model` expects a magnet model), the field contains another item with its own `class` field. Lists of objects (such as `devices` or `simulators` of the `Accelerator`) are lists of items. - **Optional arguments are optional fields.** Arguments with a default value can be left out. -- **Unknown fields are rejected.** A field which is not an argument of the constructor, for example a misspelled one, raises an error when the configuration is loaded. - **Any class can be used.** Nothing is specific to pyAML classes: a facility-specific class from your own package can be used in the same way, as long as it can be imported. ### Finding the Accepted Fields From fda240a2a10c4ddf94079da4c6630293c0bf6e62 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 16:50:00 +0200 Subject: [PATCH 4/7] Changed link for API documentation to the page with links for all packages and not only pyaml. --- docs/source/explanation/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/explanation/configuration.md b/docs/source/explanation/configuration.md index 49c9efe..074ffa7 100644 --- a/docs/source/explanation/configuration.md +++ b/docs/source/explanation/configuration.md @@ -66,7 +66,7 @@ Consequences of this rule: Since fields are constructor arguments, the documentation of a class tells you what to write in the configuration. You can: -- read the [API documentation](https://pyaml.readthedocs.io/en/stable/) of the class, +- read the [API documentation](./../reference/index.md) of the class, - use `help()` in Python, which shows the signature of the constructor: ```python From 60194c268e1be287858f639b33ab0f0a9fc3bd5a Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 16:55:15 +0200 Subject: [PATCH 5/7] Add JSON schema and link to tools to list of option to find fields. --- docs/source/explanation/configuration.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/source/explanation/configuration.md b/docs/source/explanation/configuration.md index 074ffa7..81b417c 100644 --- a/docs/source/explanation/configuration.md +++ b/docs/source/explanation/configuration.md @@ -66,8 +66,8 @@ Consequences of this rule: Since fields are constructor arguments, the documentation of a class tells you what to write in the configuration. You can: -- read the [API documentation](./../reference/index.md) of the class, -- use `help()` in Python, which shows the signature of the constructor: +- Read the [API documentation](./../reference/index.md) of the class, +- Use `help()` in Python, which shows the signature of the constructor: ```python from pyaml.magnet.quadrupole import Quadrupole @@ -76,7 +76,8 @@ Since fields are constructor arguments, the documentation of a class tells you w # lattice_names: str | None = None, description: str | None = None) ``` -- use the schema registry, whose `describe()` method lists the fields of a registered class with their types. See [Use the Schema Registry](../how-to/configuration/use-schema-registry.ipynb). +- Use the schema registry, whose `describe()` method lists the fields of a registered class with their types. See [Use the Schema Registry](../how-to/configuration/use-schema-registry.ipynb). +- Use a JSON Schema in an external tool. See [JSON Schema Tools](../how-to/configuration/create-configuration.md#tools-that-help-writing-the-configuration). ## Configuration Items From 375f908539920fddd02724d6072a91fe53ac822d Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 18:51:16 +0200 Subject: [PATCH 6/7] Remove section about finding the fields to move it to the how-to guide instead. --- docs/source/explanation/configuration.md | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/docs/source/explanation/configuration.md b/docs/source/explanation/configuration.md index 81b417c..02a7f95 100644 --- a/docs/source/explanation/configuration.md +++ b/docs/source/explanation/configuration.md @@ -62,23 +62,6 @@ Consequences of this rule: - **Optional arguments are optional fields.** Arguments with a default value can be left out. - **Any class can be used.** Nothing is specific to pyAML classes: a facility-specific class from your own package can be used in the same way, as long as it can be imported. -### Finding the Accepted Fields - -Since fields are constructor arguments, the documentation of a class tells you what to write in the configuration. You can: - -- Read the [API documentation](./../reference/index.md) of the class, -- Use `help()` in Python, which shows the signature of the constructor: - - ```python - from pyaml.magnet.quadrupole import Quadrupole - help(Quadrupole) - # Quadrupole(name: str, model: MagnetModel | None = None, - # lattice_names: str | None = None, description: str | None = None) - ``` - -- Use the schema registry, whose `describe()` method lists the fields of a registered class with their types. See [Use the Schema Registry](../how-to/configuration/use-schema-registry.ipynb). -- Use a JSON Schema in an external tool. See [JSON Schema Tools](../how-to/configuration/create-configuration.md#tools-that-help-writing-the-configuration). - ## Configuration Items Each configurable item is represented by a mapping which describes the attributes and values needed to construct one Python object. The field `class` (or its alias `class_path`) identifies the type to construct. It should be written as a fully qualified Python class path, consisting of the module and class name. For example: From a1cc72394be5bfcd519d4cad8af51fd124bf5ef4 Mon Sep 17 00:00:00 2001 From: Teresia Olsson Date: Thu, 24 Sep 2026 18:59:16 +0200 Subject: [PATCH 7/7] Merge info in configuration item into previous section. --- docs/source/explanation/configuration.md | 27 ++++++------------------ 1 file changed, 6 insertions(+), 21 deletions(-) diff --git a/docs/source/explanation/configuration.md b/docs/source/explanation/configuration.md index 02a7f95..5cc854f 100644 --- a/docs/source/explanation/configuration.md +++ b/docs/source/explanation/configuration.md @@ -28,6 +28,12 @@ The whole configuration follows a single rule: Each configuration item names a Python class in its `class` field. **Every other field of the item is an argument to that class's constructor**, with the same name as the field and the value to be passed to the constructor. ``` +The `class` should be written as a fully qualified Python class path, consisting of the module and class name in the format `package.module.Class`. + +```{note} +Since `class` is a reserved name in Python, the attribute is called `class_path` in the source code. That is also an accepted alias to use in the configuration. +``` + When pyAML reads an item, it imports the class given by `class` and calls it with the remaining fields as keyword arguments. The YAML configuration and Python code below build equivalent objects: **Configuration** @@ -62,27 +68,6 @@ Consequences of this rule: - **Optional arguments are optional fields.** Arguments with a default value can be left out. - **Any class can be used.** Nothing is specific to pyAML classes: a facility-specific class from your own package can be used in the same way, as long as it can be imported. -## Configuration Items - -Each configurable item is represented by a mapping which describes the attributes and values needed to construct one Python object. The field `class` (or its alias `class_path`) identifies the type to construct. It should be written as a fully qualified Python class path, consisting of the module and class name. For example: - -```yaml -class: pyaml.magnet.quadrupole.Quadrupole -``` - -When pyAML reads the configuration, it uses this path to select the class and passes the remaining configuration fields to the constructor of the class. - -An object can contain other configurable objects. The nested objects follow the same principle: each has its own `class` field and the values needed to construct it. For example: - -```yaml -class: pyaml.magnet.quadrupole.Quadrupole -name: QF_001 -model: - class: pyaml.magnet.identity_model.IdentityMagnetModel - unit: 1/m - physics: AN01-AR/EM-QP/QF.01/magnetic_strength -``` - ## Separation between Configuration and Source Code The configuration describes what should be constructed; it does not contain executable Python code. This keeps configuration readable, reviewable, and usable by tools such as JSON Schema editors.