Esplorare l’API EcoStruxure Machine Expert Python (con dir() e inspectapi)

Panoramica

EcoStruxure Machine Expert fornisce un'API Python utilizzabile negli script EcoStruxure Machine Expert. Quando si scrivono script Python, nella maggior parte dei casi sono necessari solo nomi di funzioni o l'elenco dei parametri obbligatori e dei relativi nomi. Spesso sono inoltre disponibili le funzioni disponibili di un oggetto restituito da una funzione API chiamata. Le funzioni seguenti consentono di esplorare l'API EcoStruxure Machine Expert Python per il supporto nello sviluppo degli script Python.

Funzione dir(…) integrata di Python

Senza argomenti, questa funzione restituisce l'elenco dei nomi nell'ambito corrente locale. Con un argomento, questa funzione tenta di restituire un elenco di attributi validi per tale oggetto.

Il meccanismo dir() predefinito di Python si comporta in modo diverso con tipi diversi di oggetti, in quanto tenta di produrre le informazioni più rilevanti piuttosto che complete:

  • Se l'oggetto è di tipo modulo, l'elenco contiene i nomi degli attributi del modulo.

  • Se l'oggetto è un oggetto classe o tipo, l'elenco contiene i nomi degli attributi e, ricorrentemente degli attributi delle relative basi.

  • In alternativa, l'elenco contiene i nomi degli attributi dell'oggetto, i nomi degli attributi della propria classe e ricorrentemente degli attributi delle classi di base.

Esempio (in 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']

Funzioni di inspectapi

Poiché la funzione dir() non elenca tutti gli elementi API EcoStruxure Machine Expert Python, sono fornite funzioni aggiuntive per visualizzarli per gli sviluppatori di script Python.

inspectapi è un modulo Python caricato automaticamente all'avvio di LogicBuilderShell.exe o della vista Scripting Immediate. Di conseguenza, nell'ambito corrente è disponibile una variabile/un modulo inspectapi. Questa variabile viene elencata anche eseguendo la funzione dir().

Il modulo/variabile inspectapi fornisce le funzioni seguenti:

Nome della funzione

Parametri

Descrizione

inspectapi.dir

obj: specificare un oggetto (ad esempio, una variabile) per il quale si ottengono ulteriori informazioni.

(opzionale) verbose: il valore predefinito è FALSE. Impostare il parametro su TRUE per ottenere un risultato verbose.

Questa funzione fornisce un elenco dei membri API EcoStruxure Machine Expert Python disponibili che è possibile chiamare. Sono elencati campi, proprietà, eventi e metodi.

inspectapi.dir_events

Questa funzione fornisce un elenco degli eventi API EcoStruxure Machine Expert Python disponibili che è possibile chiamare.

inspectapi.dir_fields

inspectapi.dir_methods

inspectapi.dir_properties

inspectapi.help

()

Questa funzione apre la guida in linea di CODESYS Script Engine - Guida utente.

Per ulteriori informazioni, vedere anche Schneider Electric Script Engine - Guida utente.

obj: Specificare un oggetto (ad esempio, una variabile) per il quale verrà visualizzata la guida in linea.

Questa funzione apre la guida in linea dell'oggetto.

  • Se non è presente alcuna documentazione per l'oggetto, viene visualizzata la guida in linea del motore di script.

  • Se sono presenti più argomenti della Guida per l'oggetto (poiché esistono estensioni per l'oggetto o l'oggetto dispone di più interfacce documentate), viene visualizzata una finestra di dialogo che elenca gli argomenti pertinenti della Guida. Fare doppio clic su una voce per aprire l'argomento della Guida corrispondente.

  • Se è disponibile un solo argomento della Guida per l'oggetto, l'argomento della Guida si apre direttamente.

Esempi: 

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

Uscita: 

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)

Uscita: 

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)

Uscita (troncata): 

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)

Uscita (troncata): 

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)