Améliorer la capacité d'héritage de Crue10_tools (#11)

* Améliorer la capacité d'héritage de Crue10_tools

* Ajout préparation version 4.4

* Ensure Python2 compatibility

* Upgrade sphinx docs

* Exception dans FactoryClass

---------

Co-authored-by: Luc DURON <l.duron@cnr.tm.fr>

Author: PierreBalayn

CHANGELOG.md

@@ -2,6 +2,11 @@ Journal des modifications
 =========================
 
 
+## [4.4] - 2025-06-04
+### Nouveautés
+- Améliorer la capacité d'héritage de Crue10_tools (pour `Etude` et `Scenario`)
+
+
 ## [4.3] - 2024-10-02
 ### Corrections
 - Mise à jour des scripts GéoGAMA-Crue (support g1.3)

crue10/etude.py

@@ -12,6 +12,7 @@
 from crue10.scenario import Scenario
 from crue10.sous_modele import SousModele
 from crue10.utils import check_isinstance, ExceptionCrue10, logger, PREFIX
+from crue10.utils.design_patterns import factory_define, factory_make
 
 
 def read_metadata(elt, keys):
@@ -22,6 +23,7 @@ def read_metadata(elt, keys):
     return metadata
 
 
+@factory_define('Etude')                        # Cette classe pourra être appelée par factory_make('Etude')
 class Etude(EnsembleFichiersXML):
     """
     Étude Crue10
@@ -251,7 +253,7 @@ def _read_etu(self):
                         raise NotImplementedError  # A single Modele for a Scenario!
 
                 metadata = read_metadata(elt_scenario, Scenario.METADATA_FIELDS)
-                scenario = Scenario(nom_scenario, modele, files=files, metadata=metadata,
+                scenario = factory_make('Scenario')(nom_scenario, modele, files=files, metadata=metadata,
                                     version_grammaire=self.version_grammaire)
 
                 runs = elt_scenario.find(PREFIX + 'Runs')
@@ -421,7 +423,7 @@ def create_empty_scenario(self, nom_scenario, nom_modele, nom_sous_modele=None,
                         version_grammaire=version_grammaire)
         if nom_sous_modele is not None:
             modele.create_empty_sous_modele(nom_sous_modele, self.mode, metadata=metadata)
-        scenario = Scenario(nom_scenario, modele, mode=self.mode, metadata=metadata,
+        scenario = factory_make('Scenario')(nom_scenario, modele, mode=self.mode, metadata=metadata,
                             version_grammaire=version_grammaire)
         self.ajouter_scenario(scenario)
         if not self.nom_scenario_courant:
@@ -597,7 +599,7 @@ def ajouter_scenario_par_copie(self, nom_scenario_source, nom_scenario_cible, ov
             out_path = os.path.join(self.folder, nom_scenario_cible[3:] + '.' + xml_type + '.xml')
             copyfile(in_path, out_path)
             scenario_files[xml_type] = out_path  # overwrite Scenario file path
-        scenario = Scenario(nom_scenario_cible, scenario_ori.modele, mode='w',
+        scenario = factory_make('Scenario')(nom_scenario_cible, scenario_ori.modele, mode='w',
                             files=scenario_files, metadata=scenario_ori.metadata)
         scenario.read_all()
         if overwrite and scenario.id in self.scenarios:

crue10/scenario/__init__.py

@@ -16,6 +16,7 @@
     duration_iso8601_to_seconds, duration_seconds_to_iso8601, \
     ExceptionCrue10, extract_pdt_from_elt, get_optional_commentaire, get_xml_root_from_file, \
     JINJA_ENV, logger, parse_loi, PREFIX, write_default_xml_file, write_xml_from_tree, DATA_FOLDER_ABSPATH
+from crue10.utils.design_patterns import factory_define, factory_make
 from crue10.utils.crueconfigmetier import CCM_FILE
 from crue10.utils.settings import CRUE10_EXE_PATH
 from crue10.utils.sorties import Sorties
@@ -99,6 +100,7 @@ def get_pdt_res_in_iso8601(self):
             return res
 
 
+@factory_define('Scenario')                     # Cette classe pourra être appelée par factory_make('Scenario')
 class Scenario(EnsembleFichiersXML):
     """
     Scénario Crue10
