[Zope-CVS] CVS: PythonNet/doc - FAQ.txt:1.1 LICENSE.txt:1.1
Mon, 17 Feb 2003 22:44:36 -0500
Update of /cvs-repository/PythonNet/doc
In directory cvs.zope.org:/tmp/cvs-serv5356/doc
=== Added File PythonNet/doc/FAQ.txt ===
Python Scripting For .NET FAQ
**What is Python Scripting For .NET?**
Python Scripting For .NET provides Python programmers with near-seamless
integration with the .NET Common Language Runtime (CLR). Using this
package you can script CLR applications or build entire applications
in Python, using CLR services and components written in any language that
targets the CLR (Managed C++, C#, VB, JScript, etc.).
This package does *not* make Python a first-class CLR language - it does
not produce managed code from Python code. Rather, it is an integration
of the CPython engine with the .NET runtime. This approach allows you to
use CLR services, continue to use existing Python C extensions, and
provides decent speed.
**What is the license?**
This package is released under the open source Zope Public License (ZPL).
A copy of the ZPL is included in the distribution, or you can find the
ZPL online at: http://www.zope.org/Products/Zope/LICENSE_20.txt.
**What is the current status of the package?**
I still consider it experimental, in that I've focused on working out
the core architecture to support a natural experience for the Python
programmer. Little or no effort has yet gone in to packaging and
deployment issues, embedding APIs and other things that will be
required for a production-quality release.
At this point, most of the core concepts of the integration are working,
it is possible to build real applications, and there are a respectable
number of unit tests.
Some caveats of the current release:
- The package is currently a self-contained private assembly, which
includes a copy of Python 2.2. The python.exe is actually a managed
wrapper to bootstrap the CLR support. In the future we'll want to
provide a bootstrap module that is a normal Python C extension so
that you can use an external CPython. Since that starts to get into
packaging issues, I've punted on that for now.
- There is still a bad interaction with the Python GC, so the managed
python.exe currently forcibly disables Python GC until I can track
- Resolution of overloaded methods is pretty brain-dead right now. It
needs to be fixed to weight argument types.
My hope is to find a group of people interested enough in .NET support
to help finish working out the details for remaining issues like
deployment, embedding, etc.
Is This Like Jython for .NET?
No. Jython provides an implementation of the Python language and runtime
in pure Java. Python Scripting For .NET is not a re-implementation of
Python, just an integration of the existing CPython runtime with .NET.
While a solution like Jython provides "two-way" interoperability, this
package only provides "one-way" integration. Meaning, while Python can
use types and services implemented in .NET, managed code cannot generally
use classes implemented in Python.
A Jython-like solution for .NET would certainly be doable and useful - but
it would also be a lot more work than the current approach.
Is This Related To ActiveState's Python.NET Work?
No. That effort focused on the feasibility of making Python a true .NET
language (compiling Python to IL).
**How do I install the package?**
A current snapshot of the package is available at:
The release snapshot is a self-contained "private" assembly. Just unzip
the package whereever you want it, cd to that directory and run
python.exe to start using it.
**How do I use it?**
Until there is "real" documentation, I'll try to keep this reasonably
up to date to give quick usage examples. A key idea for this project
has been that it 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#").
If you want to find out about any kind of usage not shown here, the
unit tests are probably a good place to look for examples.
**Importing .NET namespaces**
An import hook allows CLR namespaces to be treated essentially as
Python packages. The "top-level" package is named 'CLR', and acts as
the root for accessing CLR namespaces::
from CLR.System import String
import CLR.System as System
Types from any loaded assembly may be imported and used in this manner.
The import hook uses "implicit loading" to support automatic loading
of assemblies whose names correspond to a namespace::
# This will implicitly load the System.Windows.Forms assembly
from CLR.System.Windows.Forms import Form
To load assemblies with names that do not correspond with a namespace,
you can use the standard mechanisms provided by the CLR::
from CLR.System.Reflection import Assembly
a = Assembly.LoadWithPartialName("SomeAssembly")
# now we can import namespaces defined in that assembly
from CLR.SomeNamespace import Something
Note that CLR modules are "lazy". Because a namespace can contain a
potentially very large number of classes, reflected CLR classes are
created on-demand when they are requested of a CLR module.
**Using .NET Classes**
You can import and use any non-private class from any loaded assembly
in Python. To create an instance, pass the class arguments that match
one of its public constructors::
from CLR.System.Drawing import Point
p = Point(5, 5)
**Fields And Properties**
You can get and set fields and properties of CLR objects just as if
they were regular attributes::
from CLR.System import Environment
name = Environment.MachineName
Environment.ExitCode = 1
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 CLR.System import Enviroment
drives = Environment.GetLogicalDrives()
**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
def my_handler(source, args):
# 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::
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 events 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
'+=' and '-=' operators in a way very similar to the C# idiom::
def handler(source, args):
# register event handler
object.SomeEvent += handler
# unregister event handler
object.SomeEvent -= handler
# fire the event
result = object.SomeEvent(...)
**Deriving From .NET Classes**
**Using COM Components**
**Does it support embedding?**
The Python runtime assembly will eventually expose APIs to allow easy
embedding in managed applications. Some bits of those APIs exist in a
broken and scratch-pad way right now, but are definitely not ready
for prime-time. I expect fairly major refactoring to continue for a
while, so use of any exported APIs from other managed code should be
considered "at your own risk" :^)
**Does it work with Mono?**
A design goal for this project is that it should eventually work with
little or no change on the Mono platform. The integration layer is
completely written in managed code (C#) to make that easier.
I haven't tried building it under Mono - the last time I looked the
Mono class libraries were still missing some required parts.
**How can I report bugs?**
I haven't yet set up a mailing list for the project - if there is
enough interest I will do so. Until then, please email me with any
=== Added File PythonNet/doc/LICENSE.txt ===
Zope Public License (ZPL) Version 2.0
This software is Copyright (c) Zope Corporation (tm) and
Contributors. All rights reserved.
This license has been certified as open source. It has also
been designated as GPL compatible by the Free Software
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:
1. Redistributions in source code must retain the above
copyright notice, this list of conditions, and the following
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions, and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
3. The name Zope Corporation (tm) must not be used to
endorse or promote products derived from this software
without prior written permission from Zope Corporation.
4. The right to distribute this software or to use it for
any purpose does not give you the right to use Servicemarks
(sm) or Trademarks (tm) of Zope Corporation. Use of them is
covered in a separate agreement (see
5. If any files are modified, you must cause the modified
files to carry prominent notices stating that you changed
the files and the date of any change.
THIS SOFTWARE IS PROVIDED BY ZOPE CORPORATION ``AS IS''
AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL ZOPE CORPORATION OR ITS CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
This software consists of contributions made by Zope
Corporation and many individuals on behalf of Zope
Corporation. Specific attributions are listed in the
accompanying credits file.