ScriptObject

class ScriptObject.ScriptObject

Bases: ScriptTreeObject

Modelling of a script object.

They compare equal if Guid and ProjectHandle (inherited from ScriptTreeObject) are equal.

property type

Gets the type guid.

Return type:

Guid

property guid

Gets the GUID of the object.

Return type:

Guid

property embedded_object_types

Gets the embedded onject types.

Return type:

list[Guid]

get_name(resolve_localized_display_name=False)

Gets the name of the object.

Parameters:

resolve_localized_display_name (bool) – if set to True, the name is localized.

Return type:

str

Returns:

The name of the object

rename(stNewName)

Renames the object to the new name.

Parameters:

stNewName (str) – New name of the object.

property index

Gets the index.

Return type:

int

property is_folder

Gets a value indicating whether this instance is a folder.

Return type:

bool

property parent

Gets the parent ScriptObject, or the Project if we are top-level.

You can use the is_root property implemented by objects and projects to distinct between the two.

Return type:

object

remove()

Removes this instance.

move(new_parent: ScriptProject, new_index: int = -1)

Moves the object to the specified new parent.

Parameters:

  • new_parent (ScriptProject) – The new parent.

  • new_index (int) – New index in the new parent.

export_xml(reporter=None, path=None, recursive=False, export_folder_structure=False, declarations_as_plaintext=False)

Exports the ScriptObject in PLCopenXML format into a string, or a file at the given path.

This method internally eliminates duplicates, and all non-exportable objects are reported as error. Following 3.5.4.0, reporter can be omitted. The method will then report all exportable objects, report everything on progress, and throw exceptions on critical errors.

Note

Due to the sheer amount of overrides from different versions this function has to offer, it is best practice to give even positional arguments with their respective keywords.

Parameters:

  • reporter (ExportReporter) – The IExportReporter instance.

  • recursive (bool) – if set to true, all exportable children of the objects are also exported.

  • path (str) – The path of the file we export into. If omitted, we export into a string and return that string.

  • 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.3.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, conflictResolve=None, import_folder_structure=False, reporter=None)

Imports the contents of the specified PLCopenXML file als children of the current object.

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. This heuristics may be replaced by a more sophisticated heuristics in the future. Following 3.5.4.0, reporter can be omitted.

Note

Due to the sheer amount of overrides from different versions this method has to offer, it is best practice to give even positional arguments with their respective keywords.

Parameters:

  • dataOrPath (str) – The PLCopenXML file path, or the PLCOpenXML as string.

  • conflictResolve (ConflictResolve) – The conflict resolution strategy.

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

  • reporter (ImportReporter) – The import reporter.

export_native(destination, recursive=True, profile_name=None, reporter=None)

Export the specified objects in the CoDeSys native export format.

Version added:

3.4.4.0

Parameters:

  • destination (str) – The destination file.

  • recursive (bool) – if set to true, the chilren are included recursively.

  • 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(filenames, filter=None, handler=None)

Imports the specified files in the native xml format in under the current node.

Version added:

3.4.4.0

Parameters:

  • filenames (str or list) – The filename or a list of 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.

create_folder(foldername)

Creates a folder with the specified foldername in the structured view of the parent node.

The Modules View currently does not support folders, so creating folders below module objects is not supported.

Version added:

3.5.3.0

Parameters:

foldername (str) – The foldername.

get_signature_crc(application=None, default_value=None)

Gets the signature CRC of the specified pou.

A successful build is needed for this method to work.

For POUs which are defined below an application, compile the application via ScriptApplication.build(). You can omit “application”, and the parent application will be found automatically. For POUs which are in the pool of a library projuect, compile the application via ScriptProject.check_all_pool_objects(). The pool application guid (Guid.Empty) will be used automatically in this case, so you can omit “application”. For pous which are defined in the pool of a project, but referenced from within an application, compile the application via ScriptApplication.build() and explicitly pass that application (or its guid) as “application” parameter.

Version added:

3.5.4.0

Parameters:

  • application (object) – The application which the POU is referenced, if necessary (see remarks). This parameter accepts the application object or its guid.

  • default_value (str) – If you pass a value here, this is returned instead of throwing an exception when no CRC is found.