@@ -207,8 +209,8 @@ def ajouter_loi_hydraulique(self, loi_hydraulique):
         """
         Ajouter une loi hydraulique au scénario
 
-        :param run: loi hydraulique à ajouter
-        :type run: LoiHydraulique
+        :param loi_hydraulique: loi hydraulique à ajouter
+        :type loi_hydraulique: LoiHydraulique
         """
         check_isinstance(loi_hydraulique, LoiHydraulique)
         self.lois_hydrauliques[loi_hydraulique.id] = loi_hydraulique
@@ -751,13 +753,13 @@ def create_and_launch_new_run(self, etude, run_id=None, exe_path=CRUE10_EXE_PATH
         run.launch_services(Run.SERVICES, exe_path=exe_path)
         return run
 
-    def create_and_launch_new_multiple_sequential_runs(self, modifications_liste, etude,
-                                                       exe_path=CRUE10_EXE_PATH, force=False):
+    def create_and_launch_new_multiple_sequential_runs(
+            self, modifications_liste, etude, exe_path=CRUE10_EXE_PATH, force=False):
         """
         Créer et lancer des runs séquentiels selon les modifications demandées
 
-        :param modifications: liste avec les dictionnaires contenant les modifications
-        :type modifications: list(dict(str))
+        :param modifications_liste: liste avec les dictionnaires contenant les modifications
+        :type modifications_liste: list(dict(str))
         :param etude: étude courante
         :type etude: Etude
         :param exe_path: chemin vers l'exécutable crue10.exe

crue10/utils/design_patterns.py

@@ -0,0 +1,91 @@
+# coding: utf-8
+
+"""
+Ensemble d'utilitaires mettant en œuvre divers design patterns.
+- Singleton
+- Factory
+© CNR
+PBa 2025-06 Création
+"""
+from future.utils import with_metaclass  # python2 compatibility
+from crue10.utils import ExceptionCrue10
+
+
+class Singleton(type):
+    """ Classe à utiliser comme une métaclasse pour mettre en œuvre le design pattern Singleton.
+    Cela permet d'instancier une classe à divers endroits du code, en n'en ayant qu'une seule et unique instance.
+    """
+    # Variable de classe: dictionnaire des instances {}
+    _dic_nom_obj = {}
+
+    def __call__(cls, *args, **kwargs):
+        """ Fournir une instance de la classe, en la créant seulement la première fois.
+        """
+        if cls not in cls._dic_nom_obj:
+            cls._dic_nom_obj[cls] = super(Singleton, cls).__call__(*args, **kwargs)  # Appeler le constructeur, une fois
+        return cls._dic_nom_obj[cls]            # Renvoyer une instance déjà créée
+
+
+class FactoryClass(with_metaclass(Singleton)):
+    """ Classe utilitaire mettant en œuvre le design pattern Factory.
+    Cela permet de récupérer une classe associée à un nom, pour ensuite l'instancier en late binding. On peut ainsi
+    spécialiser une classe de Crue10_tools dans un autre package, sans toucher à Crue10_tools.
+    Ensemble cohérent: 'FactoryClass', 'factory_define', 'factory_make' (les deux fonctions constituent l'interface).
+    """
+    # Variable de classe: dictionnaire d'association {nom_cls: cls}
+    _dic_nom_cls = {}
+
+    def define(self, nom_cls, cls):
+        """ Définir une association entre un nom et une classe.
+
+        :param nom_cls: nom associé
+        :type nom_cls: str
+        :param cls: classe à utiliser
+        :type cls: callable
+        """
+        # print(f"Définir '{nom_cls}' comme {cls}")
+        self._dic_nom_cls[nom_cls] = cls
+
+    def make(self, nom_cls):
+        """ Fournir la classe à partir du nom qui lui est associé.
+
+        :param nom_cls: nom associé
+        :type nom_cls: str
+        :return: classe à utiliser
+        """
+        if nom_cls in self._dic_nom_cls:
+            # print(f"Utiliser '{nom_cls}' comme {self._dic_nom_cls.get(nom_cls)}")
+            return self._dic_nom_cls[nom_cls]
+        else:
+            raise ExceptionCrue10("Le nom `%s` est inconnu de FactoryClass (pas de @factory_define associé)" % nom_cls)
+
+
+def factory_define(nom_cls):
+    """ Décorateur qui associe le nom passé en paramètre à la classe décorée; pour ensuite utiliser 'factory'.
+    Ensemble cohérent: 'FactoryClass', 'factory_define', 'factory_make'.
+
+    :param nom_cls: nom associé à la classe
+    :type nom_cls: str
+    """
+    def decorator(cls):
+        """ Récupérer la classe décorée pour pouvoir l'utiliser via 'factory'.
+
+        :param cls: classe décorée
+        :return: classe définie
+        :rtype: callable
+        """
+        FactoryClass().define(nom_cls, cls)     # Mémoriser l'association entre nom_cls et cls
+        return cls
+    return decorator
+
+
+def factory_make(nom_cls):
+    """ Renvoyer la classe associée à un nom; utiliser le décorateur '@factory_define' sur la classe pour l'associer.
+    Ensemble cohérent: 'FactoryClass', 'factory_define', 'factory_make'.
+    Exemple d'utilisation: etu = factory_make('Etude')(etu_path=r"path/to/Etu_XX.etu.xml")
+
+    :param nom_cls: nom associé à la classe à renvoyer
+    :return: classe associée
+    :rtype: callable
+    """
+    return FactoryClass().make(nom_cls)

docs/conf.py

@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Crue10_tools'
-copyright = '2024, CNR-Engineering'
+copyright = '2025, CNR-Engineering'
 author = 'CNR-Engineering'
 
 

docs/crue10.base.rst

@@ -6,6 +6,6 @@ Module contents
 
 .. automodule:: crue10.base
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:

docs/crue10.emh.rst

@@ -9,41 +9,41 @@ crue10.emh.branche module
 
 .. automodule:: crue10.emh.branche
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:
 
 crue10.emh.casier module
 ------------------------
 
 .. automodule:: crue10.emh.casier
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:
 
 crue10.emh.noeud module
 -----------------------
 
 .. automodule:: crue10.emh.noeud
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:
 
 crue10.emh.section module
 -------------------------
 
 .. automodule:: crue10.emh.section
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:
 
 Module contents
 ---------------
 
 .. automodule:: crue10.emh
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members:

docs/crue10.rst

@@ -5,6 +5,7 @@ Subpackages
 -----------
 
 .. toctree::
+   :maxdepth: 4
 
    crue10.base
    crue10.emh
@@ -15,39 +16,47 @@ Subpackages
 Submodules
 ----------
 
+crue10.campagne\_otfa module
+----------------------------
+
+.. automodule:: crue10.campagne_otfa
+   :members:
+   :show-inheritance:
+   :special-members: __init__
+   :undoc-members:
+
 crue10.etude module
 -------------------
 
 .. automodule:: crue10.etude
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:
 
 crue10.modele module
 --------------------
 
 .. automodule:: crue10.modele
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:
 
 crue10.sous\_modele module
 --------------------------
 
 .. automodule:: crue10.sous_modele
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
-
+   :undoc-members:
 
 Module contents
 ---------------
 
 .. automodule:: crue10
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:

docs/crue10.run.rst

@@ -4,30 +4,29 @@ crue10.run package
 Submodules
 ----------
 
-crue10.run.resultats_calcul module
--------------------------
+crue10.run.resultats\_calcul module
+-----------------------------------
 
 .. automodule:: crue10.run.resultats_calcul
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:
 
 crue10.run.trace module
 -----------------------
 
 .. automodule:: crue10.run.trace
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
-
+   :undoc-members:
 
 Module contents
 ---------------
 
 .. automodule:: crue10.run
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:

docs/crue10.scenario.rst

@@ -9,25 +9,24 @@ crue10.scenario.calcul module
 
 .. automodule:: crue10.scenario.calcul
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members:
 
 crue10.scenario.loi\_hydraulique module
 ---------------------------------------
 
 .. automodule:: crue10.scenario.loi_hydraulique
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
-
+   :undoc-members:
 
 Module contents
 ---------------
 
 .. automodule:: crue10.scenario
    :members:
-   :undoc-members:
    :show-inheritance:
    :special-members: __init__
+   :undoc-members: