Difference between revisions of "Scripted objects saving attributes/fr"

From FreeCAD Documentation
Jump to navigation Jump to search
(Created page with "Objets scriptés enregistrant des attributs")
 
(Created page with "* [https://forum.freecadweb.org/viewtopic.php?f=18&t=44009 obj.Proxy.Type est un dict, pas une chaîne de caractères], explication de {{incode|__getstate__}} et {{incode|__se...")
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
<languages/>
 
<languages/>
 +
 +
{{TOCright}}
  
 
== Introduction ==
 
== Introduction ==
  
[[Scripted_objects|Scripted objects]] are rebuilt every time a [[File_Format_FCStd|FCStd document]] is opened. To do this the document keeps a reference to the module and Python class that were used to create the object, along with its properties.
+
Les [[Scripted_objects/fr|Objets créés par script]] sont reconstruits à chaque fois qu'un [[File_Format_FCStd/fr|document au format FCStd]] est ouvert. Pour ce faire, le document conserve une référence au module et à la classe Python qui ont été utilisés pour créer l'objet, ainsi que ses propriétés.
  
Attributes of the class used to create the object can also be saved, that is, "serialized". This can be further controlled by the {{incode|__getstate__}} and {{incode|__setstate__}} methods of the class.
+
Les attributs de la classe utilisée pour créer l'objet peuvent également être enregistrés, c'est-à-dire "sérialisés". Ceci peut être contrôlé par les méthodes {{incode|__getstate__}} et {{incode|__setstate__}} de la classe.
  
== Saving all attributes ==
+
== Sauvegarde de tous les attributs ==
  
By default, attributes saved in an object class are those from the {{incode|__dict__}} dictionary of the class.
+
Par défaut, les attributs enregistrés dans une classe d'objets sont ceux du dictionnaire {{incode|__dict__}} de la classe.
  
 
{{Code|code=
 
{{Code|code=
Line 34: Line 36:
 
}}
 
}}
  
An object can be created using this class, and it can be saved to {{FileName|my_document.FCstd}}. If no particular [[viewprovider|viewprovider]] is assigned to the new object, its proxy class is simply set to a value different from {{incode|None}}, in this case, to {{incode|1}}.
+
Un objet peut être créé à l'aide de cette classe et il peut être enregistré dans {{FileName|my_document.FCstd}}. Si aucun [[viewprovider/fr|viewprovider]] particulier n'est attribué au nouvel objet, sa classe proxy est simplement définie sur une valeur différente de {{incode|None}}, dans ce cas, sur {{incode|1}}.
 
{{Code|code=
 
{{Code|code=
 
import FreeCAD as App
 
import FreeCAD as App
Line 52: Line 54:
 
}}
 
}}
  
When we re-open the file we can inspect the dictionary of the object's class.
+
Lorsque nous rouvrons le fichier, nous pouvons inspecter le dictionnaire de la classe de l'objet.
 
{{Code|code=
 
{{Code|code=
 
>>> obj = App.ActiveDocument.Custom
 
>>> obj = App.ActiveDocument.Custom
Line 61: Line 63:
 
}}
 
}}
  
We see that all attributes that start with {{incode|self}} in the class were saved. These can be of different types, including string, list, float, and dictionary. The original tuple for {{incode|self.color}} was converted to a list, but otherwise all attributes were loaded the same.
+
Nous voyons que tous les attributs qui commencent par {{incode|self}} dans la classe ont été sauvegardés. Ceux-ci peuvent être de différents types, notamment chaîne de caractères, liste, flottant et dictionnaire. Le tuple original pour {{incode|self.color}} a été converti en liste, mais sinon tous les attributs ont été chargés de la même manière.
  
== Saving specific attributes ==
+
== Sauvegarde d'attributs spécifiques ==
  
We can define a class similar to the first one, that implements specific attributes to save.
+
Nous pouvons définir une classe similaire à la première, qui implémente des attributs spécifiques à sauvegarder.
 
{{Code|code=
 
{{Code|code=
 
# various_states.py
 
# various_states.py
Line 95: Line 97:
 
}}
 
}}
  
