Editor

Synthèse

La classe Editor permet d’utiliser les sessions et opérations de mise à jour pour gérer les transactions de base de données.

Les mises à jour font l’objet d’une gestion intermédiaire et ne sont pas validées dans les données tant que le déclenchement n’a pas eu lieu. Cela permet de mieux contrôler la présence d’erreurs dans une ou plusieurs opérations de mise à jour.

Discussion

Les sessions et opérations de mise à jour offrent les bénéfices suivants :

• Mises à jour de groupe dans les transactions atomiques. Si une erreur se produit avant que toutes les mises à jour ne soient effectuées, les mises à jour peuvent être ignorées et la transaction annulée.
• Les piles d’opérations Annuler et Rétablir de mise à jour facultative sont gérées par la géodatabase. Lorsqu'une opération de mise à jour est stoppée, elle est placée dans la pile d'opérations d'annulation. Il est possible de traverser les piles d’opérations Annuler et Rétablir en appelant les méthodes undoOperation et redoOperation.
• Les sessions et opérations de mise à jour permettent de réaliser des mises à jour par lot, offrant des avantages significatifs en termes de performances pour la mise à jour des géodatabases d'entreprise.
• Dans les géodatabases autorisant les mises à jour simultanées de plusieurs utilisateurs, une application dans une session de mise à jour ne prendra en compte les modifications réalisées par d'autres applications qu'une fois la session terminée.

La classe Editor peut être utilisée pour démarrer et arrêter des sessions et opérations de mise à jour pour les géodatabases et les shapefiles.

La méthode startEditing est utilisée pour lancer une session de mise à jour et la méthode startOperation pour démarrer une opération de mise à jour. Pour valider une opération de mise à jour, appelez stopOperation. Pour annuler une opération de mise à jour, appelez abortOperation. Pour terminer une session de mise à jour, appelez stopEditing, qui accepte un paramètre booléen indiquant si les modifications effectuées dans la session doivent être validées ou ignorées.

Remarque :

Le non-respect de ce modèle peut provoquer des résultats inattendus. Par exemple, stopEditing ne doit pas être appelé lorsqu’une opération de mise à jour est en cours. Au lieu de cela, annulez l’opération de mise à jour et arrêtez la session de mise à jour.

Les opérations de mise à jour doivent être contrôlées dans le cadre d'une session de mise à jour, et ne peuvent pas être imbriquées dans d'autres opérations de mise à jour.

Sessions de mise à jour et avec instructions

Les sessions et opérations de mise à jour peuvent également être utilisées avec les instructions with. Les instructions with agissent comme des gestionnaires de contexte et gèrent les appels de départ, d’arrêt et d’abandon pour vous. L’exemple ci-dessous met en évidence la structure de base de la classe Editor utilisée avec les instructions with.

import arcpy

# Open an edit session and start an edit operation
with arcpy.da.Editor(workspace) as edit:
    # <your edits>

    # If an exception is raised, the operation will be aborted, and 
    #   the edit session is closed without saving

    # If no exceptions are raised, stop the operation and save 
    #   and close the edit session

Utiliser la pile d’opérations Annuler et Rétablir

Les piles d’opérations Annuler et Rétablir sont activées ou désactivées pour une session de mise à jour en fonction du paramètre booléen de la méthode startEditing. Lorsqu’une session de mise à jour doit inclure plusieurs opérations susceptibles d’être annulées (et rétablies), les piles d’opérations Annuler et Rétablir doivent être activées. À l'inverse, par exemple lorsque la session de mise à jour n'inclut qu'une seule opération, les piles des opérations Annuler et Rétablir peuvent être désactivées afin d'améliorer les performances en définissant le paramètre sur False (Faux).

Remarque :

Lorsque l’on commence une session de mise à jour versionnée dans une géodatabase d’entreprise, les piles d’opérations Annuler et Rétablir sont activées. Les sessions de mise à jour non versionnées ne prennent pas en jour les opérations Annuler et Rétablir.

