Exploration de l'API EcoStruxure Machine Expert Python (avec dir() et inspectapi)

Présentation

EcoStruxure Machine Expert fournit une API Python que vous pouvez utiliser dans des scripts EcoStruxure Machine Expert. Lorsque vous écrivez des scripts Python, vous n'avez la plupart du temps besoin que de noms de fonctions ou de la liste des paramètres requis et de leurs noms. Bien souvent, vous avez aussi besoin des fonctions d'un objet renvoyé par une fonction d'API que vous avez appelée. Les fonctions suivantes vous permettent d'explorer l'API EcoStruxure Machine Expert Python pour vous aider à développer des scripts Python.

Fonction dir(…) intégrée de Python

En l'absence d'argument, la fonction renvoie la liste des noms appartenant au domaine de validité local actuel. En présence d'un argument, elle renvoie la liste des attributs valides de l'objet en question.

Le mécanisme dir() par défaut de Python se comporte différemment selon les types d'objets car il essaie de produire les informations les plus pertinentes et non complètes :

  • Avec un objet de module, la liste répertorie les noms des attributs du module concerné.

  • Avec un objet de type ou de classe, la liste répertorie les noms des attributs de l'objet et de ses bases (de façon récursive).

  • Pour les autres types d'objets, la liste répertorie les noms des attributs de l'objet, des attributs de sa classe et des attributs des classes de base (de façon récursive).

Exemple (dans LogicBuilderShell.exe) : 

>>> import struct
>>> dir()   # show the names in the module namespace
['__builtins__', '__doc__', '__name__', 'struct']
>>> dir(struct)   # show the names in the struct module
['Struct', '__builtins__', '__doc__', '__file__', '__name__',
 '__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
 'unpack', 'unpack_from']
>>> class Shape(object):
        def __dir__(self):
            return ['area', 'perimeter', 'location']
>>> s = Shape()
>>> dir(s)
['area', 'perimeter', 'location']

Fonctions inspectapi

Comme la fonction dir() ne répertorie pas tous les éléments de l'API EcoStruxure Machine Expert Python, des fonctions supplémentaires sont fournies pour permettre aux développeurs de scripts Python de les afficher.

inspectapi est un module Python chargé automatiquement lors du démarrage de LogicBuilderShell.exe ou de l'affichage Scripting Immediate. Ainsi, une variable / un module inspectapi est disponible dans la portée en cours. Cette variable peut également être répertoriée en exécutant la fonction dir().

La variable ou le module inspectapi fournit les fonctions suivantes :

Nom de la fonction

Paramètres

Description

inspectapi.dir

obj : Spécifiez un objet (une variable, par exemple) pour lequel vous voulez plus d'informations.

(facultatif) verbose : La valeur par défaut est FALSE. Réglez ce paramètre sur TRUE pour obtenir des informations détaillées.

Cette fonction fournit une liste des membres d'API EcoStruxure Machine Expert Python disponibles que vous pouvez appeler, à savoir les champs, les propriétés, les événements et les méthodes.

inspectapi.dir_events

Cette fonction fournit une liste des événements d'API EcoStruxure Machine Expert Python disponibles que vous pouvez appeler.

inspectapi.dir_fields

inspectapi.dir_methods

inspectapi.dir_properties

inspectapi.help

()

Cette fonction ouvre l'aide en ligne du Guide utilisateur du moteur de script CODESYS.

Pour plus d'informations, reportez-vous également au Guide utilisateur de Schneider Electric Script Engine.

obj : Spécifiez un objet (une variable, par exemple) pour lequel vous voulez afficher l'aide en ligne.

Cette fonction ouvre l'aide en ligne de l'objet.

  • S'il n'y a pas de documentation pour l'objet, l'aide en ligne du moteur de script s'ouvre.

  • S'il y a plusieurs rubriques d'aide pour l'objet (parce qu'il existe des extensions pour cet objet ou qu'il a plusieurs interfaces documentées), une boîte de dialogue apparaît et répertorie les rubriques d'aide appropriées. Double-cliquez sur une entrée pour ouvrir la rubrique d'aide correspondante.

  • S'il n'y a qu'une seule rubrique d'aide pour l'objet, elle s'ouvre directement.

Exemples : 

# To see the API of the inspect api itself
inspectapi.dir(inspectapi)

Sortie : 

Members of type 'InspectAPI'
Methods:
  dir (obj, verbose = False)
  dir_events (obj, verbose = False)
  dir_fields (obj, verbose = False)
  dir_methods (obj, verbose = False)
  dir_properties (obj, verbose = False)
  help (obj = null)
