Import precedence relative to Python modules

import gives precedence to .py files. For example, if a file called System.py exists in the path, it will get imported instead of the System namespace:

>>> # create System.py in the current folder
>>> f = open("System.py", "w")
>>> f.write('print "Loading System.py"')
>>> f.close()
>>>
>>> # unload the System namespace if it has been loaded
>>> import sys
>>> if sys.modules.has_key("System"):
...     sys.modules.pop("System") #doctest: +ELLIPSIS
<module 'System' (CLS module, ... assemblies loaded)>
>>>
>>> import System
Loading System.py
>>> System #doctest: +ELLIPSIS
<module 'System' from '...System.py'>

>>> import os
>>> os.remove("System.py")
>>> sys.modules.pop("System") #doctest: +ELLIPSIS
<module 'System' from '...System.py'>
>>> import System
>>> System #doctest: +ELLIPSIS
<module 'System' (CLS module, ... assemblies loaded)>

Accessing generic types

.NET supports generic types which allow the same code to support multiple type parameters which retaining the advantages of types safety. Collection types (like lists, vectors, etc) are the canonical example where generic types are useful. .NET has a number of generic collection types in the System.Collections.Generic namespace.

IronPython exposes generic types as a special type object which supports indexing with type object(s) as the index (or indices):

>>> from System.Collections.Generic import List, Dictionary
>>> int_list = List[int]()
>>> str_float_dict = Dictionary[str, float]()

Note that there might exist a non-generic type as well as one or more generic types with the same name [1]. In this case, the name can be used without any indexing to access the non-generic type, and it can be indexed with different number of types to access the generic type with the corresponding number of type parameters. The code below accesses System.EventHandler and also System.EventHandler<TEventArgs>

