Reading .NET API Documentations

Reading .NET API Documentations for Python Programmers

The current preliminary version of the script interface documentation is auto-generated from the underlying .NET / C# sources. Thus, it contains some idioms which are not common to Python programmers.

The list gives some hints on how to translate them to the Pythonic way of thinking:

oInterfaces in .NET are a contract about which members (methods, properties) have to be provided by the classes implementing that interface. In IronPython, one can implement one or several .NET interfaces by deriving them as one does with base classes. When a member declared by the interface is missing in the declaration, an exception will be thrown at runtime. (The DeviceImportFromSvn.py example shows a class implementing the ImportReporter interface.)

oIn .NET, all parameters, properties, and function return values are statically typed. The allowed type is annotated in front of the parameter name. For functions, the type of the return value is in front of the function name. Instances of subclasses are allowed when a parent class (or interface) is mentioned. void denotes a function without a return value.

oMethods may be overloaded, a class can have several methods with the same name, but they differ in the number and/or types of parameters. IronPython will automatically call the matching variant.

oThe type INT can contain an integral number between -2,147,483,648... 2,147,483,647, BOOL is equal to the Python type BOOL (TRUE and FALSE), the type STRING is equal to the Python type str and unicode (which are equal in IronPython). IDictionary<Object, Object> denotes a normal Python dictionary. IronPython automatically converts between the Python and .NET types.

oIf a type T derives from IBaseObject<T>, that type can be extended with more members by other plugins. The actual usages of that type T in parameters or return values will be marked with IExtendedObject<T>.

oThe interface IEnumerable<T> describes any sequence (lists, arrays, generators) which yield only objects of type T (or subclasses). When the sequence yields an incompatible object, an exception will be thrown at runtime.

oThe interface IList<T> describes a list which contains only objects of type T (or subclasses). When trying to add an incompatible object, an exception will be thrown.

oThe syntax params T [] name is equal to the Python syntax *name for variable argument lists, but restricts the parameters to type T (or subclasses).

oEnumerations (ENUM) do not exist as a language construct in Python. They are used to define a fixed amount of constant values, for example, the days of a week. Enumeration values defined in .NET can be accessed in IronPython via Name.Member syntax (similar to static class members), for example, OnlineChangeOption.Try. There are several patterns of emulating enums in Python, for example, http://pypi.python.org/pypi/enum/ or http://www.ironpython.info/index.php/Enumerations.

oProperties marked with { get; set; } are read-write, properties only marked with { get; } are read-only. They are similar to the @property decorator in Python.

For scripts the following entry points are available:

osystem: Basic functionality for integration in the EcoStruxure Machine Expert system. This object provides all functions described under ISystem Interface, such as the exit of EcoStruxure Machine Expert, the access to the message window or the query if the --noUI mode is running by use of the ui_present command.

oprojects: Basic functionality for project management. This object provides all functions described under IScriptProjects Interface, such as loading of projects and project archives. Furthermore, it is the entry point to the individual projects.

oonline: Basic functionality for online connection to device. By use of the create_on­line_application method, the online object of an application object can be created. This online object allows login to controllers, starting applications and retrieving variable values.