The return value of {{incode|__getstate__}} is the object that will be serialized. This can be a single value, or a tuple of values. When the object is restored, the class calls the {{incode|__setstate__}} method, passing the {{incode|state}} variable with the serialized content. In this case {{incode|state}} is a tuple that is unpacked into the respective variables to reconstruct the "state" that original existed.
+
La valeur de retour de {{incode|__getstate__}} est l'objet qui sera sérialisé. Il peut s'agir d'une valeur unique ou d'un tuple de valeurs. Lorsque l'objet est restauré, la classe appelle la méthode {{incode|__setstate__}}, en passant la variable {{incode|state}} avec le contenu sérialisé. Dans ce cas, {{incode|state}} est un tuple qui est décomposé dans les variables respectives pour reconstruire l'"état" qui existait à l'origine.
 
{{Code|code=
 
{{Code|code=
 
state = (self.color, self.width)
 
state = (self.color, self.width)
Line 101: Line 103:
 
}}
 
}}
  
We can create an object with this class, and save the document, just like in the previous example. When we re-open the file we can inspect the dictionary of the object's class.
+
Nous pouvons créer un objet avec cette classe et enregistrer le document, comme dans l'exemple précédent. Lorsque nous rouvrons le fichier, nous pouvons inspecter le dictionnaire de la classe de l'objet.
 
{{Code|code=
 
{{Code|code=
 
>>> obj2 = App.ActiveDocument.Custom2
 
>>> obj2 = App.ActiveDocument.Custom2
Line 110: Line 112:
 
}}
 
}}
  
The original tuple for {{incode|self.color}} was converted to a list, but otherwise the information was recovered fine. Instead of restoring all attributes like in the previous case, only the attributes that we specified in {{incode|__getstate__}} and {{incode|__setstate__}} were restored.
+
Le tuple original de {{incode|self.color}} a été converti en liste, mais les autres informations ont été récupérées sans problème. Au lieu de restaurer tous les attributs comme dans le cas précédent, seuls les attributs que nous avons spécifiés dans {{incode|__getstate__}} et {{incode|__setstate__}} ont été restaurés.
  
== Usage ==
+
== Utilisation ==
  
=== Identifying the type ===
+
=== Identifier le type ===
  
Normally, [[scripted_objects|scripted objects]] should use [[property|properties]] to store information, as these are automatically restored when the document is opened.
+
Normalement, les [[scripted_objects/fr|objets créés par script]] devraient utiliser des [[property/fr|propriétés]] pour stocker des informations, car celles-ci sont automatiquement restaurées à l'ouverture du document.
  
However, sometimes the class restore internal information which is not intended to be modified, but which is helpful to inspect.
+
Cependant, il arrive que la classe restitue des informations internes qui ne sont pas destinées à être modifiées, mais qu'il est utile d'inspecter.
  
For example, most objects of the [[Draft_Module|Draft Workbench]] set up a {{incode|Type}} attribute that can be used to determine the type of object that is under use.
+
Par exemple, la plupart des objets de l'[[Draft_Workbench/fr|atelier Draft]] configurent un attribut {{incode|Type}} qui peut être utilisé pour déterminer le type d'objet utilisé.
  
 
{{Code|code=
 
{{Code|code=
Line 135: Line 137:
 
}}
 
}}
  
All objects have a {{incode|TypeId}} property, but for [[scripted_objects|scripted objects]] this property is not useful, as it always refers to the parent C++ class, for example, [[Part_Part2DObject|{{incode|Part::Part2DObjectPython}}]] or [[Part_Feature|{{incode|Part::FeaturePython}}]]. Therefore, having this additional {{incode|Proxy.Type}} attribute in the class is useful to treat each object in a particular way.
+
Tous les objets ont une propriété {{incode|TypeId}}, mais pour les [[scripted_objects/fr|objets créés par script]], cette propriété n'est pas utile car elle fait toujours référence à la classe C++ parente, par exemple, [[Part_Part2DObject/fr|{{incode|Part::Part2DObjectPython}}]] ou [[Part_Feature/fr|{{incode|Part::FeaturePython}}]]. Par conséquent, le fait d'avoir cet attribut supplémentaire {{incode|Proxy.Type}} dans la classe est utile pour traiter chaque objet d'une manière particulière.
  
=== Migrating the object ===
+
=== Migration de l'objet ===
  
Version information can be stored inside the class in order to verify the origin of an object.
+
Les informations de version peuvent être stockées à l'intérieur de la classe afin de vérifier l'origine d'un objet.
  
 
{{Code|code=
 
{{Code|code=
Line 156: Line 158:
 
}}
 
}}
  