Return type:

string

Returns:

The string representation of the CRC, or the default value when no CRC was found.

Raises:

  • InvalidOperationException – No compile context found for the object - maybe the application was not compiled?

  • NotSupportedException – No compiled signature found for the object - maybe the object is no POU.

  • KeyNotFoundException – No CRC attribute found for the object.

  • ArgumentException – You passed an invalid object for the application.

property build_properties

Gets the build properties of the object, or None.

Not all objects have editable build properties - this method returns None when the object does not have any build properties.

Version added:

3.5.7.0

Return type:

ScriptBuildProperties

property effectively_excluded_from_build

Gets a boolean indicating whether this object is effectively excluded from the build.

An object is effectively excluded if either the object itsself or any of its parents has the ScriptBuildProperties.exclude_from_build() flag set.

Version added:

3.5.7.0

Return type:

bool

property exclusion_from_build_is_inherited

Gets a boolean indicating whether the build exclusion is inherited from a parent object.

Version added:

3.5.7.0

Return type:

bool

class ScriptObject.ScriptBuildProperties

Bases: object

Defining the build properties of objects contributing to the compiler.

Note that some objects do not define all of those properties. For example, folders only allow the exclude_from_build() property to be set (which is inherited to POUs below that folder), and devices may opt in or out of some properties based on the kind of device. Accessing an invalid property will throw an InvalidOperationException.

property external

Gets or sets the External-flag.

A POU with this flag is supposed to be linked in runtime system.

Check the external_is_valid() property whether this property is currently valid for this object.

Return type:

bool

property external_is_valid

Gets wether the external() property is valid for this object or not.

Return type:

bool

property enable_system_call

Gets or sets the Enable system call-flag.

A POU with this flag can be called by C-Code out of the runtime system

Check the enable_system_call_is_valid() property whether this property is currently valid for this object.

Return type:

bool

property enable_system_call_is_valid

Gets whether the enable_system_call() property is is valid for this object or not.

Return type:

bool

property compiler_defines

Gets or sets compilerdefines for the object.

The defines may be a list of comma seperated defines like this: DEF1, DEF2=’value’ For simple objects the scope of these defines is the object itself for applications, the scope of these defines is the whole application. Check the compiler_defines_is_valid() property whether this property is currently valid for this object.

Return type:

str

property compiler_defines_is_valid

Gets whether the compiler_defines() property is valid for this object or not.

Return type:

bool

Gets or sets the flag for linking an object in any case.

If true is assigned, the object will be linked into the application even when it is not referenced in another way.

Check the link_always_is_valid() property whether this property is currently valid for this object.

Return type:

bool

Gets whether the link_always() property is valid for this object or not.

Return type:

bool

property exclude_from_build

Gets or sets the flag Exclude from build.

Objects which are excluded from the build will be ignored by the compiler.

In other words, the language model of an object with this flag will be removed from language model manager. Note that a false value might be overwritten by a true value stored for the parent object. Use ScriptObject.effectively_excluded_from_build() to query the effective value for this object. Check the exclude_from_build_is_valid() property whether this property is currently valid for this object.

Return type:

bool

property exclude_from_build_is_valid

Gets whether the exclude_from_build() property is valid for this object or not.

Return type:

bool

class ScriptObject.ScriptProjectInfoMarker

Bases: object

The all objects are extended with this interface, since CoDeSys V3.5 SP2.

Version added:

3.5.2.0

property is_project_info

Gets a value indicating whether this ScriptProjectInfoMarker is the project info object.

Return type:

bool

class ScriptObject.ScriptProjectInfoObject

Bases: ScriptProjectInfoMarker

The project information objects are extended with this interface, since CoDeSys V3.5 SP2.

Version added:

3.5.2.0

property generate_accessors

Gets a value indicating whether this ScriptProjectInfoObject generates property accessor POU objects or not.

Returns:

true` if accessor functions are generated; otherwise, ``false.

Return type:

bool

change_accessor_generation(generate_accessors)

Changes the generate_accessor flag.

As changing this flag is potentially expensive (genrating several POUs), it is an explicit function and no property setter.

Parameters:

generate_accessors (bool) – if set to True, the accessors are generated.

property company

Gets or sets the company.

Libraries are uniquely identified by the tuple <company(), title(), version()>

Return type:

str

property title

Gets or sets the title.

Libraries are uniquely identified by the tuple <company(), title(), version()>.

Return type:

str

property version

Gets or sets the version.

remarks

Return type:

Version or str or tuple[int] or Sequence[int]

Returns:

The version. This returns a System.Version instance. For setting, it accepts System.Version instances as well as strings which are parseable as version, and tuples / sequences with 2-4 integers.

property released

Gets or sets a value indicating whether the project containing this ScriptProjectInfoObject is released.

Released library projects should not be modified any more. Unset the released flag and change the version if you want to modify a released library.

Return type:

bool

property categories

If the project is used as a library, it appears under the following categories.

Return type:

list[LibCategory]

property default_namespace

Gets or sets the default namespace when the project is used as a library.

Return type:

str

property author

Gets or sets the author.

Return type:

str

property description

Gets or sets the description.

This string may be multiline.

Return type:

str

property dongle_licencing_active

Gets or sets a value indicating whether this library has dongle license protection.

If dongle licensing is activated, the user needs to connect a dongle containing the appropriate license in order to use this library. For the licensing to work correctly, both firm_code and product_code MUST be specified. Please note that only compiled libraries will be protected!

Return type:

bool

Returns:

true if license protection is active; otherwise, false

Raises:

InvalidOperationException – When setting to True, but dongle_licensing_firm_code() or dongle_licensing_product_code() are not set.

property dongle_licensing_firm_code

Gets or sets the dongle licensing firm code.

If dongle licensing is activated, the user needs to connect a dongle containing the appropriate license in order to use this library. For the licensing to work correctly, both firm_code and product_code MUST be specified. Please note that only compiled libraries will be protected!

Return type:

int or None

Raises:

  • InvalidOperationException – When trying to unset this value while dongle_licencing_active() is set.

  • ArgumentOutOfRangeException – When trying to set this to a negative value.

property dongle_licensing_product_code

Gets or sets the dongle licensing product code.

If dongle licensing is activated, the user needs to connect a dongle containing the appropriate license in order to use this library. For the licensing to work correctly, both firm_code and product_code MUST be specified. Please note that only compiled libraries will be protected!

Return type:

int or None

Raises:

  • InvalidOperationException – When trying to unset this value while dongle_licencing_active() is set.

  • ArgumentOutOfRangeException – When trying to set this to a negative value.

property dongle_licensing_activation_url

Gets or sets the dongle licensing activation email address.

Return type:

str

property dongle_licensing_activation_mail

Gets or sets the dongle licensing activation email address.

Return type:

str

property values

Gets the custom property dictionary.

The following types are allowed:

Type

Description

str

Textual properties.

DateTime

Date / time properties.

int

Numerical properties.

bool

Boolean properties.

Version

Version properties, they may also be passed as str or tuple / sequence of integers.

You’re responsible yourself to set the correct type. Any inconsistencies or problems introduced by fiddling with this dictionary are your own responsibility.

Some properties are defined in the online help: See the section “Libraries -> Guidelines for creating Libraries -> Library Development Summary -> CODESYS LibDevSummary V3.5.4.0 -> Concepts and Elements -> Library Properties”:

–

Name

Type

Description

Required

Company

Text

Serves for structuring (filter) in the “Add Library” dialog

Required

Title

Text

Name of the library

Required

Version

Version

Library verison

Optional

Released

Bool

A library should not be modified after having been released

Optional

Author

Text

Author of the current library version

Optional

DefaultNamespace

Text

World-wide unique prefix, for defining the scope of the symbols of the library

Optional

Description

Text

Short description of the purpose of the library

Optional

Placeholder

Text

which Placeholder should be used for referencing the library

Optional

IsContainerLibrary

Bool

This library follwos the rules for a Container Library

Optional

IsInterfaceLibrary

Bool

This library follows the rules for a Interface Library

Optional

LanguageModelAttribute

Text

The access on symbols of the library is only possible via Namespace/Prefix

Optional

IsEndUserLibrary

Bool

This Library is especially designed for the needs of end users
Return type:

Dictionary(str, object)