## IronPython 1.0.1 Frequently Asked Questions

#### Q: Is this license OSI compliant?

A: This license has not been submitted to OSI, but it allows developers to take full advantage of a dynamic language on the CLR and to have the freedom to distribute their works for the benefit of the community at large. The license is half of a page long and very straight forward. We believe it stands up to what developers demand of an "open" license.

#### Q: What copyright rights does the license grant me?

A: The license grants you a copyright license to make unlimited copies of the Software in source or object code form, as well as to create Derivative Works (as that term is defined under US copyright law). This means that in addition to making unlimited copies of the Software, you have a copyright license to modify the Software and to use all or part of the Software to create a Derivative Work.

#### Q: What patent rights does the license grant me?

A: This license grants you a patent license to use and distribute the Software under any Microsoft patent claims that read on the Software itself. In other words, if you create a modified version of the Software, you still retain the patent license to use and distribute the original portions of the Software under the specific Microsoft patent claims that read on the Software, but you do not have a patent license as to the new functionality you may have added by modifying the Software. This result is typical of many common open source licenses, including the Common Public License (CPL) and the Mozilla Public License (MPL). In addition, this license grants no rights to any Microsoft patents that read on other components or files not included in the Software. This means that no patent license is granted to use or distribute any other software or technology that may be needed to use the Software or was created from the Software (for example, any compiled output of the Software, the combination of the Software with other hardware or other software, or any additional enabling technologies that may be necessary to make or use the Software or any final product that includes the Software).

##

## Technical Frequently Asked Questions

### Q: How do I report a bug or get help?

A: On CodePlex you can file bugs by selecting the "Issue Tracker" tab and clicking on "New Work Item". On the home page you'll see a link to join our mailing list.

### Q: Is there Visual Studio integration for completion, coloring, WinForms designer, etc.?

A good explanation of the Visual Studio IronPython integration sample is in this blog post.

### Q: Why do you require .NET 2.0 to run IronPython 1.0.1?

A: There are a lot of features in .NET 2.0 that we wanted to use in IronPython. These include generics, DynamicMethods, new kinds of delegates, and more. We could have supported these new features using #ifdefs to keep a version of the code base that ran on 1.1. We decided that backwards compatibility wasn’t worth complicating the code base and development of IronPython at this time. We expect that when we start working on adding support for new .NET 3.0 features to IronPython that we’ll do them in the #ifdef or similar way so that IronPython will continue to run on .NET 2.0 for the foreseeable future.

### Q: Why does IronPython not follow the standard C# naming conventions, why so many FxCop errors?

A: We have fixed all FxCop errors in the IronPython.Hosting namespace which is the main public API exposed by IronPython. However, there are other public types that are marked public either because the generated IL code needs them or because of historical reasons. While we would like to fix all FxCop issues for all public types, those remaining do not affect users of IronPython. We want to release IronPython 1.0.1 under the principles of "release early, release often". We thought that it was unnecessary to delay the release to take the time to do this work first. These kinds of issues will be resolved as we work on future releases.

### Q: Why am I getting errors when trying to use WinForms?

A: One common error that you may be getting is:

>     C:\IronPython>ipy.exe
>     IronPython 1.0.2424 on .NET 2.0.50727.42
>     Copyright (c) Microsoft Corporation. All rights reserved.
>     >>> import System.Windows.Forms as WinForms
>     Traceback (most recent call last):
>     File , line 0, in -toplevel-
>     AttributeError: 'package#' object has no attribute 'Windows'

