From 4c812ae29906137943e450a30f54c227a162ac1d Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Sat, 13 Jun 2026 21:43:41 +0200 Subject: [PATCH] docs(propertyerror) --- docs/structured_data/data_integrity.rst | 2 + docs/tutorial/index.rst | 1 + docs/tutorial/jinja.rst | 2 + docs/tutorial/propertyerror.rst | 57 +++++++++++++++++++++++++ 4 files changed, 62 insertions(+) create mode 100644 docs/tutorial/propertyerror.rst diff --git a/docs/structured_data/data_integrity.rst b/docs/structured_data/data_integrity.rst index 5197f944f..c8f12daa4 100644 --- a/docs/structured_data/data_integrity.rst +++ b/docs/structured_data/data_integrity.rst @@ -22,6 +22,8 @@ The values of the variables must be individually of good quality. typing variable_validation +.. _access_control: + Access control ~~~~~~~~~~~~~~ diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index e2bdf9d06..c1d0e4225 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -61,6 +61,7 @@ Let's dive into this **configuration options validation** use case. multiple document practice1 + propertyerror practice2 validators namespace diff --git a/docs/tutorial/jinja.rst b/docs/tutorial/jinja.rst index 7fe99fc10..4f859bec1 100644 --- a/docs/tutorial/jinja.rst +++ b/docs/tutorial/jinja.rst @@ -1,3 +1,5 @@ +.. _tutorial_jinja: + Playing with Jinja ==================== diff --git a/docs/tutorial/propertyerror.rst b/docs/tutorial/propertyerror.rst new file mode 100644 index 000000000..74884fcac --- /dev/null +++ b/docs/tutorial/propertyerror.rst @@ -0,0 +1,57 @@ +.. _tutorial_propertyerror: + +The Jinja propertyerror test +============================ + +.. objectives:: Objectives + + In a :ref:`Jinja-type calculation `, it is possible to test if a variable is accessible (there is no :ref:`access_control` problem). + +.. prerequisites:: Prerequisites + + - We assume that Rougail's library is :ref:`installed ` on your computer. + + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. + Each tag corresponds to a stage of progress in the tutorial. + Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. + + If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, + this workshop page corresponds to the tag :tutorial:`v1.1_140 ` in the repository: + + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch --detach v1.1_140 + +For now, the variable `proxy_dns_socks5` defines these access controls as follows: + +- if the `proxy_mode` variable is not set to `"Manual proxy configuration"` +- if socks version is `v4`. + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_131/firefox/55-proxy_dns_socks5.yml + :language: yaml + :caption: The :file:`firefox/55-proxy_dns_socks5.yml` + +In principle it works, but is that really what we want? We mean, do we want to disable it based on the proxy_mode variable? + +No, we actually want to make this variable available if the socks version is accessible and equals v4. + +Disabled a variable when an other variable is disabled +------------------------------------------------------- + +The most suitable syntax in Jinja for checking the status of a variable is to use the `concept of a test `_. + +Rougail offers a custom test that will verify correct access to the variable. + +This test is call `propertyerror`. + +Here is how one could write the Jinja using this feature: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_140/firefox/55-proxy_dns_socks5.yml + :language: yaml + :caption: The :file:`firefox/55-proxy_dns_socks5.yml` structure file with some Jinja code in the `hidden` property + +.. keypoints:: Key points + + We have seen that we can use the test `propertyerror` in Jinja template.