From 339f82ee99c343516d06781b94a6e67a7e559bfe Mon Sep 17 00:00:00 2001 From: Eric Fayolle Date: Mon, 2 Dec 2019 11:52:37 +0100 Subject: [PATCH] MAJ doc xsd --- docCataWriter/xsd_mapping.rst | 100 ++++++++++++++++++++++++++++------ 1 file changed, 83 insertions(+), 17 deletions(-) diff --git a/docCataWriter/xsd_mapping.rst b/docCataWriter/xsd_mapping.rst index f268f8bd..5dc71117 100644 --- a/docCataWriter/xsd_mapping.rst +++ b/docCataWriter/xsd_mapping.rst @@ -383,7 +383,9 @@ The *SIMP* declaration is : The *UserASSD* class declared this way is quite the same notion as using an *ASSD* class in an *OPER* command (:ref:`Defining a concept type `). The *UserASSD* differs from an ASSD by : * the *UserASSD* *SIMP* can be declared where ever you like in the catalog (not just at first level like for an *OPER*) - * it is assummed that all the necessary data for contructing objects of *UserASSD* type are declared in the catalog ( objects of *ASSD* are assumed to be created thanks to the help of some *OPER* parameters but not exactly with that paramters... ) + * the generated python code (.comm) will call the object constructor of the *UserASSD* type with no parameter + +.. todo:: Expliciter le mécanisme en oeuvre au niveau python. You get the xsd type : @@ -485,7 +487,7 @@ The root element declaration is : The name of the element comes from the *code* parameter previously defined. You find all the element declarations that come from all the *PROC* / *OPER* declared in the catalog. -.. note:: For generate drivers with PyXB, it's a really bad idea to define xsd **element** with **maxOccurs** > 1 in a **xs:choice** with a **maxOccurs** == 'unbounded'. Despite the generate code is correct, it produce a python class unusable since the PyXB Finite Automate with Counter can't decide from which schema component two elements of the same type comes from. This ambighuity interrupt the xml mapping of your python object. +.. note:: For generate drivers with PyXB, it's a really bad idea to define xsd **element** with **maxOccurs** > 1 in a **xs:choice** with a **maxOccurs** == 'unbounded'. Despite the generate code is correct, it produce a python class unusable since the PyXB Finite Automate with Counter can't decide from which schema component two elements of the same type comes from. This ambighuity interrupt the xml production from your python object. .. note:: TODO : We have to explain the way we use the schema namespaces. @@ -493,7 +495,13 @@ The OPER command ~~~~~~~~~~~~~~~~ -The *OPER* command returns an *ASSD* type (not a *UserASSD* ). An *ASSD* type provides the ability to declare and use a new class in a eficas catalog. After having declared the new typename *ASSD* : +The *OPER* command returns an *ASSD* type (not a *UserASSD*). +An *ASSD* type provides the ability to declare and use a user class in a eficas catalog. + +Producing an *ASSD* : +^^^^^^^^^^^^^^^^^^^^^ + +After having declared the new typename *ASSD* : .. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py :language: python @@ -504,7 +512,7 @@ The *OPER* command describes a way to create user type instances : .. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py :language: python - :start-at: ConstructMesh + :start-at: ReadMesh :end-at: ,) @@ -512,7 +520,7 @@ You get the xsd type : .. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd :language: xml - :start-at: name="T_ConstructMesh" + :start-at: name="T_ReadMesh" :end-at: /xs:complexType .. note:: @@ -524,10 +532,13 @@ The element declaration is : .. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd :language: xml :dedent: 2 - :start-at: name="ConstructMesh" - :end-at: name="ConstructMesh" + :start-at: name="ReadMesh" + :end-at: name="ReadMesh" -If you want to declare in the catalog that a specific data of the dataset is a reuse of an already produced data by an *OPER*, you have to declare it within an SIMP. This SIMP must have the *typ* attribute equals to the *sd_prod* attribute value of the corresponding *OPER* : +Using an already produced *ASSD* object : +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to declare in a catalog that a specific data of the dataset is a reuse of an already produced data by an *OPER*, you have to declare it within an SIMP. This SIMP must have the *typ* attribute equals to the *sd_prod* attribute value of the corresponding *OPER* : .. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py :language: python @@ -559,7 +570,7 @@ Concerning the element declaration : :start-at: name="MyField" :end-at: name="MyField" -The way we choose to map the *OPER* to xsd allows users to create a cross reference system using name of producted structure in their dataset. +The way we choose to map the *OPER* to xsd allows users to create a cross reference system using name of produced structure in their dataset. .. todo:: : Generate a schema validation rule to check that a name used as a reference is unique and exists in the corresponding object, we have to add in the root element declaration the following code : @@ -575,7 +586,7 @@ The way we choose to map the *OPER* to xsd allows users to create a cross refere -.. note:: PyXB doesn't care about these rules, it relies on the sax/dom parsers capabilities. By default, using the libxml library, these checks are not perform. Anyway it's always possible to fully validate xml datasets by using a parser which have this kind of capability. +.. note:: PyXB doesn't care about these rules, it relies on the sax/dom parsers capabilities. By default, using the libxml library, these checks are not performed. Anyway it's always possible to fully validate xml datasets by using a parser which have this kind of capability. .. todo:: PyXB doesn't automaticaly create links between the objects using the ref name contract. Either the user have to recrate the links or we have to provide a PyXB extension to do so. @@ -606,29 +617,29 @@ And the element declaration : :start-at: name="Test_proc_2" :end-at: name="Test_proc_2" -Using an SIMP UserASSD in a PROC or a FACT -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Declaring an SIMP of type UserASSD in a PROC or a FACT : +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Here is a *PROC* declaration using an SIMP UserASSD : .. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py :language: python - :start-at: class MeshBis - :end-at: class MeshBis + :start-at: class MeshU + :end-at: class MeshU .. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py :language: python :start-at: Meshes :end-at: #Meshes - -You get the xsd type : + +You get the *PROC* xsd type : .. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd :language: xml :start-at: name="T_Meshes" :end-at: /xs:complexType -And the element declaration : +And the associated element declaration : .. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd :language: xml @@ -636,7 +647,62 @@ And the element declaration : :start-at: name="Meshes" :end-at: name="Meshes" +.. todo:: We will have an eficas *xsdattribute* attribute to get the *SIMP* as an xsd attribute instead of an xsd element + +Concerning the *FACT* xsd type, you get : + +.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd + :language: xml + :start-at: name="T_mesh" + :end-at: /xs:complexType + +The *SIMP* of UserASSD type becomes : + +.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd + :language: xml + :start-at: name="T_name" + :end-at: /xs:simpleType + +Using an already defined SIMP of type UserASSD : +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you want to declare somewhere in a catalog that a specific data is a reuse of an already defined *UserASSD* *SIMP* data, you have to declare it within an SIMP of type *UserASSD* thanks to the *typ* attribute : + +.. literalinclude:: ../Tests/MappingAccasXsd/cata_1.py + :language: python + :start-at: MyFieldBis + :end-at: ,) + +.. note:: Note that this is exactly the same as using an *ASSD* provided by an *OPER*. + +You get the xsd types : + +.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd + :language: xml + :start-at: name="T_MyFieldBis" + :end-at: /xs:complexType + +and + +.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd + :language: xml + :start-at: name="T_onMesh_1" + :end-at: /xs:simpleType + + +Concerning the element declaration, you get : + +.. literalinclude:: ../Tests/MappingAccasXsd/cata_1_genere.xsd + :language: xml + :dedent: 2 + :start-at: name="MyFieldBis" + :end-at: name="MyFieldBis" + +.. note:: The string **onMesh** element value must be a valid name of a **name** element value from a **mesh** element. + +.. todo:: We have to write a rule to check this. + Understanding the XSD mapping for FACT and BLOC ________________________________________________ -- 2.39.2