Les deux méthodes qui contrôlent les piles d’opérations Annuler et Rétablir sont undoOperation et redoOperation. undoOperation restaure l’état de la session de mise à jour sur la dernière opération de mise à jour et place l’opération de mise à jour dans la pile d’opérations Rétablir. La méthode redoOperation déplace une opération de mise à jour du haut de la pile des opérations Rétablir dans la pile Annuler et rétablit l’état de la session de mise à jour à l’état précédant l’exécution de l’opération de mise à jour. Lorsqu'une opération de mise à jour est appliquée, la pile des opérations Rétablir est vidée et il n'est plus possible de rétablir aucune des opérations que contenait la pile.

Situations nécessitant une session de mise à jour

À continuation, vous trouverez certains des types de jeu de données qui peuvent uniquement être mis à jour dans une session de mise à jour :

• Classes d'entités faisant partie d'une topologie
• Classes d'entités faisant partie d'un réseau géométrique
• Classes d’entités faisant partie d’un jeu de données réseau
• Jeux de données des géodatabases d'entreprise
• Certains objets et classes d'entités avec des extensions de classe

Sessions et curseurs de mise à jour

Les curseurs ne peuvent être déployés que pour une seule opération de mise à jour. Cela signifie qu’une nouvelle instance de curseur doit être créée et déployée pour chaque opération. Ceci est très important lorsque l’on met à jour des lignes renvoyées par un curseur car celles-ci sont liées à un état spécifique de la géodatabase. Évitez d'utiliser un même curseur pour plusieurs opérations de mise à jour. Ceci pourrait générer un comportement inattendu et des pertes de données.

Sessions de mise à jour et données versionnées

Les tables de géodatabase d’entreprise et les classes d’entités peuvent être versionnées. La propriété isVersioned peut être utilisée pour déterminer si une table ou une classe d’entités est versionnée.

Lors de la mise à jour de tables de géodatabases d’entreprise et de classe d’entités, le mode session de mise à jour doit être défini en fonction du type de données mises à jour :

• Lors de la mise à jour d’une table ou d’une classe d’entités non versionnée, définissez l’argument multiuser_mode sur False.
• Lors de la mise à jour d’une table ou d’une classe d’entités versionnée, définissez l’argument multiuser_mode sur True.

Utilisez la classe Editor ou la méthode startEditing de la classe Editor pour définir multiuser_mode.

Si le mode multi-utilisateurs n’est pas correctement défini, vous risquez de recevoir une erreur indiquant que les objets de cette classe ne peuvent pas être mis à jour en dehors d’une session de mise à jour.

Syntaxe

 Editor (workspace, {multiuser_mode})

Paramètre	Explication	Type de données
workspace	Path to the workspace to edit. The editor can edit only one workspace at a time.	String
multiuser_mode	When edits will be performed on versioned data, set this to True; otherwise, set it to False. Only use with enterprise geodatabases. (La valeur par défaut est True)	Boolean

Propriétés

Propriété	Explication	Type de données
isEditing (Lecture seule)	True if the Editor is in an edit session.	Boolean

Vue d’ensemble des méthodes

Méthode	Explication
__enter__ ()	Starts an edit session.
__exit__ ()	If successful, stops editing and saves an edit session. If an exception, stops editing and doesn't save.
startEditing ({with_undo}, {multiuser_mode})	Starts an edit session.
stopEditing (save_changes)	Stops an edit session.
startOperation ()	Starts an edit operation.
stopOperation ()	Stops an edit operation.
abortOperation ()	Aborts an edit operation.
undoOperation ()	Undo an edit operation (roll back modifications).
redoOperation ()	Redoes an edit operation.

Méthodes

__enter__ ()

__exit__ ()

startEditing ({with_undo}, {multiuser_mode})