If the structure of the class changes, that is, if its properties or methods change, are renamed, or are removed, we could test the version attribute in order to migrate the older object to a new set of properties or to a new class. This can be done by implementing the {{incode|onDocumentRestored}} method, as explained in [[Scripted_objects_migration|Scripted objects migration]].
+
Si la structure de la classe change, c'est-à-dire si ses propriétés ou méthodes changent, sont renommées ou supprimées, nous pourrions tester l'attribut version afin de faire migrer l'ancien objet vers un nouvel ensemble de propriétés ou vers une nouvelle classe. Ceci peut être fait en implémentant la méthode {{incode|onDocumentRestored}}, comme expliqué dans [[Scripted_objects_migration/fr|Migration d'objets créés par script]].
  
 
{{Code|code=
 
{{Code|code=
Line 169: Line 171:
 
}}
 
}}
  
== Links ==
+
== Liens ==
 +
 
 +
* [[Scripted_objects/fr|Objets créés par script]]
 +
* [[Scripted_objects_migration/fr|Migration d'objets créés par script]]
 +
* [https://forum.freecadweb.org/viewtopic.php?f=10&t=49120 Discussion sur le forum FreeCAD : Sérialisation des objets scripts : json ou pickle ?]
  
* [[Scripted_objects|Scripted objects]]
+
* [https://forum.freecadweb.org/viewtopic.php?f=18&t=44009 obj.Proxy.Type est un dict, pas une chaîne de caractères], explication de {{incode|__getstate__}} et {{incode|__setstate__}} dans le forum.
* [[Scripted_objects_migration|Scripted objects migration]]
+
* [https://docs.python.org/3/library/pickle.html#object.__getstate__ Le module Pickle] dans la documentation Python.
  
* [https://forum.freecadweb.org/viewtopic.php?f=18&t=44009 obj.Proxy.Type is a dict, not a string], explanation of {{incode|__getstate__}} and {{incode|__setstate__}} in the forum.
 
* [https://docs.python.org/3/library/pickle.html#object.__getstate__ The Pickle module] in the Python documentation.
 
 
{{Powerdocnavi{{#translation:}}}}
 
{{Powerdocnavi{{#translation:}}}}
 +
[[Category:Developer Documentation{{#translation:}}]]
 +
[[Category:Python Code{{#translation:}}]]
 +
{{clear}}

Latest revision as of 10:18, 5 December 2021

Other languages:
Deutsch • ‎English • ‎français • ‎italiano • ‎polski • ‎русский

Introduction

Les Objets créés par script sont reconstruits à chaque fois qu'un document au format FCStd est ouvert. Pour ce faire, le document conserve une référence au module et à la classe Python qui ont été utilisés pour créer l'objet, ainsi que ses propriétés.

Les attributs de la classe utilisée pour créer l'objet peuvent également être enregistrés, c'est-à-dire "sérialisés". Ceci peut être contrôlé par les méthodes __getstate__ et __setstate__ de la classe.

Sauvegarde de tous les attributs

Par défaut, les attributs enregistrés dans une classe d'objets sont ceux du dictionnaire __dict__ de la classe.

# various_states.py
class VariousStates:
    def __init__(self, obj):
        obj.addProperty("App::PropertyLength", "Length")
        obj.addProperty("App::PropertyArea", "Area")
        obj.Length = 15
        obj.Area = 300
        obj.Proxy = self

        Type = dict()
        Type["Version"] = "Custom"
        Type["Release"] = "production"
        self.Type = Type
        self.Type = "Custom"
        self.ver = "0.18"
        self.color = (0, 0, 1)
        self.width = 2.5

    def execute(self, obj):
        pass

Un objet peut être créé à l'aide de cette classe et il peut être enregistré dans my_document.FCstd. Si aucun viewprovider particulier n'est attribué au nouvel objet, sa classe proxy est simplement définie sur une valeur différente de None, dans ce cas, sur 1.

import FreeCAD as App
import various_states

doc = App.newDocument()
doc.FileName = "my_document.FCStd"

obj = doc.addObject("Part::FeaturePython", "Custom")
various_states.VariousStates(obj)

if App.GuiUp:
    obj.ViewObject.Proxy = 1

doc.recompute()
doc.save()

Lorsque nous rouvrons le fichier, nous pouvons inspecter le dictionnaire de la classe de l'objet.

>>> obj = App.ActiveDocument.Custom
>>> print(obj.Proxy)
<various_states.VariousStates object at 0x7f0a899bde10>
>>> print(obj.Proxy.__dict__)
{'Type': {'Version': 'Custom', 'Release': 'production'}, 'ver': '0.18', 'color': [0, 0, 1], 'width': 2.5}

Nous voyons que tous les attributs qui commencent par self dans la classe ont été sauvegardés. Ceux-ci peuvent être de différents types, notamment chaîne de caractères, liste, flottant et dictionnaire. Le tuple original pour self.color a été converti en liste, mais sinon tous les attributs ont été chargés de la même manière.

Sauvegarde d'attributs spécifiques

Nous pouvons définir une classe similaire à la première, qui implémente des attributs spécifiques à sauvegarder.

# various_states.py
class CustomStates:
    def __init__(self, obj):
        obj.addProperty("App::PropertyLength", "Length")
        obj.addProperty("App::PropertyArea", "Area")
        obj.Length = 15
        obj.Area = 300
        obj.Proxy = self

        Type = dict()
        Type["Version"] = "Custom"
        Type["Release"] = "production"
        self.Type = Type
        self.ver = "0.18"
        self.color = (0, 0, 1)
        self.width = 2.5

    def execute(self, obj):
        pass

    def __getstate__(self):
        return self.color, self.width

    def __setstate__(self, state):
        self.color = state[0]
        self.width = state[1]

La valeur de retour de __getstate__ est l'objet qui sera sérialisé. Il peut s'agir d'une valeur unique ou d'un tuple de valeurs. Lorsque l'objet est restauré, la classe appelle la méthode __setstate__, en passant la variable state avec le contenu sérialisé. Dans ce cas, state est un tuple qui est décomposé dans les variables respectives pour reconstruire l'"état" qui existait à l'origine.

state = (self.color, self.width)
state = ((0, 0, 1), 2.5)

Nous pouvons créer un objet avec cette classe et enregistrer le document, comme dans l'exemple précédent. Lorsque nous rouvrons le fichier, nous pouvons inspecter le dictionnaire de la classe de l'objet.

>>> obj2 = App.ActiveDocument.Custom2
>>> print(obj2.Proxy)
<various_states.CustomStates object at 0x7fb399496630>
>>> print(obj2.Proxy.__dict__)
{'color': [0, 0, 1], 'width': 2.5}

Le tuple original de self.color a été converti en liste, mais les autres informations ont été récupérées sans problème. Au lieu de restaurer tous les attributs comme dans le cas précédent, seuls les attributs que nous avons spécifiés dans __getstate__ et __setstate__ ont été restaurés.

Utilisation

Identifier le type

Normalement, les objets créés par script devraient utiliser des propriétés pour stocker des informations, car celles-ci sont automatiquement restaurées à l'ouverture du document.

Cependant, il arrive que la classe restitue des informations internes qui ne sont pas destinées à être modifiées, mais qu'il est utile d'inspecter.

Par exemple, la plupart des objets de l'atelier Draft configurent un attribut Type qui peut être utilisé pour déterminer le type d'objet utilisé.

class DraftObject:
    def __init__(self, obj, _type):
        self.Type = _type

    def __getstate__(self):
        return self.Type

    def __setstate__(self, state):
        if state:
            self.Type = state

Tous les objets ont une propriété TypeId, mais pour les objets créés par script, cette propriété n'est pas utile car elle fait toujours référence à la classe C++ parente, par exemple, Part::Part2DObjectPython ou Part::FeaturePython. Par conséquent, le fait d'avoir cet attribut supplémentaire Proxy.Type dans la classe est utile pour traiter chaque objet d'une manière particulière.

Migration de l'objet

Les informations de version peuvent être stockées à l'intérieur de la classe afin de vérifier l'origine d'un objet.

class CustomObject:
    def __init__(self, obj, _type):
        self.Type = _type
        self.version = "0.18"

    def __getstate__(self):
        return self.Type, self.version

    def __setstate__(self, state):
        if state:
            self.Type = state[0]
            self.version = state[1]

Si la structure de la classe change, c'est-à-dire si ses propriétés ou méthodes changent, sont renommées ou supprimées, nous pourrions tester l'attribut version afin de faire migrer l'ancien objet vers un nouvel ensemble de propriétés ou vers une nouvelle classe. Ceci peut être fait en implémentant la méthode onDocumentRestored, comme expliqué dans Migration d'objets créés par script.

class CustomObject:
    def onDocumentRestored(self, obj):
        if hasattr(obj.Proxy, "version") and obj.Proxy.version:
            if obj.Proxy.version == "0.18":
                self.migrate_from_018(obj)

    def migrate_from_018(self, obj):
        ...

Liens