family in turorial
This commit is contained in:
gwen
parent
eda0632809
commit
04f30963f4
3 changed files with 114 additions and 73 deletions
|
|
@ -9,20 +9,19 @@ Here's a quite well supplied tutorial, we're gonna start with a use case that co
|
|||
"how to set a proxy" in the `Mozilla Firefox <https://www.mozilla.org/en-US/firefox/new/>`_ browser
|
||||
use case.
|
||||
|
||||
More precisely, this tutorial aims at reproducing :term:`variable`\ s (that is, configuration options) behind this Mozilla Firefox settings page:
|
||||
More precisely, this tutorial aims at reproducing :term:`variable`\ s (in this use case we will call them configuration options) behind this Mozilla Firefox settings page:
|
||||
|
||||
.. image:: images/firefox.png
|
||||
|
||||
.. attention:: We are not coding a firefox plugin here.
|
||||
.. note:: We are not coding a firefox plugin here.
|
||||
We are just going to handle some of the firefox configuration settings
|
||||
with Rougail.
|
||||
|
||||
|
||||
Presentation of the firefox configuration variables
|
||||
Presentation of the firefox option configuration variables
|
||||
-----------------------------------------------------------
|
||||
|
||||
Let's dive into the configuration validation use case,
|
||||
that is the values entered by the user that have to be validated.
|
||||
Let's dive into this configuration validation use case.
|
||||
The values entered by the user that have to be validated.
|
||||
|
||||
At first glance we have a selection of five options configuration values that we need to fill in:
|
||||
|
||||
|
|
|
|||
|
|
@ -86,14 +86,14 @@ So, if :
|
|||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The :file:`struct/config.yaml` rougail structure file, with no default value set.
|
||||
:caption: The :file:`firefox/00-proxy.yaml` rougail structure file, with no default value set.
|
||||
:name: RougailDictionaryNoDefault
|
||||
|
||||
..
|
||||
---
|
||||
proxy_mode:
|
||||
|
||||
In this situation there are no default value set. The rougail CLI will output an error :
|
||||
Then the rougail CLI will output an error :
|
||||
|
||||
.. code-block:: shell
|
||||
:caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` rougail dictionnary file
|
||||
|
|
@ -111,16 +111,21 @@ In this situation there are no default value set. The rougail CLI will output an
|
|||
|
||||
.. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
|
||||
|
||||
Rougail waits for a value to be set, that's why.
|
||||
Rougail waits for the `proxy_mode` configuration option's value to be set.
|
||||
|
||||
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` Tiramisu's definition.
|
||||
|
||||
Type inference
|
||||
.. glossary::
|
||||
|
||||
mandatory
|
||||
|
||||
A variable is mandatory when a value is required, that is, `None` is not an option.
|
||||
|
||||
Typing a variable
|
||||
-----------------
|
||||
|
||||
By default, rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined
|
||||
in the structure file.
|
||||
.
|
||||
If the `type` attribute is not set, rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.
|
||||
|
||||
If the operator sets an option value for example with the `number` type, like this:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -133,10 +138,10 @@ If the operator sets an option value for example with the `number` type, like th
|
|||
Then rougail will expect a `int` or a `float` as a value for the `example_var` variable.
|
||||
In our firefox use case, the real type of the `proxy_mode` variable is a `choice` type:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/05/config.yaml
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: The :file:`config/05/config.yaml` rougail dictionnary file, with a default value set.
|
||||
:caption: The :file:`firefox/00-proxy.yml` rougail dictionnary file, with a default value set.
|
||||
:name: RougailDictionaryChoiceTypeWitheDefault
|
||||
|
||||
..
|
||||
|
|
@ -166,6 +171,33 @@ In our firefox use case, the real type of the `proxy_mode` variable is a `choice
|
|||
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
|
||||
</pre>
|
||||
|
||||
The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable.
|
||||
|
||||
It shall have a value, but what if the user *does not* specify any value?
|
||||
There is a possibility of setting a default value, wich is set as `No proxy` by default.
|
||||
|
||||
Container type
|
||||
-----------------
|
||||
|
||||
We say that the `proxy_mode` variable is *constrained* (by the `choice` type).
|
||||
|
||||
We have the list of the possible (authorized) values:
|
||||
|
||||
- `No proxy`
|
||||
- `Auto-detect proxy settings for this network`
|
||||
- `Use system proxy settings`
|
||||
- `Manual proxy configuration`
|
||||
- `Automatic proxy configuration URL`
|
||||
|
||||
.. glossary::
|
||||
|
||||
choice type
|
||||
|
||||
The `proxy_mode` setting is "choice" (`type: choice`) means that
|
||||
there is a list of available values that can be selected.
|
||||
|
||||
.. note:: Indeed, in the Firefox configuration, it is possible to define several configuration modes,
|
||||
from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`).
|
||||
|
||||
.. keypoints:: Key points progress
|
||||
|
||||
|
|
@ -178,6 +210,7 @@ In our firefox use case, the real type of the `proxy_mode` variable is a `choice
|
|||
- a variable's default value
|
||||
- the :term:`integrator` and :term:`operator` roles
|
||||
- a mandatory value
|
||||
- a choice type
|
||||
|
||||
To sum up, we have arrived at this point in writing the structure file:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,25 +1,35 @@
|
|||
Firefox tutorial: the `mode_proxy` variable
|
||||
------------------------------------------------
|
||||
|
||||
The `proxy` family
|
||||
-------------------
|
||||
====================
|
||||
|
||||
Let's create our first :term:`dictionary`.
|
||||
|
||||
.. prerequisites:: Let's create a folder named `dict` and a dictionary file inside
|
||||
.. objectives:: Objectives
|
||||
|
||||
We will put our dictionary files in this folder.
|
||||
We will learn how to:
|
||||
|
||||
Then let's put our first dictionary file in this folder, named :file:`00-proxy.yml`
|
||||
- create a :term:`family`
|
||||
- gather variables into a family
|
||||
- make a variable in a variable, which is a family too
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: the :file:`00-proxy.yml` file
|
||||
|
||||
.. type-along:: Reminders
|
||||
|
||||
- As a prerequisite we have an idea of what a :term:`structure file description <dictionary>` is.
|
||||
- We have a :file:`firefox` folder and we are putting all the structure description files in it.
|
||||
- We had at the :term:`structure description file <structure file>`
|
||||
|
||||
A `manual` family
|
||||
--------------------
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: A family structure file description named `manual` in the :file:`firefox/10-manual.yml` file
|
||||
:name: RougailFirstDictionary
|
||||
|
||||
..
|
||||
---
|
||||
version: '1.1'
|
||||
proxy:
|
||||
description: Proxy configuration in order to have access to the internet
|
||||
manual:
|
||||
description: Manual proxy configuration
|
||||
type: family
|
||||
|
||||
We can see that we have defined a :term:`family` here, and this family is *empty*
|
||||
|
|
@ -27,67 +37,66 @@ We can see that we have defined a :term:`family` here, and this family is *empty
|
|||
|
||||
.. admonition:: If a family is empty
|
||||
|
||||
We need to specify the :term:`family` type (line 5) here because if we don't,
|
||||
We need to specify the :term:`family` type here because if we don't,
|
||||
the Rougail's type engine will infer it by default as a :term:`variable`.
|
||||
|
||||
It's because we don't have set any :term:`variable` inside.
|
||||
It's because we don't have set any :term:`variable` inside. If we make a YAML block
|
||||
(that is, if we indent), the Rougail's type inference engine will implicitely make it a family.
|
||||
|
||||
|
||||
.. note:: The variables will be created in several files for educational purposes.
|
||||
.. note:: The variables, families, etc. will be created in several files for educational purposes.
|
||||
Obviously all the variables can be put in the same file.
|
||||
|
||||
A family inside a family
|
||||
----------------------------
|
||||
|
||||
The proxy's configuration type
|
||||
----------------------------------
|
||||
Creating a family hierarchy is very easy, here is an example
|
||||
|
||||
In the Firefox configuration, it is possible to define several configuration modes,
|
||||
from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`).
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: A rougail structure description file with a hierarchy.
|
||||
:name: RougailFirstFamilyHierarchy
|
||||
|
||||
..
|
||||
---
|
||||
manual:
|
||||
description: Manual proxy configuration
|
||||
type: family
|
||||
|
||||
http_proxy:
|
||||
description: HTTP Proxy
|
||||
type: family
|
||||
|
||||
Here the `http_proxy` family lives inside the `manual` family.
|
||||
|
||||
Put a variable inside a family or a sub family
|
||||
--------------------------------------------------
|
||||
|
||||
Let's create a variable in its family with a description and a default value.
|
||||
The type of this variable is a `choice` type:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_006/firefox/00-proxy.yml
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml
|
||||
:linenos:
|
||||
:language: yaml
|
||||
:caption: A rougail dictionnary file with a choice variable named `proxy_mode`, with a default value and a description.
|
||||
:name: RougailDictionaryFirstVariableChoiceType
|
||||
:caption: An `address` variable in the `http_proxy` family
|
||||
:name: RougailVariableInSubFamily
|
||||
|
||||
.. glossary::
|
||||
..
|
||||
---
|
||||
manual:
|
||||
description: Manual proxy configuration
|
||||
type: family
|
||||
|
||||
mandatory
|
||||
http_proxy:
|
||||
description: HTTP Proxy
|
||||
type: family
|
||||
|
||||
A variable is mandatory when a value is required, that is, `None` is not an option.
|
||||
address:
|
||||
description: HTTP address
|
||||
|
||||
The `proxy_mode` variable here, implicitely requires a value. It is a mandatory variable.
|
||||
.. keypoints:: Key points progress
|
||||
|
||||
It shall have a value, but what if the user *does not* specify any value?
|
||||
There is a possibility of setting a default value, wich is set as `No proxy` by default.
|
||||
|
||||
.. glossary::
|
||||
|
||||
choice type
|
||||
|
||||
The `proxy_mode` setting is "choice" (`type: choice`) means that
|
||||
there is a list of available values that can be selected.
|
||||
|
||||
We say that the `proxy_mode` variable is *constrained* (by the `choice` type).
|
||||
|
||||
We have the list of the possible (authorized) values:
|
||||
|
||||
- `No proxy`
|
||||
- `Auto-detect proxy settings for this network`
|
||||
- `Use system proxy settings`
|
||||
- `Manual proxy configuration`
|
||||
- `Automatic proxy configuration URL`
|
||||
|
||||
Now let's test our first two dictionaries:
|
||||
|
||||
>>> from rougail import Rougail, RougailConfig
|
||||
>>> from pprint import pprint
|
||||
>>> RougailConfig['dictionaries_dir'] = ['dict']
|
||||
>>> rougail = Rougail()
|
||||
>>> config = rougail.get_config()
|
||||
>>> config.property.read_only()
|
||||
>>> pprint(config.value.get(), sort_dicts=False)
|
||||
{'rougail.proxy.proxy_mode': 'No proxy'}
|
||||
**Keywords**
|
||||
|
||||
- :term:`family`, and sub families
|
||||
- variables defined in a family
|
||||
|
|
|
|||
Loading…
Reference in a new issue