class
ScriptProject.
ComparisonFlags
Bases: enum.Flag
Flags controlling the details of the ScriptProject.compare_to() method.
Version added
3.5.12.0
NONE
= 0
No flags set.
IGNORE_WHITESPACE
= 1
Controls whether whitespace changes are ignored (some object comparers ignore this parameter).
IGNORE_COMMENTS
= 2
Controls whether comment changes are ignored (some object comparers ignore this parameter).
IGNORE_PROPERTIES
= 4
Controls whether property changes are ignored (some object comparers ignore this propertyparameter).
SPLIT_RENAMES
= 8
Controls whether renames are split into a add and remove operation. If set to True, renamed objects are recorded as addition and deletion. If set to False, renamed objects are marked with ScriptProject.ObjectDifferences.RENAMED.
COMPARE_TRANSIENTS
= 16
Controls whether transient objects are ignored. Transient objects (like task call objects sitting below a ScriptTaskObject or SVN_VERSION_INFO objects) are not saved with the project, they're based on data stored elsewhere and will be recreated on the fly, thus they're not compared by default.
COMPARE_HIDDEN
= 32
Controls whether hidden objects are ignored. As they're not visible to the user, and usually represented by some other visible objects, they're not compared by default.
class
ScriptProject.
ScriptProject
Bases: ScriptTreeObject.ScriptTreeObject
Provides project specific functionality to scripts.
close
Closes this project.
The corresponding Object Manager project will also be closed. If this project has got unsaved changes, these changes will be discarded.
save
Saves this project at its physical location (see path).
The encryption settings are not changed.
save_as
path
password=None
Saves the project under a new filename and with different encryption.
If no password is given (None is passed), encryption stays as it is. If the password given, but an empty string, encryption is disabled. Otherwise, the password is used as new password to encrypt the project.
Note
If you want to change password without changing the path, use "proj.save_as(proj.path, "myPassword")".
Parameters
path (str) -- The new path to save the project.
password (str) -- The password.
save_archive
path
comment=None
additional_files=None
*additional_categories
Saves the project as an archive.
All additional categories which are selected by default are included, but no extra files.
Note
For a definition of the additional items, see ScriptProjectArchiveCategories. If you don't pass any additional_categories, ScriptProjectArchiveCategories.@default is used. To exclude all additional items, explicitly pass None.
Parameters
path (str) -- The path to save the archive.
comment (str) -- The comment to set for the archive.
additional_files (list) -- The additional (external) files to include into the archive.
additional_categories (ScriptProjectArchiveCategory) -- Version added: 3.5.4.0 The additional_categories.
dirty
Gets a boolean value indicating whether this project has been changed since the last call to save().
Return type
bool
Returns
True if this instance is dirty; otherwise, False.
primary
Gets a boolean value indicating whether the primary attribute has been set for this project.
The primary project is the one the user is currently working with.
The other, non-primary projects (aka background projects) can serve several purposes, for example:
Libraries referenced by the primary project.
Projects opened for comparison by the "Compare Project" command.
Temporary projects created for various purposes, e. G. by the V2.3 import converter,
or the CODESYS SVN add-on.
Those projects are not directly user visible, and you should not modify or close them from within your scripts.
Return type
bool
Returns
True if this instance is primary; otherwise, False.
library
Gets a boolean value indicating whether the project is a background library project.
Those projects represent a library which was loaded because it is referenced by the primary project (directly or indirectly). It will automatically be closed when the primary project is closed.
If you want to check whether the primary project is a library or not, check whether the path() ends with ".library" or ".project".
Return type
bool
Returns
True is this instance is a library; otherwise, False
path
Gets the absolute path where this project is physically stored.
To change that path, use save_as().
Return type
str
active_application
Gets or sets the active application.
This is a property. You can read or assign a :class:ScriptObject for the application you want to be the active application.
Version added
Return type
return_type
document
objects
Prints the specified database objects, including chapter headings and chapter numbering, a title page and table of contents.
The current printer settings as specified by the user are used. Currently, printing only works when the UI is present, not in --noUI mode.
Parameters
objects (list) -- The objects.
Raises
InvalidOperationException -- Is thrown when running in --noUI mode.
export_xml
objects
reporter=None
path=None
recursive=False
export_folder_structure=False
declarations_as_plaintext=False
Exports the given objects in PLCopenXML format into a string, or a file at the given path.
All non-exportable objects are reported as error, but the export may still continue.
Parameters
objects (list) -- The objects to export.
reporter (ExportReporter) -- The ExportReporter instance. None can be passed for no reporting.
path (str) -- The path of the file we export into. If omitted, we export into a string and return that string.
recursive (bool) -- If set to True, all exportable children of the objects are also exported.
export_folder_structure (bool) -- Version added: 3.4.4.0 if set to True, the folder structure of the objects is also exported. This is a proprietary extension to the default schema.
declarations_as_plaintext (bool) -- Version added: 3.5.2.0 if set to true, the declaration parts will be additionally exported as plain text (which is lossless in contrast to the default schema). This is a proprietary extension to the default schema. (Import will automatically recognize and prefer the plain text format if present.)
Return type
str
Returns
The exported XML as string, or None if a filepath is given.
import_xml
dataOrPath
reporter=None
import_folder_structure=False
Imports the contents of the specified PLCopenXML file into the top level of the project.
The heuristics to find out whether the content is a file or directly an XML string currently is as follows: if it contains the '<' character, it is regarded as an XML file. Rationale: On windows, < is an invalid char in path names, and it is contained in every XML file. (On other common platforms like unix and OSX, < is uncommon and discouraged in file names.) This heuristics may be replaced by a more sophisticated heuristics in the future.
Parameters
reporter (ImportReporter) -- The import reporter.
dataOrPath (str) -- The PLCopenXML file path, or the PLCopenXML as string.
import_folder_structure (bool) -- Version added: 3.4.4.0 if set to true, the folder structure of the objects is also imported. This is a proprietary extension to the default schema.
export_native
objects
destination
recursive=False
one_file_per_subtree=False
profile_name=None
reporter=None
Export the specified objects in the CoDeSys native export format.
The parameter destination must point to a directory if one_file_per_subtree is set to True, and to a file in the other case.
Version added
3.4.4.0
Parameters
objects (list) -- The objects to export.
destination (str) -- The destination.
recursive (bool) -- if set to true, the chilren are included recursively.
one_file_per_subtree (bool) -- if set to true, one file per subtree is generated.
profile_name (str) -- The profile_name, or None for the default profile.
reporter (NativeExportReporter) -- The reporter. You can pass None for no reporting at all.
import_native
filename=None
filenames=None
filter=None
handler=None
Imports the specified files in the native xml format in the top level of this project.
Warning
If None is passed for both filename and filenames, this method will fail.
Version added
3.4.4.0
Parameters
filename (str) -- The Filename.
filenames (list) -- The Filenames.
filter (NativeImportFilter()) -- The filter - if None is passed, all files are imported.
handler (NativeImportHandler) -- The handler - if None passed, the default handler is used.
Return type
login
username
password
Log into the project using the specified credentials.
Version added
3.4.1.10
Parameters
username (str) -- The username.
password (str) -- The password.
logout
Log out from the project (back to the user "nobody").
Version added
3.4.1.10
user_management
Returns the user management object for this project.
Version added
3.5.1.0
Raises
Exception -- If no user management is available.
has_project_info
Gets a value indicating whether this ScriptProject already has a project information object.
Version added
3.5.2.0
Return type
bool
Returns
true if it has a project info; otherwise, false.
get_project_info
Gets the project information object, implicitly creating one if not existing yet.
check_all_pool_objects
parameter_list
Checks all pool objects. This command only works reliable for libraries, and when called on primary projects.
You can use the System.get_messages() and System.get_message_objects() calls to check whether any messages were added.
Version added
3.5.2.0
generate_runtime_system_files
destination_directory
generate_m4=True
generate_c=False
Generates the specified destination_directory.
At least one of generate_m4 and generate_c must be set.
Version added
3.5.2.0
Parameters
destination (str) -- The destination_directory. Relative pathes are interpreted relative to the project location. If you pass None or the empty string, the project directory is used.
generate_m4 (bool) -- if set to true, M4 code is generated.
generate_c (bool) -- if set to true, C Code is generated.
clean_all
Performs a "Clean All".
Version added
3.5.2.0
save_as_compiled_library
destination_name=None
Save the current project as a compiled library.
This command currently only works for the primary project.
The destination_name has the following semantics: If it is omitted or the empty string, the full project path will be used, with the extension changed to ".compiled_library". If the name of an existing directory is given, the library will be saved there, using the project base name and the extension changed to ".compiled_library". Otherwise, the destination name will be interpreted as the path relative to where the current project re.
Version added
3.5.2.0
Parameters
destination_name (str) -- The destination name.
create_folder
foldername
structured_view=None
Creates a folder with the specified folder name.
There are three predefined structured views, and the guids are provided as constants:
SV_DEV The device view, SV_DEV = Guid("{D9B2B2CC-EA99-4c3b-AA42-1E5C49E65B84}")
SV_POU The POU view, SV_POU = Guid("{21AF5390-2942-461a-BF89-951AAF6999F1}")
The Modules View currently does not support folders, so no GUID is provided.
Version added
3.5.2.0
Parameters
foldername (str) -- The foldername.
structured_view (Guid) -- The structured view. This parameter is optional, if you pass Guid.Empty or omit the parameter, the "POU" view is used.
export_doc
path=None
ext_path=None
formatting=None
Exports the documentation for primary project in JSON format into a string, or a file at the given path.
Version added
3.5.5.0
Parameters
path (str) -- The path of the file we export into. If omitted, we export into a string and return that string.
ext_path (str) -- The path where external documentation files should be exported. If ommited, the same path as in path is used. If both ommited, the external documentation media is ignored.
formatting (DocExport.Formatting) -- Formatting of the export file.
Return type
str
Returns
The exported JSON as string, or None if a filepath is given.
compare_to
right_project
flags=<ComparisonFlags.NONE: 0>
Compares two script projects.
Version added
3.5.12.0
Parameters
right_project (object) -- The project (base) you want to compare the current project against.
flags (ComparisonFlags) -- Flags controlling the detailed behaviour of the comparison.
Return type
Returns
The comparison result.
project_settings
Returns the management object for ScriptProjectSettings.
Version added
3.5.12.10
Return type
enable_integrity_check
Enables the integrity checked project format.
Version added
3.5.13.0
disable_encryption
Disables password, CodeMeter(TM) dongle and X509 certificate-based encryption or integrity check for the specified project.
Version added
3.5.13.0
is_integrity_check_enabled
Returns whether the integrity checked project format is is_integrity_check_enabled.
Version added
3.5.13.0
Return type
bool
class
ScriptProject.
ScriptProjectSettings
Bases: object
Interface for project settings.
Version added
3.5.12.10
available_download_content
Gets a list of all available ScriptProjectArchiveCategories that can be used for ScriptProjectSettings.set_sourcedownload().
Return type
list <ScriptProjectArchiveCategory>
set_sourcedownload
timing
content
compact
device
Sets the source download settings to the project.
Parameters
timing (int) --
|
Value |
Behaviour |
|
1 |
Implicity at download and online change. |
|
2 |
Prompt at program download and online change. |
|
3 |
Implicity at creating boot project. |
|
4 |
Only on demand. |
|
5 |
Implicitly at creating boot project, program download and onlinechange. |
content (list) -- An enumerable of ScriptProjectArchiveCategory that should be part of the source download.
compact (bool) -- Indicates to use a compact download or not.
device (ScriptObject) -- The destination device or None for all devices in project.
class
ScriptProject.
ObjectDifferences
Bases: enum.Flag
Representing the object differences.
Version added
3.5.12.0
EQUAL
= 0
The objects are equal.
ADDED
= 1
The object was added.
DELETED
= 2
The object has been deleted.
CONTENT_CHANGED
= 4
The contents of the object are different.
FOLDER_CHANGED
= 8
The parent folder of the object is different.
ACCESS_RIGHTS_CHANGED
= 16
The acces rights of the object are different.
PROPERTIES_CHANGED
= 32
The mets properties of the object are different.
RENAMED
= 64
The name of the object was changed.
ANY_CHANGES
= 16777215
This covers any changes we can detect now and in the future. (=0xFFFFFF)
class
ScriptProject.
ScriptComparedObject
Bases: object
Representing the difference of an object.
left_object
The object from the ScriptComparison.left_project, or None for deleted objects.
Return type
right_object
The object from the ScriptComparisonResult.right_project, or None for added objects.
Return type
ObjectDifferences
The exact object differences.
Return type
class
ScriptProject.
ScriptComparisonResult
Bases: list
Represents the project comparison result.
Iterating this returns all changed objects.
Version added
3.5.12.0
left_project
The first or left project which was compared.
Return type
right_project
The second or right project which was compared.
Return type
get_changed_objects
state=<ObjectDifferences.ANY_CHANGES: 16777215>
Returns all changed objects with a matching diff state (any of the given flags have to be set).
Parameters
state (ObjectDifferences) -- The diff states to filter for objects.
Return type
list
Returns
The objects matching the criteria.
get_diff_state
script_object
Gets the diff state for a specific object.
Return type
Returns
The diff state for the object.
class
ScriptProject.
ExportReporter
Bases: object
python classes can implement their own export_xml reporter here. This interface(IExportReporter) is exposed under the name ExportReporter.
error
obj
message
This method is called when an error has occurred during export_xml.
Parameters
obj (ScriptObject) -- The object which caused the error.
message (str) -- The message describing the problem.
warning
obj
message
This method is called when a warning has occurred during export_xml.
Parameters
obj (ScriptObject) -- The object which caused the warning.
message (str) -- The message describing the problem.
nonexportable
obj
This method is called when we find out that a given object is not exportable.
This is only called for objects given directly as parameters - non-exportable children are silently ignored. The script can decide to abort the export by setting aborting to true during this phase.
This method will be called for all non-exportable objects even when aborting is set to true. The flag will be checked after all objects have been checked for exportability, just before the actual export is going to start (and thus before the destination file is opened). This allows scripts to find out about all non-exportable objects in one run.
Parameters
obj (ScriptObject) -- The object which is not exportable
aborting
This allows abortion when we report non-exportable objects.
Return type
bool
class
ScriptProject.
ImportReporter
Bases: object
Python classes can implement their own import_xml reporter here.
This interface(IImportReporter) is exposed under the name ImportReporter.
error
message
This method is called when an error has occurred during import_xml.
Parameters
message (str) -- The message describing the problem.
warning
message
This method is called when a warning has occurred during import_xml.
Parameters
message (str) -- The message describing the problem.
resolve_conflict
obj
This method is called when an object to import is already existing.
Parameters
obj (ScriptObject) -- The already existing object.
Return type
ConflictResolve
Returns
How to resolve the conflict: rename the new object, replace the existing object, or skip the new object.
added
obj
This method is called whenever an object has been successfully added during import.
Parameters
obj (ScriptObject) -- The newly added object.
replaced
object
This method is called whenever an object has been successfully replaced during import.
Parameters
obj (ScriptObject) -- The replacing object.
skipped
objectname
This method is called whenever an object has been skipped during import.
Parameters
objectname (str) -- The name of the skipped object.
aborting
Gets a boolean value indicating whether importing should be aborted or not.
Return type
bool
class
ScriptProject.
NativeExportReporter
Bases: object
This reporter is used for the native XML export. This interface is exposed under the name NativeExportReporter.
skipped
type_name
serializable_value_name
This method is called when data has been effectively skipped during serialization or deserialization.
Parameters
type_name (str) -- The typename of the object that was not stored or restored completely.
serializable_value_name (str) -- The serializable value name of the member or property that has been skipped.
warn
message
This method is called when a warning occurs during serialization or deserialization.
Parameters
message (str) -- A message describing the reason of the warning.
cancel
message
This method is called when an error occurs during serialization or deserialization.
The code that triggered the serialization should discard the resulting stream because it will not be correctly formatted in this case. The code that triggered the deserialization should discard the resulting object because it might be inconsistent.
Parameters
message (str) -- A message describing the reason of the error.
ScriptProject.
NativeImportFilter
self
name
guid
type
path
[Delegate]. This method can be used to filter the imported objects.
Parameters
path (param_type) -- A python tuple containing the object path.
Return type
bool
Returns
True if the item is to be imported.
class
ScriptProject.
NativeImportResult
class
ScriptProject.
NativeImportHandler
Bases: object
Handler callback for the native XML import.
This interface is exposed under the name NativeImportHandler.
conflict
name
existingObject
newguid
Queries how to resolve a conflict.
Return type
Returns
The resolution for this conflict.
progress
name
pastedObject
exception
Reports progress of import.
skipped
name
Informs about skipped objects.
Parameters
name (list) -- A python tuple with the names..
