- Python for .NET-Python for .NET is a package that gives Python programmers - nearly seamless integration with the .NET Common Language Runtime - (CLR) and provides a powerful application scripting tool for .NET - developers. Using this package you can script .NET applications or - build entire applications in Python, using .NET services and - components written in any language that targets the CLR (Managed - C++, C#, VB, JScript). -Note that this package does not implement Python as a - first-class CLR language - it does not produce managed code (IL) - from Python code. Rather, it is an integration of the C Python - engine with the .NET runtime. This approach allows you to use use - CLR services and continue to use existing Python code and C-based - extensions while maintaining native execution speeds for Python - code. If you are interested in a pure managed-code implementation - of the Python language, you should check out the IronPython - project, which is in active development. -Python for .NET is currently compatible with Python releases 2.5 - and greater. To subscribe to the - Python for .NET mailing list or read the - online archives of the list, see the - mailing list information page. You can also send questions - or comments to me at brian.lloyd@revolution.com - or use the - Python for .NET issue tracker to report issues. -My blog site is - also (sometimes) a good source for more information on Python for - .NET ;) -
|
-
- Python for .NET-
|
-
- Python for .NET is a package that gives Python programmers - nearly seamless integration with the .NET Common Language Runtime - (CLR) and provides a powerful application scripting tool for .NET - developers. Using this package you can script .NET applications or - build entire applications in Python, using .NET services and - components written in any language that targets the CLR (Managed - C++, C#, VB, JScript). - -Note that this package does not implement Python as a - first-class CLR language - it does not produce managed code (IL) - from Python code. Rather, it is an integration of the C Python - engine with the .NET runtime. This approach allows you to use use - CLR services and continue to use existing Python code and C-based - extensions while maintaining native execution speeds for Python - code. If you are interested in a pure managed-code implementation - of the Python language, you should check out the IronPython - project, which is in active development. - -Python for .NET is currently compatible with Python releases 2.3 - and greater. Current releases are available at the - Python for .NET website . To subscribe to the - Python for .NET mailing list or read the - online archives of the list, see the - mailing list information page. - -Installation-Python for .NET is available as a source release and as a - Windows installer for various versions of Python and the common - language runtime from the - Python for .NET website . On Windows platforms, you can - choose to install .NET-awareness into an existing Python - installation as well as install Python for .NET as a standalone - package. - - -The source release is a self-contained "private" assembly. Just - unzip the package wherever you want it, cd to that directory and - run python.exe to start using it. Note that the source release - does not include a copy of the CPython runtime, so you will need - to have installed Python on your machine before using the source - release. - -Running on Linux/Mono: preliminary testing - shows that PythonNet will run under Mono, - though the Mono runtime is not yet complete so there still may be - problems. The Python for .NET integration layer is 100% managed - code, so there should be no long-term issues under Mono - it - should work better and better as the Mono platform matures. - -Note that if you are running under Mono on a *nix system, you - will need to have a compatible version of Python installed. You - will also need to create a symbolic link to the copy of - libpython2.x.so (in your existing Python installation) in the - PythonNet directory. This is needed to ensure that the mono - interop dll loader will find it by name. For example: - -ln -s /usr/lib/libpython2.4.so ./python24.so -- - Getting Started-A key goal for this project has been that Python for .NET should - "work just the way you'd expect in Python", except for cases that - are .NET specific (in which case the goal is to work "just the way - you'd expect in C#"). In addition, with the IronPython project - gaining traction, it is my goal that code written for IronPython - run without modification under Python for .NET. - -If you already know Python, you can probably finish this readme - and then refer to .NET docs to figure out anything you need to do. - Conversely if you are familiar with C# or another .NET language, - you probably just need to pick up one of the many good Python - books or read the Python tutorial online to get started. - -A good way to start is to run python.exe and - follow along with the examples in this document. If you get stuck, - there are also a number of demos and unit tests located in the - source directory of the distribution that can be helpful as - examples. - -Note that if you have installed CLR support into your existing - Python installation (rather than using the included python.exe), - you will need to use the line: "'import clr" (lower-case!) to - initially load the clr extension module before trying the - following examples. - - -Importing Modules-Python for .NET allows CLR namespaces to be treated essentially - as Python packages. -- -from System import String - from System.Collections import * --
- Note that earlier releases of Python for .NET required you to
- import modules through a special top-level package named Types from any loaded assembly may be imported and used in this - manner. To load an assembly, use the "AddReference" function in - the "clr" module: - -
- import clr
- clr.AddReference("System.Windows.Forms")
- from System.Windows.Forms import Form
-
-
- - Note that earlier releases of Python for .NET relied on - "implicit loading" to support automatic loading of assemblies - whose names corresponded to an imported namespace. Implicit - loading still works for backward compatibility, but will be - removed in a future release so it is recommended to use the - clr.AddReference method. - - - Python for .NET uses the PYTHONPATH (sys.path) to look for
- assemblies to load, in addition to the usual application base and
- the GAC. To ensure that you can implicitly import an assembly, put
- the directory containing the assembly in Using Classes-Python for .NET allows you to use any non-private classes, - structs, interfaces, enums or delegates from Python. To create an - instance of a managed class, you use the standard instantiation - syntax, passing a set of arguments that match one of its public - constructors: - -from System.Drawing import Point - - p = Point(5, 5) -- In most cases, Python for .NET can determine the correct - constructor to call automatically based on the arguments. In some - cases, it may be necessary to call a particular overloaded - constructor, which is supported by a special "__overloads__" - attribute, which will soon be deprecated in favor of iPy - compatible "Overloads", on a class: - - from System import String, Char, Int32
-
- s = String.Overloads[Char, Int32]('A', 10)
- s = String.__overloads__[Char, Int32]('A', 10)
-
-
- Using Generics-When running under versions of the .NET runtime greater than - 2.0, you can use generic types. A generic type must be bound to - create a concrete type before it can be instantiated. Generic - types support the subscript syntax to create bound types: - -from System.Collections.Generic import Dictionary - from System import * - - dict1 = Dictionary[String, String]() - dict2 = Dictionary[String, Int32]() - dict3 = Dictionary[String, Type]() -- When you pass a list of types using the subscript syntax, you - can also pass a subset of Python types that directly correspond to - .NET types: - -dict1 = Dictionary[str, str]() - dict2 = Dictionary[str, int]() - dict3 = Dictionary[str, Decimal]() -- This shorthand also works when explicitly selecting generic - methods or specific versions of overloaded methods and - constructors (explained later). - - You can also subclass managed classes in Python, though members
- of the Python subclass are not visible to .NET code. See the Fields And Properties-You can get and set fields and properties of CLR objects just as - if they were regular attributes: - -from System import Environment - - name = Environment.MachineName - Environment.ExitCode = 1 -- - Using Indexers-If a managed object implements one or more indexers, you can - call the indexer using standard Python indexing syntax: - -from System.Collections import Hashtable - - table = Hashtable() - table["key 1"] = "value 1" -- Overloaded indexers are supported, using the same notation one - would use in C#: - -items[0, 2] - - items[0, 2, 3] -- - Using Methods-Methods of CLR objects behave generally like normal Python - methods. Static methods may be called either through the class or - through an instance of the class. All public and protected methods - of CLR objects are accessible to Python: - -from System import Environment - - drives = Environment.GetLogicalDrives() -- It is also possible to call managed methods Note that there is one caveat related to calling unbound - methods: it is possible for a managed class to declare a static - method and an instance method with the same name. Since it is - not possible for the runtime to know the intent when such a - method is called unbound, the static method will always be - called. - - The docstring of CLR a method (__doc__) can be used to view the
- signature of the method, including overloads if the CLR method is
- overloaded. You can also use the Python from System import Environment - - print Environment.GetFolderPath.__doc__ - - help(Environment) -- - Overloaded and Generic Methods-While Python for .NET will generally be able to figure out the - right version of an overloaded method to call automatically, there - are cases where it is desirable to select a particular method - overload explicitly. - -Methods of CLR objects have an "__overloads__", which will soon - be deprecated in favor of iPy compatible Overloads, attribute that - can be used for this purpose : - - from System import Console
-
- Console.WriteLine.Overloads[bool](true)
- Console.WriteLine.Overloads[str]("true")
- Console.WriteLine.__overloads__[int](42)
-
- Similarly, generic methods may be bound at runtime using the - subscript syntax directly on the method: - - someobject.SomeGenericMethod[int](10)
- someobject.SomeGenericMethod[str]("10")
-
-
- Delegates And Events-Delegates defined in managed code can be implemented in Python. - A delegate type can be instantiated and passed a callable Python - object to get a delegate instance. The resulting delegate instance - is a true managed delegate that will invoke the given Python - callable when it is called: - -def my_handler(source, args): - print 'my_handler called!' - - # instantiate a delegate - d = AssemblyLoadEventHandler(my_handler) - - # use it as an event handler - AppDomain.CurrentDomain.AssemblyLoad += d -- Multicast delegates can be implemented by adding more callable - objects to a delegate instance: - -d += self.method1 - d += self.method2 - d() -- Events are treated as first-class objects in Python, and behave - in many ways like methods. Python callbacks can be registered with - event attributes, and an event can be called to fire the event. - - Note that events support a convenience spelling similar to that
- used in C#. You do not need to pass an explicitly instantiated
- delegate instance to an event (though you can if you want). Events
- support the def handler(source, args): - print 'my_handler called!' - - # register event handler - object.SomeEvent += handler - - # unregister event handler - object.SomeEvent -= handler - - # fire the event - result = object.SomeEvent(...) -- - Exception Handling-You can raise and catch managed exceptions just the same as you - would pure-Python exceptions: - - from System import NullReferenceException
-
- try:
- raise NullReferenceException("aiieee!")
- except NullReferenceException, e:
- print e.Message
- print e.Source
-
-
-
- Using Arrays- The type from System import Array - - myarray = Array[int](10) -- Managed arrays support the standard Python sequence protocols: - -items = SomeObject.GetArray() - - # Get first item - v = items[0] - items[0] = v - - # Get last item - v = items[-1] - items[-1] = v - - # Get length - l = len(items) - - # Containment test - test = v in items -- Multidimensional arrays support indexing using the same notation - one would use in C#: - -items[0, 2] - - items[0, 2, 3] -- - Using Collections-Managed arrays and managed objects that implement the - IEnumerable interface can be iterated over using the standard - iteration Python idioms: - -domain = System.AppDomain.CurrentDomain - - for item in domain.GetAssemblies(): - name = item.GetName() -- - Using COM Components-Using Microsoft-provided tools such as aximp.exe - and tlbimp.exe, it is possible to generate - managed wrappers for COM libraries. After generating such a - wrapper, you can use the libraries from Python just like any other - managed code. - -Note: currently you need to put the generated wrappers in the - GAC, in the PythonNet assembly directory or on the PYTHONPATH in - order to load them. - - -Type Conversion-Type conversion under Python for .NET is fairly straightforward - - most elemental Python types (string, int, long, etc.) convert - automatically to compatible managed equivalents (String, Int32, - etc.) and vice-versa. Note that all strings returned from the CLR - are returned as unicode. - -Types that do not have a logical equivalent in Python are - exposed as instances of managed classes or structs (System.Decimal - is an example). - - The .NET architecture makes a distinction between A process called Understanding boxing and the distinction between value types and - reference types can be important when using Python for .NET - because the Python language has no value type semantics or syntax - - in Python "everything is a reference". - -Here is a simple example that demonstrates an issue. If you are - an experienced C# programmer, you might write the following code: - -items = System.Array.CreateInstance(Point, 3) - for i in range(3): - items[i] = Point(0, 0) - - items[0].X = 1 # won't work!! -- While the spelling of In Python however, "everything's a reference", and there is
- really no spelling or semantic to allow it to do the right thing
- dynamically. The specific reason that The rule in Python is essentially: "the result of any attribute - or item access is a boxed value", and that can be important in how - you approach your code. - -Because there are no value type semantics or syntax in Python, - you may need to modify your approach. To revisit the previous - example, we can ensure that the changes we want to make to an - array item aren't "lost" by resetting an array member after making - changes to it: - -items = System.Array.CreateInstance(Point, 3) - for i in range(3): - items[i] = Point(0, 0) - - # This _will_ work. We get 'item' as a boxed copy of the Point - # object actually stored in the array. After making our changes - # we re-set the array item to update the bits in the array. - - item = items[0] - item.X = 1 - items[0] = item -- This is not unlike some of the cases you can find in C# where
- you have to know about boxing behavior to avoid similar kinds of This is the same thing, just the manifestation is a little - different in Python. See the .NET documentation for more details - on boxing and the differences between value types and reference - types. - - -Embedding Python-Note: because Python code running under Python - for .NET is inherently unverifiable, it runs totally under the - radar of the security infrastructure of the CLR so you should - restrict use of the Python assembly to trusted code. - -The Python runtime assembly defines a number of public classes - that provide a subset of the functionality provided by the Python - C API. - -These classes include PyObject, PyList, PyDict, etc. The source - and the unit tests are currently the only API documentation.. The - rhythym is very similar to using Python C++ wrapper solutions such - as CXX. - -At a very high level, to embed Python in your application you - will need to: - -
The module you import can either start working with your managed - app environment at the time its imported, or you can explicitly - lookup and call objects in a module you import. - -For general-purpose information on embedding Python in - applications, use www.python.org or Google to find (C) examples. - Because Python for .NET is so closely integrated with the managed - environment, you will generally be better off importing a module - and deferring to Python code as early as possible rather than - writing a lot of managed embedding code. - -Important Note for embedders: Python is not - free-threaded and uses a global interpreter lock to allow - multi-threaded applications to interact safely with the Python - interpreter. Much more information about this is available in the - Python C API documentation on the www.python.org Website. - -When embedding Python in a managed application, you have to - manage the GIL in just the same way you would when embedding - Python in a C or C++ application. - - Before interacting with any of the objects or APIs provided by
- the Python.Runtime namespace, calling code must have acquired the
- Python global interpreter lock by calling the When finished using Python APIs, managed code must call a
- corresponding The AcquireLock and ReleaseLock methods are thin wrappers over
- the unmanaged License- -Python for .NET is released under the open - source Zope Public License (ZPL). A copy of the ZPL is included - in the distribution, or you can find a copy of the - ZPL online . Some distributions of this package include a - copy of the C Python dlls and standard library, which are covered - by the Python - license . - - |
-