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

property link_always¶

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

property link_always_is_valid¶

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.ScriptTransientObjectMarker¶

Bases: object

All script objects are extended with this interface

property is_transient_object¶

Gets a value indicating whether this ScriptTransientObjectMarker is a transient 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)