The cause is that IronPython needs help finding any assemblies that are even a little bit out of the ordinary. The Built-in module clr provides functions to add references to .NET modules (clr.AddReference). For more information, see the Loading .NET Libraries exercise in the IronPython Tutorial (if you're reading the FAQ on the web, the tutorial.htm document is in the tutorial directory where you installed IronPython).

### Q: How do I make use of .NET features in IronPython?

A: Users have to opt in to this functionality. No new keywords have been added, and the existing language semantics are unchanged. A "clr" module is available for import to turn on .NET extensions. See the IronPython Tutorial for good examples (if you're reading the FAQ on the web, the tutorial.htm document is in the tutorial directory where you installed IronPython). Using the "import clr" statement adds methods to built-in types in some cases; for example, dir(int) will show a ToString attribute. Such effects only happen in the context of the module that contains the "import clr" statement.

### Q: How do I import .NET namespaces from assemblies other than System and Mscorlib?

A: IronPython can directly import only some of the .NET libraries -- the most commonly used ones. To use additional .NET assemblies, they must be explicitly referenced. To add a reference to a .NET assembly, use one of the clr.AddReference* functions. See IronPython Tutorial for good examples and instruction on how to do this (if you're reading the FAQ on the web, the tutorial.htm document is in the tutorial directory where you installed IronPython).

### Q: How do I use CPython standard libraries?

A: To tell IronPython where the Python standard library is, you can add the "lib" directory of CPython to IronPython's path. To do this, put the following code into IronPython's "site.py" file (replace c:\python24\lib with your actual path to the CPython lib directory):

>     import sys
>     sys.path.append(r"c:\python24\lib")

### Q: Why are some built-in modules not present?

A: IronPython implements all the commonly used built-in modules. Some modules are not implemented because they are OS-specific (for example, they are only relevant on SGI or the Mac). Some modules aren't present only because we didn't have time to implement them yet. See the IronPython Differences document for details.

### Q: What CPython version are you compatible with?

A: IronPython 1.0.1 targeted CPython 2.4.3 for compatibility. See the IronPython Differences document for details.

### Q: Do you have any 2.5 features working?

A: Yes, IronPython implements several 2.5 features: all(), any(), max() with a key argument, min() with a key argument, partition() and rpartition() on strings, the with statement, empty parenthetic expression for the bases classes in a class statement, try-except-finally, and ternary expressions

### Q: Do we work with the .NET Compact Framework?

A: No, IronPython 1.0.1 targets only the .NET 2.0 Common Language Runtime. The .NET Compact Framework lacks Reflection.Emit and lightweight code generation (dynamic methods), both of which IronPython requires.

### Q: How do I compile .py files to a DLL for linking into my C# or VB program?

A: IronPython does not support building DLLs for a C# style of linking and calling into Python code. You can define interfaces in C#, build those into a DLL, and then implement those interfaces in Python code as well as pass the python objects that implement the interfaces to C# code.

### Q: How do I build and call into PYD libraries?

A: IronPython does not support using PYDs built for CPython since they leverage implementation details of CPython. You can get a similar effect for new "PYD"s you would like to implement by writing them in C# or VB and building a DLL for .NET.

### Q: How do I create, or why don't you create .pyc files?

A: IronPython does not cache binary products for .py files, nor write fast loading version of .py files. IronPython will likely support this kind of optimization in the future.

### Q: How do I choose amongst a method's overloads?

A: .NET methods may have an Overloads attribute which can be indexed by a tuple of types to choose between overloads of a .NET method. For example, the following chooses the WriteLine method that takes an object and passes None for it:

> from System import Console
> Console.WriteLine.Overloads[object](None)

### Q: How can I call a method with ref, out, and params parameters?

A: Consider the following C# class which defines methods with ref, out, and params parameters. Following the C# code are examples in the Python interpreter of calling these methods.

> File a.cs (compiled with "csc.exe /t:library a.cs"):

> public class C {
> public static int MethodRef(ref int i) { i = 1; return 2; }
> public static int MethodOut(out int i) { i = 1; return 2; }
> public static int MethodParams(params object[] values) { return values.Length; }
> }

Loading the class C:

> >>> import clr
> >>> clr.AddReference("a.dll")
> >>> import C

Calling the method with ref parameters: if you pass the value (3) directly, the output value will become part of the returned tuple.

> >>> C.MethodRef(3)
> (2, 1)

Alternatively, you can create an instance of clr.Reference<T> and initialize it with the value that you want to pass into the method. When the call returns, the value will have been updated.

> >>> import clr
> >>> x = clr.Reference[int](3)
> >>> x.Value
> 3
> >>> C.MethodRef(x)
> 2
> >>> x.Value
> 1

Calling the method with an out parameter is very similar, except there is no need to provide the input value. The values of the out parameters will become part of the returned tuple:

> >>> C.MethodOut()
> (2, 1)

You can also provide an instance of clr.Reference<T> to capture the value of the out parameter. The initial value in this case does not matter.

> >>> x = clr.Reference[int]()
> >>> x.Value # The Value is initialized to 0
> 0
> >>> C.MethodOut(x)
> 2
> >>> x.Value # Value was modified by the MethodOut method.
> 1
> >>> x.Value = 10
> >>> C.MethodOut(x)
> 2
> >>> x.Value
> 1

IronPython handles methods with params arguments in a natural way. The parameters can be passed as a parameter list:

> >>> C.MethodParams(1,2,3)
> 3
> >>> C.MethodParams(1,2,3,4,5,6,)
> 6

### Q: How do I create a .NET array?

A: Here is an example that shows how to create a .NET array: "System.Array[int]((1,2,3))".

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

Here is another example that creates a multi-dimensional array of arrays and initializes it (any kind of Python sequence can be used to initialize the array):

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

If you want to create a true multi-dimensional array and set elements, you can do the following :

> x = Array.CreateInstance(int, Array[int]((1,2,3)))
> x[0,1,2] = 2

### Q: How do I specify generic types, such as collections?

A: IronPython supports an indexing-like syntax for identifying concrete realizations of generic types and methods, for example:

> import System
> q = System.Collections.Generic.Queue[str]()

This is similar to creating a .NET array.

### Q: How can I access .NET properties and indexers?

A: The following is a simple example of setting and getting the value of a property "Text" on a windows form. The syntax is the same as any attribute access.

> >>> import System
> >>> clr.AddReference("System.Windows.Forms")
> >>> from System.Windows.Forms import Form
> >>> f = Form()
> >>> f.Text = "Hello" # Set the property
> >>> f.Text # Get the property value
> 'Hello'
> >>>

To call indexers, use Python's indexing syntax:

> >>> import System
> >>> h = System.Collections.Hashtable()
> >>> h['a'] = 10
> >>> h['a']
> 10

### Q: How does IronPython handle conversions between Python types and .NET types?

A: IronPython runs on the .NET Framework which provides more primitive types than Python. If you use normal Python code with IronPython, you will only encounter the standard Python types (int, long, float, str, ...). When calling .NET methods, IronPython will try to convert the argument values to the appropriate .NET types. See below for an example with integer numbers.

> File a.cs (compiled with "csc.exe /t:library a.cs"):

> public class C {
> public static void MethodUShort(ushort p) { }
> }

The following Python code calls the "MethodUShort" on class C with different argument values:

> >>> import clr
> >>> clr.AddReference("a.dll")
> >>> import C
> >>> C.MethodUShort(1) # conversion will succeed
> >>> C.MethodUShort(65536) # 65536 won't fit into System.UInt16
> Traceback (most recent call last):
> File , line 0, in <stdin>##20
> File , line 0, in MethodUShort##19
> OverflowError: Arithmetic operation resulted in an overflow.
> >>> C.MethodUShort(-1) # neither will -1
> Traceback (most recent call last):
> File , line 0, in <stdin>##21
> File , line 0, in MethodUShort##19
> OverflowError: Arithmetic operation resulted in an overflow.

### Q: How does IronPython work with the .NET System.Char type since Python doesn't have a char type?

A: In IronPython, all strings of length 1 will be automatically coerced into System.Char type when System.Char type is expected. If a method returns System.Char type, the actual return value will be an instance of System.Char type, but the value can be easily converted to string:

> >>> x = System.Char.Parse('a')
> >>> x
> <System.Char object at 0x000000000000002C [a]>
> >>> str(x)
> 'a'

### Q: How does IronPython work with .NET structs, value types, enums?

A: All instances of value types are always boxed within the IronPython runtime. For more details, refer to the document on CodePlex.

### Q: How do .NET assemblies and namespaces relate to Python modules?

A: In IronPython, the import mechanism provides access to the namespaces in .NET assemblies. Once the assembly is referenced by the IronPython runtime, it is possible to import the namespaces contained within the assembly. Once a namespace is imported, all nested namespaces are also accessible. For more information, see the Loading .NET Libraries exercise in the IronPython Tutorial (if you're reading the FAQ on the web, the tutorial.htm document is in the tutorial directory where you installed IronPython).

> >>> import System
> >>> clr.AddReference("System.Windows.Forms")
> >>> import System.Windows
> >>> form = System.Windows.Forms.Form()

### Q: How does IronPython's threading model relate to CPython's with respect to object operations?

A: CPython has a Global Interpreter Lock, and it interprets opcodes for operations on primitive types atomically. IronPython also ensures operations on primitive types are atomic (for example, inserting into a list or removing an item at a specific index). However, IronPython's in-place addition operations (for example, "l = []; l += [2,3,4]") are not atomic, so if two threads perform this operation, "l" could end up with interleaving values. Furthermore, IronPython looks up an operation's implementation method atomically and then invokes the method atomically. Between the time of the look up and the invoke, another thread could execute that replaced the definition of the operation, and the first thread would invoke the old definition it found. If a program's behavior needs to be guaranteed across this sort of scenario, your program should be ensuring this level of thread safety; the CPython specification makes no guarantees in this situation either.

### Q: Why does ipy.exe appear to access the internet sometimes?

A: Microsoft signs its DLLs so that they can be verified as coming from Microsoft. Because ipy.exe is using DLLs that are signed, the .NET CLR tries to confirm the certificates that were used to sign the DLLs. When it does this, you may notice internet traffic to a certification service for signed binaries, and you may notice performance impact on start up. For a good discussion of this topic, please see Authenticode and Assemblies.