Paramètre	Explication	Type de données
with_undo	Sets whether the undo and redo stacks are enabled or disabled for an edit session. If an edit session will contain multiple operations that might be conditionally rolled back (and redone), the undo and redo stacks should be enabled. If not—for example, if the edit session will only contain a single operation—the undo and redo stacks can be disabled for performance benefits by setting the argument to false. When starting a versioned edit session in enterprise geodatabase, the undo and redo stacks will always be enabled. Nonversioned edit sessions do not support undo and redo operations. (La valeur par défaut est True)	Boolean
multiuser_mode	When False, you have full control of editing a nonversioned, or versioned dataset. If your dataset is nonversioned and you use stopEditing(False), your edit will not be committed (otherwise, if set to True, your edits will be committed). (La valeur par défaut est True)	Boolean

stopEditing (save_changes)

Paramètre	Explication	Type de données
save_changes	Specifies whether to save or discard changes. (La valeur par défaut est True)	Boolean

startOperation ()

stopOperation ()

abortOperation ()

undoOperation ()

redoOperation ()

Exemple de code

Exemple 1 d'utilisation de la fonction Editor

Le code suivant utilise une instruction with qui initie une opération de mise à jour et utilise la fonction CalculateField sur un ensemble de sélection de lignes dans une table. Toute erreur de l'outil qui se produit sera gérée et imprimée.

Puisque la fonction CalculateField est exécutée dans une instruction with, les modifications ne sont pas enregistrées si une exception se produit. Si CalculateField est exécuté correctement, les mises à jour sont enregistrées.

import arcpy

fc = 'C:/Portland/Portland.gdb/Land/Parks'
workspace = 'C:/Portland/Portland.gdb'
layer_name = 'Parks'

arcpy.MakeFeatureLayer_management(fc, layer_name)
arcpy.SelectLayerByAttribute_management(
    layer_name, 'NEW_SELECTION',
    """CUSTODIAN = 'City of Portland'""")
with arcpy.da.Editor(workspace) as edit:
    arcpy.CalculateField_management(layer_name, 'Usage', '"PUBLIC"', 'PYTHON')

Exemple 2 d'utilisation de la fonction Editor

L’exemple ci-dessous montre comment initier une session de mise à jour et une opération de mise à jour, créer une ligne dans une table, puis arrêter l’opération de mise à jour et valider la session de mise à jour.

import arcpy
import os

fc = 'C:/projects/Portland/Portland.sde/portland.jgp.schools'
workspace = os.path.dirname(fc)

# Start an edit session. Must provide the workspace.
edit = arcpy.da.Editor(workspace)

# Edit session is started without an undo/redo stack for versioned data

# Set multiuser_mode to False if working with unversioned enterprise gdb data
edit.startEditing(with_undo=False, multiuser_mode=True)

# Start an edit operation
edit.startOperation()

# Insert a row into the table.
with arcpy.da.InsertCursor(fc, ('SHAPE@', 'Name')) as icur:
    icur.insertRow([(7642471.100, 686465.725), 'New School'])

# Stop the edit operation.
edit.stopOperation()

# Stop the edit session and save the changes
edit.stopEditing(save_changes=True)

Exemple 3 d’utilisation de la fonction Editor

Voici un exemple d’utilisation de la classe Editor en tant que gestionnaire de contexte avec des données versionnées.

import arcpy
import os

new_students = 'C:/projects/Portland/Portland.sde/ptld.main.students_new2022'
students = 'C:/projects/Portland/Portland.sde/ptld.main.students'

# Start an edit session. Provide the workspace being acted on
# and with sde specify if data is edited in multiuser_mode.
with arcpy.da.Editor(os.path.dirname(students), multiuser_mode=True):

    # If all 3 edit operations run successfully without error
    # upon exiting this code block the edits will be applied to the data

    arcpy.management.CalculateField(new_students , 'arrived', '2022')
    arcpy.management.Append(new_students, students)
    arcpy.management.CalculateField(students, "active", True)