# To see the API of projects variable
inspectapi.dir(projects)

Sortie : 

Members of type 'ScriptProjects'
Properties:
  [get] all
  [get] primary
Methods:
  convert (stPath, stOutputPath, converter, bPrimary)
  convert (stPath, stOutputPath, converterGuid, bPrimary)
  create (stPath, bPrimary)
  get_all ()
  get_by_path (stPath)
  get_primary ()
  open (stPath, stPassword, bPrimary)
  open (stPath, encryption_password, session_user, session_password, bPrimary)
  open_archive (stArchiveFile, stProjectPath, bOverwrite, stPassword)
  open_archive (stArchiveFile, stProjectPath, bOverwrite, encryption_password, session_user, session_password)
# open a project
proj = projects.open("c:\\temp\\MyScript.py ")
# To see API of primary project
inspectapi.dir(projects.primary)

Sortie (tronquée) : 

Members of type 'ScriptProject'
Properties:
  [set] active_application
  [get] dirty
  [get] handle
  [get] has_library_manager
  [get] has_project_info
  [get] is_root
  [get] library
  [get] path
  [get] primary
  [get] project
  [get] svn
  [get] user_management
Methods:
  add (stName, id, stModuleId)
  add (stName, iType, stId, stVersion, stModuleId)
  check_all_pool_objects ()
  clean_all ()
  close ()
  compare_to (projectFile)
  compare_to (projectFile, ignoreWhiteSpace, ignoreComments, ignoreProperties)
  ...
  logout ()
  save ()
  save_archive (stArchiveFile)
  save_archive (stPath, additional_categories)
  save_archive (stPath, comment, additional_categories)
  save_archive (stPath, additional_files, additional_categories)
  ....
  save_as (stPath, stPassword)
  save_as_compiled_library (destination_name)
  set_active_application (value)
  update ()
# search objects by name (e.g. a device with name SERCOSIII)
objs = projects.primary.find("SERCOSIII", True)
# extract object at index 0 from returned list (if found).
theObj = obj[0]
# see the available API of the found object SERCOSIII
inspectapi.dir(theObj)

Sortie (tronquée) : 

Members of type 'ScriptObject'
Properties:
  [get] connectors
  [get] device_parameters
  [get] embedded_object_types
  [get] guid
  [get] handle
  [get] has_textual_declaration
  [get] has_textual_implementation
  [get] index
  [get] is_application
  [get] is_device
  [get] is_explicit_connector
  [get] is_folder
  [get] is_libman
  [get] is_project_info
  [get] is_root
  [get] is_task
  [get] parent
  [get] project
  [get] svn
  [get] type
Methods:
  add (stName, id, stModuleId)
  add (stName, iType, stId, stVersion, stModuleId)
  allowed_interfaces_at (index)
  can_convert (targetDeviceId, targetModuleId = null)
  can_convert (targetType, targetId, targetVersion, targetModuleId = null)
  convert (targetDeviceId, targetModuleId = null)
  convert (targetType, targetId, targetVersion, targetModuleId = null)
  create_folder (stFolderName)
  disable ()
  enable ()
  export_native (destination, includeChildren, profileName, reporter)
  export_xml (reporter, stPath, bRecursive)
  export_xml (reporter, stPath, bRecursive, bExportFolderStructure)
  export_xml (reporter, stPath, bRecursive, bExportFolderStructure, bPlainText)
  export_xml (stPath, bRecursive, bExportFolderStructure, bPlainText)
  find (namePath)
  find (stName, recursive)
  get_address ()
  get_all_parameters ()
  ...
  move (newParent, nNewIndex)
  plug (stName, id, stModuleId)
  plug (stName, iType, stId, stVersion, stModuleId)
  reboot_plc ()
  remove ()
  rename (stNewName)
  reset_diagnosis_messages ()
  set_communication_address (address)
  set_gateway_and_address (stGateway, stAddress)
  set_gateway_and_address (gateway, stAddress)
  set_parameter (parameter, value)
  set_parameter_iec_address (identifier, connectorId, iecAddress)
  set_parameter_io_variable_mapping (identifier, connectorId, variable, createVariable = False)
  set_parameter_io_variable_mapping (identifier, connectorId, subElementIndex, variable, createVariable = False)
  set_simulation_mode (bSimulation)
  unplug ()
  update (id, stModuleId)
  update (iType, stId, stVersion, stModuleId)