[Zope-CVS] CVS: PythonNet/doc - FAQ.txt:1.1 LICENSE.txt:1.1

Brian Lloyd brian@zope.com
Mon, 17 Feb 2003 22:44:36 -0500


Update of /cvs-repository/PythonNet/doc
In directory cvs.zope.org:/tmp/cvs-serv5356/doc

Added Files:
	FAQ.txt LICENSE.txt 
Log Message:
initial commit

=== 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
        that down.

      - 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: 
    http://www.zope.com/Members/Brian/PythonForDotNet/snapshot.zip

    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


    **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 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 
      is called.:: 

          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**

      xxx

    **Using COM Components**

      xxx

    **Type Conversion**

      xxx

    **Security**

      xxx


  **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 
    issues: brian@zope.com.


=== 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
Foundation (FSF).

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
   disclaimer.

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
   http://www.zope.com/Marks).

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.

Disclaimer

  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
  DAMAGE.


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.