>>> from System import EventHandler, EventArgs
>>> EventHandler # this is the combo type object
<types 'EventHandler', 'EventHandler[TEventArgs]'>
>>> # Access the non-generic type
>>> dir(EventHandler) #doctest: +ELLIPSIS
['BeginInvoke', 'Clone', 'DynamicInvoke', 'EndInvoke', ...
>>> # Access the generic type with 1 type paramter
>>> dir(EventHandler[EventArgs]) #doctest: +ELLIPSIS
['BeginInvoke', 'Call', 'Clone', 'Combine', ...

>>> clr.GetClrType(EventHandler[EventArgs]).Name
'EventHandler`1'

Accessing nested types

Nested types are exposed as attributes of the outer class:

>>> from System.Environment import SpecialFolder
>>> SpecialFolder
<type 'SpecialFolder'>

Importing .NET members from a type

.NET types are exposed as Python classes. Like Python classes, you usually cannot import all the attributes of .NET types using from <name> import *:

>>> from System.Guid import *
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: no module named Guid

You can import specific members, both static and instance:

>>> from System.Guid import NewGuid, ToByteArray
>>> g = NewGuid()
>>> ToByteArray(g) #doctest: +ELLIPSIS
Array[Byte](...

Note that if you import a static property, you will import the value when the import executes, not a named object to be evaluated on every use as you might mistakenly expect:

>>> from System.DateTime import Now
>>> Now #doctest: +ELLIPSIS
<System.DateTime object at ...>
>>> # Let's make it even more obvious that "Now" is evaluated only once
>>> a_second_ago = Now
>>> import time
>>> time.sleep(1)
>>> a_second_ago is Now
True
>>> a_second_ago is System.DateTime.Now
False

>>> from System.Environment import *
>>> Exit is System.Environment.Exit
True

>>> SpecialFolder is System.Environment.SpecialFolder
True

>>> OSVersion
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'OSVersion' is not defined
>>> System.Environment.OSVersion #doctest: +ELLIPSIS
<System.OperatingSystem object at ...>

Type-system unification (type and System.Type)

.NET represents types using System.Type. However, when you access a .NET type in Python code, you get a Python type object [2]:

>>> from System.Collections import BitArray
>>> ba = BitArray(5)
>>> isinstance(type(ba), type)
True

This allows a unified (Pythonic) view of both Python and .NET types. For example, isinstance works with .NET types as well:

>>> from System.Collections import BitArray
>>> isinstance(ba, BitArray)
True

If need to get the System.Type instance for the .NET type, you need to use clr.GetClrType. Conversely, you can use clr.GetPythonType to get a type object corresponding to a System.Type object.

The unification also extends to other type system entities like methods. .NET methods are exposed as instances of method:

>>> type(BitArray.Xor)
<type 'method_descriptor'>
>>> type(ba.Xor)
<type 'builtin_function_or_method'>

>>> isinstance(type(ba), type)
True
>>> type(ba) is type
False

>>> del list.append
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: cannot delete attribute 'append' of builtin type 'list'
>>>
>>> import System
>>> del System.DateTime.ToByteArray
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: can't set attributes of built-in/extension type 'DateTime'

Invoking .NET instance methods

Invoking .NET instance methods works just like invoking methods on a Python object using the attribute notation:

>>> from System.Collections import BitArray
>>> ba = BitArray(5)
>>> ba.Set(0, True) # call the Set method
>>> ba[0]
True

IronPython also supports named arguments:

>>> ba.Set(index = 1, value = True)
>>> ba[1]
True

IronPython also supports dict arguments:

>>> args = [2, True] # list of arguments
>>> ba.Set(*args)
>>> ba[2]
True

IronPython also supports keyword arguments:

>>> args = { "index" : 3, "value" : True }
>>> ba.Set(**args)
>>> ba[3]
True

Argument conversions

When the argument type does not exactly match the parameter type expected by the .NET method, IronPython tries to convert the argument. IronPython uses conventional .NET conversion rules like conversion operators , as well as IronPython-specific rules. This snippet shows how arguments are converted when calling the Set(System.Int32, System.Boolean) method:

>>> from System.Collections import BitArray
>>> ba = BitArray(5)
>>> ba.Set(0, "hello") # converts the second argument to True.
>>> ba[0]
True
>>> ba.Set(1, None) # converts the second argument to False.
>>> ba[1]
False

See appendix-type-conversion-rules for the detailed conversion rules. Note that some Python types are implemented as .NET types and no conversion is required in such cases. See builtin-type-mapping for the mapping.

Some of the conversions supported are:

Method overloads

.NET supports overloading methods by both number of arguments and type of arguments. When IronPython code calls an overloaded method, IronPython tries to select one of the overloads at runtime based on the number and type of arguments passed to the method, and also names of any keyword arguments. In most cases, the expected overload gets selected. Selecting an overload is easy when the argument types are an exact match with one of the overload signatures:

>>> from System.Collections import BitArray
>>> ba = BitArray(5) # calls __new__(System.Int32)
>>> ba = BitArray(5, True) # calls __new__(System.Int32, System.Boolean)
>>> ba = BitArray(ba) # calls __new__(System.Collections.BitArray)

The argument types do not have be an exact match with the method signature. IronPython will try to convert the arguments if an unamibguous conversion exists to one of the overload signatures. The following code calls __new__(System.Int32) even though there are two constructors which take one argument, and neither of them accept a float as an argument:

>>> ba = BitArray(5.0)

However, note that IronPython will raise a TypeError if there are conversions to more than one of the overloads:

>>> BitArray((1, 2, 3))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Multiple targets could match: BitArray(Array[Byte]), BitArray(Array[bool]), BitArray(Array[int])

If you want to control the exact overload that gets called, you can use the Overloads method on method objects:

>>> int_bool_new = BitArray.__new__.Overloads[int, type(True)]
>>> ba = int_bool_new(BitArray, 5, True) # calls __new__(System.Int32, System.Boolean)
>>> ba = int_bool_new(BitArray, 5, "hello") # converts "hello" to a System.Boolan
>>> ba = int_bool_new(BitArray, 5)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: __new__() takes exactly 2 arguments (1 given)

TODO - Example of indexing Overloads with an Array, byref, etc using Type.MakeByrefType

Using unbound class instance methods

It is sometimes desirable to invoke an instance method using the unbound class instance method and passing an explicit self object as the first argument. For example, .NET allows a class to declare an instance method with the same name as a method in a base type, but without overriding the base method. See System.Reflection.MethodAttributes.NewSlot for more information. In such cases, using the unbound class instance method syntax allows you chose precisely which slot you wish to call:

>>> import System
>>> System.ICloneable.Clone("hello") # same as : "hello".Clone()
'hello'

The unbound class instance method syntax results in a virtual call, and calls the most derived implementation of the virtual method slot:

>>> s = "hello"
>>> System.Object.GetHashCode(s) == System.String.GetHashCode(s)
True
>>> from System.Runtime.CompilerServices import RuntimeHelpers
>>> RuntimeHelpers.GetHashCode(s) == System.String.GetHashCode(s)
False

Calling explicitly-implemented interface methods

.NET allows a method with a different name to override a base method implementation or interface method slot. This is useful if a type implements two interfaces with methods with the same name. This is known as explicity implemented interface methods. For example, Microsoft.Win32.RegistryKey implements System.IDisposable.Dispose explicitly:

>>> from Microsoft.Win32 import RegistryKey
>>> clr.GetClrType(RegistryKey).GetMethod("Flush") #doctest: +ELLIPSIS
<System.Reflection.RuntimeMethodInfo object at ... [Void Flush()]>
>>> clr.GetClrType(RegistryKey).GetMethod("Dispose")
>>>

In such cases, IronPython tries to expose the method using its simple name - if there is no ambiguity:

>>> from Microsoft.Win32 import Registry
>>> rkey = Registry.CurrentUser.OpenSubKey("Software")
>>> rkey.Dispose()

However, it is possible that the type has another method with the same name. In that case, the explicitly implemented method is not accessible as an attribute. However, it can still be called by using the unbound class instance method syntax:

>>> rkey = Registry.CurrentUser.OpenSubKey("Software")
>>> System.IDisposable.Dispose(rkey)

Invoking static .NET methods

Invoking static .NET methods is similar to invoking Python static methods:

>>> System.GC.Collect()

Like Python static methods, the .NET static method can be accessed as an attribute of sub-types as well:

>>> System.Object.ReferenceEquals is System.GC.ReferenceEquals
True

TODO What happens if the sub-type has a static method with the same name but a different signature? Are both overloads available or not?

Invoking generic methods

Generic methods are exposed as attributes which can be indexed with type objects. The following code calls System.Activator.CreateInstance<T>

>>> from System import Activator, Guid
>>> guid = Activator.CreateInstance[Guid]()

Type parameter inference while invoking generic methods

In many cases, the type parameter can be inferred based on the arguments passed to the method call. Consider the following use of a generic method [3]:

>>> from System.Collections.Generic import IEnumerable, List
>>> list = List[int]([1, 2, 3])
>>> import clr
>>> clr.AddReference("System.Core")
>>> from System.Linq import Enumerable
>>> Enumerable.Any[int](list, lambda x : x < 2)
True

With generic type parameter inference, the last statement can also be written as:

>>> Enumerable.Any(list, lambda x : x < 2)
True

See appendix for the detailed rules.

ref and out parameters

The Python language passes all arguments by-value. There is no syntax to indicate that an argument should be passed by-reference like there is in .NET languages like C# and VB.NET via the ref and out keywords. IronPython supports two ways of passing ref or out arguments to a method, an implicit way and an explicit way.

In the implicit way, an argument is passed normally to the method call, and its (potentially) updated value is returned from the method call along with the normal return value (if any). This composes well with the Python feature of multiple return values. System.Collections.Generic.Dictionary has a method bool TryGetValue(K key, out value). It can be called from IronPython with just one argument, and the call returns a tuple where the first element is a boolean and the second element is the value (or the default value of 0.0 if the first element is False):

>>> d = { "a":100.1, "b":200.2, "c":300.3 }
>>> from System.Collections.Generic import Dictionary
>>> d = Dictionary[str, float](d)
>>> d.TryGetValue("b")
(True, 200.2)
>>> d.TryGetValue("z")
(False, 0.0)

In the explicit way, you can pass an instance of clr.Reference[T] for the ref or out argument, and its Value field will get set by the call. The explicit way is useful if there are multiple overloads with ref parameters:

>>> import clr
>>> r = clr.Reference[float]()
>>> d.TryGetValue("b", r)
True
>>> r.Value
200.2

Extension methods

Extension methods are currently not natively supported by IronPython. Hence, they cannot be invoked like instance methods. Instead, they have to be invoked like static methods.

Non-default .NET indexers

Note that a default indexer is just a property (typically called Item) with one argument. It is considered as an indexer if the declaraing type uses DefaultMemberAttribute to declare the property as the default member.

See property-with-parameters for information on non-default indexers.

Properties with parameters

COM and VB.NET support properties with paramters. They are also known as non-default indexers. C# does not support declaring or using properties with parameters.

IronPython does support properties with parameters. For example, the default indexer above can also be accessed using the non-default format as such:

>>> ba.Item[0]
False

.NET arrays

IronPython supports indexing of System.Array with a type object to access one-dimensional strongly-typed arrays:

>>> System.Array[int]
<type 'Array[int]'>

IronPython also adds a __new__ method that accepts a IList<T> to initialize the array. This allows using a Python list literal to initialize a .NET array:

>>> a = System.Array[int]([1, 2, 3])

Further, IronPython exposes __getitem__ and __setitem__ allowing the array objects to be indexed using the Python indexing syntax:

>>> a[2]
3

Note that the indexing syntax yields Python semantics. If you index with a negative value, it results in indexing from the end of the array, whereas .NET indexing (demonstrated by calling GetValue below) raises a System.IndexOutOfRangeException exception:

>>> a.GetValue(-1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: Index was outside the bounds of the array.
>>> a[-1]
3

Similarly, slicing is also supported:

>>> a[1:3]
Array[int]((2, 3))

.NET Exceptions

raise can raise both Python exceptions as well as .NET exceptions:

>>> raise ZeroDivisionError()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError
>>> import System
>>> raise System.DivideByZeroException()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: Attempted to divide by zero.

The except keyword can catch both Python exceptions as well as .NET exceptions:

>>> try:
...    import System
...    raise System.DivideByZeroException()
... except System.DivideByZeroException:
...    print "This line will get printed..."
...
This line will get printed...
>>>

>>> e = ZeroDivisionError()
>>> e.foo = 1 # this works
>>> e = System.DivideByZeroException()
>>> e.foo = 1
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'DivideByZeroException' object has no attribute 'foo'

>>> import clr
>>> try:
...     1/0
... except ZeroDivisionError as e:
...     pass
>>> type(e)
<type 'exceptions.ZeroDivisionError'>
>>> type(e.clsException)
<type 'DivideByZeroException'>

>>> e.clsException.Data["PythonExceptionInfo"] #doctest: +ELLIPSIS
<IronPython.Runtime.Exceptions.PythonExceptions+ExceptionDataWrapper object at ...>

>>> import System
>>> try:
...     try:
...         1/0
...     except System.DivideByZeroException as e1:
...         raise e1
... except ZeroDivisionError as e2:
...     pass
>>> type(e1)
<type 'DivideByZeroException'>
>>> type(e2)
<type 'exceptions.ZeroDivisionError'>
>>> e2.clsException is e1
True

>>> # since "Exception" might be System.Exception after "from System import *"
>>> if "Exception" in globals(): del Exception
>>> class MyException(Exception):
...     def __init__(self, value):
...         self.value = value
...     def __str__(self):
...         return repr(self.value)
>>> try:
...     raise MyException("some message")
... except System.Exception as e:
...     pass
>>> clr.GetClrType(type(e)).FullName
'System.Exception'
>>> e.Message
'Python Exception: MyException'

Enumerations

.NET enumeration types are sub-types of System.Enum. The enumeration values of an enumeration type are exposed as class attributes:

print System.AttributeTargets.All # access the value "All"

IronPython also supports using the bit-wise operators with the enumeration values:

>>> import System
>>> System.AttributeTargets.Class | System.AttributeTargets.Method
<enum System.AttributeTargets: Class, Method>

Value types

Python expects all mutable values to be represented as a reference type. .NET, on the other hand, introduces the concept of value types which are mostly copied instead of referenced. In particular .NET methods and properties returning a value type will always return a copy.

This can be confusing from a Python programmer’s perspective since a subsequent update to a field of such a value type will occur on the local copy, not within whatever enclosing object originally provided the value type.

While most .NET value types are designed to be immutable, and the .NET design guidelines recommend value tyeps be immutable, this is not enforced by .NET, and so there do exist some .NET valuetype that are mutable. TODO - Example.

For example, take the following C# definitions:

struct Point {
    # Poorly defined struct - structs should be immutable
    public int x;
    public int y;
}

class Line {
    public Point start;
    public Point end;

    public Point Start { get { return start; } }
    public Point End { get { return end; } }
}

If line is an instance of the reference type Line, then a Python programmer may well expect "line.Start.x = 1" to set the x coordinate of the start of that line. In fact the property Start returned a copy of the Point value type and it’s to that copy the update is made:

print line.Start.x    # prints ‘0’
line.Start.x = 1
print line.Start.x    # still prints ‘0’

This behavior is subtle and confusing enough that C# produces a compile-time error if similar code is written (an attempt to modify a field of a value type just returned from a property invocation).

Even worse, when an attempt is made to modify the value type directly via the start field exposed by Line (i.e. “`line.start.x = 1`”), IronPython will still update a local copy of the Point structure. That’s because Python is structured so that “foo.bar” will always produce a useable value: in the case above “line.start” needs to return a full value type which in turn implies a copy.

C#, on the other hand, interprets the entirety of the “`line.start.x = 1`” statement and actually yields a value type reference for the “line.start” part which in turn can be used to set the “x” field in place.

This highlights a difference in semantics between the two languages. In Python “line.start.x = 1” and “foo = line.start; foo.x = 1” are semantically equivalent. In C# that is not necessarily so.

So in summary: a Python programmer making updates to a value type embedded in an object will silently have those updates lost where the same syntax would yield the expected semantics in C#. An update to a value type returned from a .NET property will also appear to succeed will updating a local copy and will not cause an error as it does in the C# world. These two issues could easily become the source of subtle, hard to trace bugs within a large application.

In an effort to prevent the unintended update of local value type copies and at the same time preserve as pythonic and consistent a view of the world as possible, direct updates to value type fields are not allowed by IronPython, and raise a ValueError:

>>> line.start.x = 1 #doctest: +SKIP
Traceback (most recent call last):
   File , line 0, in input##7
ValueError Attempt to update field x on value type Point; value type fields can not be directly modified

This renders value types “mostly” immutable; updates are still possible via instance methods on the value type itself.

Proxy types

IronPython cannot directly use System.MarshalByRefObject instances. IronPython uses reflection at runtime to determine how to access an object. However, System.MarshalByRefObject instances do not support reflection.

You can use unbound-class-instance-method syntax to call methods on such proxy objects.

Delegates

Python functions and bound instance methods can be converted to delegates:

>>> from System import EventHandler, EventArgs
>>> def foo(sender, event_args):
...     print event_args
>>> d = EventHandler(foo)
>>> d(None, EventArgs()) #doctest: +ELLIPSIS
<System.EventArgs object at ... [System.EventArgs]>

>>> def foo(*args):
...     print args
>>> d = EventHandler(foo)
>>> d(None, EventArgs()) #doctest: +ELLIPSIS
(None, <System.EventArgs object at ... [System.EventArgs]>)

>>> def foo(*args):
...     return 100 # this return value will get ignored
>>> d = EventHandler(foo)
>>> d(None, EventArgs())

>>> def foo(str1, str2):
...     return 100.1 # this return value will get converted to an int
>>> d = System.Comparison[str](foo)
>>> d("hello", "there")
100

Methods with multiple overloads

Python does not support method overloading. A class can have only one method with a given name. As a result, you cannot override specific method overloads of a .NET sub-type. Instead, you need to use define the function accepting an arbitrary argument list (see _tut-arbitraryargs), and then determine the method overload that was invoked by inspecting the types of the arguments:

>>> import clr
>>> import System
>>> StringComparer = System.Collections.Generic.IEqualityComparer[str]
>>>
>>> class MyComparer(StringComparer):
...     def GetHashCode(self, *args):
...          if len(args) == 0:
...              # Object.GetHashCode() called
...              return 100
...
...          if len(args) == 1 and type(args[0]) == str:
...              # StringComparer.GetHashCode() called
...              return 200
...
...          assert("Should never get here")
...
>>> comparer = MyComparer()
>>> getHashCode1 = clr.GetClrType(System.Object).GetMethod("GetHashCode")
>>> args = System.Array[object](["another string"])
>>> getHashCode2 = clr.GetClrType(StringComparer).GetMethod("GetHashCode")
>>>
>>> # Use Reflection to simulate a call to the different overloads
>>> # from another .NET language
>>> getHashCode1.Invoke(comparer, None)
100
>>> getHashCode2.Invoke(comparer, args)
200

Methods with ref or out parameters

Python does not have syntax for specifying whether a method paramter is passed by-reference since arguments are always passed by-value. When overriding a .NET method with ref or out parameters, the ref or out paramter is received as a clr.Reference[T] instance. The incoming argument value is accessed by reading the Value property, and the resulting value is specified by setting the Value property:

>>> import clr
>>> import System
>>> StrFloatDictionary = System.Collections.Generic.IDictionary[str, float]
>>>
>>> class MyDictionary(StrFloatDictionary):
...     def TryGetValue(self, key, value):
...         if key == "yes":
...             value.Value = 100.1 # set the *out* parameter
...             return True
...         else:
...             value.Value = 0.0  # set the *out* parameter
...             return False
...     # Other methods of IDictionary not overriden for brevity
...
>>> d = MyDictionary()
>>> # Use Reflection to simulate a call from another .NET language
>>> tryGetValue = clr.GetClrType(StrFloatDictionary).GetMethod("TryGetValue")
>>> args = System.Array[object](["yes", 0.0])
>>> tryGetValue.Invoke(d, args)
True
>>> args[1]
100.1

Generic methods

When you override a generic method, the type parameters get passed in as arguments. Consider the following generic method declaration:

// csc /t:library /out:convert.dll convert.cs
public interface IMyConvertible {
    T1 Convert<T1, T2>(T2 arg);
}

The following code overrides the generic method Convert:

>>> import clr
>>> clr.AddReference("convert.dll")
>>> import System
>>> import IMyConvertible
>>>
>>> class MyConvertible(IMyConvertible):
...     def Convert(self, t2, T1, T2):
...         return T1(t2)
>>>
>>> o = MyConvertible()
>>> # Use Reflection to simulate a call from another .NET language
>>> type_params = System.Array[System.Type]([str, float])
>>> convert = clr.GetClrType(IMyConvertible).GetMethod("Convert")
>>> convert_of_str_float = convert.MakeGenericMethod(type_params)
>>> args = System.Array[object]([100.1])
>>> convert_of_str_float.Invoke(o, args)
'100.1'

Calling from Python

When you call a method from Python, and the method overrides a .NET method from a base type, the call is performed as a regular Python call. The arguments do not undergo conversion, and neither are they modified in any way like being wrapped with clr.Reference. Thus, the call may need to be written differently than if the method was overriden by another language. For example, trying to call TryGetValue on the MyDictionary type from the overriding-ref-args section as shown below results in a TypeError, whereas a similar call works with System.Collections.Generic.Dictionary[str, float]:

>>> result, value = d.TryGetValue("yes")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: TryGetValue() takes exactly 3 arguments (2 given)

Hashing of mutable objects

The CLR expects that System.Object.GetHashCode always returns the same value for a given object. If this invariant is not maintained, using the object as a key in a System.Collections.Generic.Dictionary<K,V> will misbehave. Python allows __hash__ to return different results, and relies on the user to deal with the scenario of using the object as a key in a Hash. The mapping above between the Python and CLR concepts of equality and hashing means that CLR code that deals with Python objects has to be aware of the issue. If static MSIL code uses a Python object as a the key in a Dictionary<K,V>, unexpected behavior might happen.

To reduce the chances of this happenning when using common Python types, IronPython does not map __hash__ to GetHashCode for Array and Hash. For other Python classes, the user can provide separate implementations for __eq__ and Equals, and __hash__ and GetHashCode if the Python class is mutable but also needs to be usable as a key in a Dictionary<K,V>.

ToString on Python objects

Calling ToString on Python objects calls the default System.Object.ToString implementation, even if the Python type defines __str__:

>>> class MyClass(object):
...     def __str__(self):
...         return "__str__ result"
>>> o = MyClass()
>>> # Use Reflection to simulate a call from another .NET language
>>> o.GetType().GetMethod("ToString").Invoke(o, None) #doctest: +ELLIPSIS
'IronPython.NewTypes.System.Object_...'

__repr__/__str__ on .NET objects

All Python user types have __repr__ and __str__:

>>> class MyClass(object):
...     pass
>>> o = MyClass()
>>> o.__repr__() #doctest: +ELLIPSIS
'<MyClass object at ...>'
>>> o.__str__() #doctest: +ELLIPSIS
'IronPython.NewTypes.System.Object_...'
>>> str(o) #doctest: +ELLIPSIS
'<MyClass object at ...>'

For .NET types which do not override ToString, IronPython provides __repr__ and __str__ methods which behave similar to those of Python user types [10]:

>>> from System.Collections import BitArray
>>> ba = BitArray(5)
>>> ba.ToString() # BitArray inherts System.Object.ToString()
'System.Collections.BitArray'
>>> ba.__repr__() #doctest: +ELLIPSIS
'<System.Collections.BitArray object at ... [System.Collections.BitArray]>'
>>> ba.__str__() #doctest: +ELLIPSIS
'<System.Collections.BitArray object at ... [System.Collections.BitArray]>'

For .NET types which do override ToString, IronPython includes the result of ToString in __repr__, and maps ToString directly to __str__:

>>> e = System.Exception()
>>> e.ToString()
"System.Exception: Exception of type 'System.Exception' was thrown."
>>> e.__repr__() #doctest: +ELLIPSIS
"<System.Exception object at ... [System.Exception: Exception of type 'System.Exception' was thrown.]>"
>>> e.__str__() #doctest:
"System.Exception: Exception of type 'System.Exception' was thrown."

For Python types that override ToString, __str__ is mapped to the ToString override:

>>> class MyClass(object):
...     def ToString(self):
...         return "ToString implemented in Python"
>>> o = MyClass()
>>> o.__repr__() #doctest: +ELLIPSIS
'<MyClass object at ...>'
>>> o.__str__()
'ToString implemented in Python'
>>> str(o) #doctest: +ELLIPSIS
'<MyClass object at ...>'

Properties

There is one important detail worth pointing out. IronPython tries to use the type library of the OleAut object if it can be found, in order to do name resolution while accessing methods or properties. The reason for this is that the IDispatch interface does not make much of a distinction between properties and method calls. This is because of Visual Basic 6 semantics where "excel.Quit" and "excel.Quit()" have the exact same semantics. However, IronPython has a strong distinction between properties and methods, and methods are first class objects. For IronPython to know whether "excel.Quit" should invoke the method Quit, or just return a callable object, it needs to inspect the typelib. If a typelib is not available, IronPython assumes that it is a method. So if a OleAut object has a property called "prop" but it has no typelib, you would need to write "p = obj.prop()" in IronPython to read the property value.

Methods with out parameters

Calling a method with "out" (or in-out) parameters requires explicitly passing in an instance of "clr.Reference", if you want to get the updated value from the method call. Note that COM methods with out parameters are not considered Automation-friendly [11]. JScript does not support out parameters at all. If you do run into a COM component which has out parameters, having to use "clr.Reference" is a reasonable workaround:

>>> import clr
>>> from System import Type, Activator
>>> command_type = Type.GetTypeFromProgID("ADODB.Command")
>>> command = Activator.CreateInstance(command_type)
>>> records_affected = clr.Reference[int]()
>>> command.Execute(records_affected, None, None) #doctest: +SKIP
>>> records_affected.Value
0

Another workaround is to leverage the inteorp assembly by using the unbound class instance method syntax of "outParamAsReturnValue = InteropAssemblyNamespace.IComInterface(comObject)".

import clr and builtin types

Since some Python builtin types are implemented as .NET types, the question arises whether the types work like Python types or like .NET types. The answer is that by default, the types work like Python types. However, if a module executes import clr, the types work like both Python types and like .NET types. For example, by default, object' does not have the System.Object method called GetHashCode:

>>> hasattr(object, "__hash__")
True
>>> # Note that this assumes that "import clr" has not yet been executed
>>> hasattr(object, "GetHashCode") #doctest: +SKIP
False

However, once you do import clr, object has both __hash__ as well as GetHashCode:

>>> import clr
>>> hasattr(object, "__hash__")
True
>>> hasattr(object, "GetHashCode")
True

Feature by feature comparison

LINQ consists of a number of language and .NET features, and IronPython has differing levels of support for the different features:

• C# and VB.NET lambda function - Python supports lambda functions already.
• Anonymous types - Python has tuples which can be used like anonymous types.
• Extension methods - See
• Generic method type parameter inference - See
• Expression trees - This is not supported. This is the main reason DLinq does not work.