ScriptProject¶

class ScriptProject.ComparisonFlags(value)¶

Bases: Enum

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.ObjectDifferences(value)¶

Bases: Enum

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.NativeImportResult(value)¶

Bases: Enum

Enum that enumerates the possible results of a native XML import.

no_changes = 1¶: The import did not change anything at all.

ok = 2¶: The import was successful

skipped = 3¶: The import skipped some entries

errors = 4¶: Errors happened during the import

class ScriptProject.NativeImportResolve(value)¶

Bases: Enum

How to resolve a conflict.

replace = 1¶: Replace the object.

skip = 2¶: Skip the object

cancel = 3¶: Cancel the import

class ScriptProject.Formatting(value)¶

Bases: Enum

none = (1,)¶

Indented = 2¶

class ScriptProject.ConflictResolve(value)¶

Bases: Enum

Possible resolvements in the case that importing a specific PLCopenXML object leads to conflicts with an already existing object.

Replace = (0,)¶: The existing object is replaced by the imported object.

Copy = (1,)¶: The existing object remains with its original name, and the imported object is renamed so that is does not conflict any more.

Skip = 2¶: The object to be imported is skipped.

class ScriptProject.ScriptProject¶

Bases: 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 or None) – 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.

property 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.

property 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.

property 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

property path¶

Gets the absolute path where this project is physically stored.

To change that path, use save_as().

Return type:: str

property active_application¶

Gets or sets the active application.

This is a property. You can read or assign a ScriptObject for the application you want to be the active application.

Return type:: ScriptObject

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 (tuple[ScriptObject]) – 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 (tuple[ScriptObject]) – The objects to export.
reporter (ExportReporter) – The ExportReporter instance. None can be passed for no reporting.
path (str or None) – The path of the file we export into. If omitted, we export into a string and return that string.
recursive (bool or None) – 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 or None) – 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:

NativeImportResult

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

property user_management¶

Returns the user management object for this project.

Version added:: 3.5.1.0
Raises:: Exception – If no user management is available.
Return type:: ScriptUserManagement

property 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.

Version added:: 3.5.2.0
Return type:: ScriptObject
Returns:: The project information object.

check_all_pool_objects()¶

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_directory (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 or None) – 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=Formatting.Indented)¶

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 or None) – The path of the file we export into. If omitted, we export into a string and return that string.
ext_path (str or None) – 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 (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=0)¶

Compares two script projects.

Version added:

3.5.12.0

Parameters:

right_project (ScriptProject) – The project (base) you want to compare the current project against.
flags (ComparisonFlags) – Flags controlling the detailed behaviour of the comparison.

Return type:

ScriptComparisonResult

Returns:

The comparison result.

property project_settings¶

Returns the management object for ScriptProjectSettings.

Version added:: 3.5.12.10
Return type:: ScriptProjectSettings

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

property 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) –

The timing behaviour.¶
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[ScriptProjectArchiveCategory]) – 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.

property project_defines¶

Gets or sets the project defines (a comma separated list).

This is a property. You can read or assign a string (a comma separated list) containing the project defines. This property can be only used for compilerversion 3.5.20.0 or newer.

Return type:: str
Returns:: The project defines, or an empty string if no project defines are set or the compilerversion is less than 3.5.20.0.

class ScriptProject.ScriptComparedObject¶

Bases: object

Representing the difference of an object.

property left_object¶

The object from the ScriptComparison.left_project, or None for deleted objects.

Return type:: ScriptObject

property right_object¶

The object from the ScriptComparisonResult.right_project, or None for added objects.

Return type:: ScriptObject

property ObjectDifferences¶

The exact object differences.

Return type:: ObjectDifferences

class ScriptProject.ScriptComparisonResult(iterable=(), /)¶

Bases: list

Represents the project comparison result.

Iterating this returns all changed objects.

Version added:: 3.5.12.0

property left_project¶

The first or left project which was compared.

Return type:: ScriptProject

property right_project¶

The second or right project which was compared.

Return type:: ScriptProject

get_changed_objects(state=ObjectDifferences.ANY_CHANGES)¶

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:: ScriptComparedObject
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

property 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(obj)¶

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.

property 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 (tuple[object]) – A python tuple containing the object path.
Return type:: bool
Returns:: True if the item is to be imported.

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:: NativeImportResolve
Returns:: The resolution for this conflict.

progress(name, pastedObject, exception)¶

Reports progress of import.

skipped(name)¶

Informs about skipped objects.

Parameters:: name (tuple[object]) – A python tuple with the names..