Revision: 2772
Author: fwierzbicki
Date: 2006-05-28 06:19:57 -0700 (Sun, 28 May 2006)
ViewCVS: http://svn.sourceforge.net/jython/?rev=2772&view=rev
Log Message:
-----------
Some name changes.
Added Paths:
-----------
trunk/sandbox/wierzbicki/mockup/Project/userfaq.txt
trunk/sandbox/wierzbicki/mockup/Project/userguide.txt
Removed Paths:
-------------
trunk/sandbox/wierzbicki/mockup/Project/faq.txt
trunk/sandbox/wierzbicki/mockup/Project/userdoc.txt
Deleted: trunk/sandbox/wierzbicki/mockup/Project/faq.txt
===================================================================
--- trunk/sandbox/wierzbicki/mockup/Project/faq.txt 2006-05-28 13:19:06 UTC (rev 2771)
+++ trunk/sandbox/wierzbicki/mockup/Project/faq.txt 2006-05-28 13:19:57 UTC (rev 2772)
@@ -1,645 +0,0 @@
-==========
-Jython FAQ
-==========
-
-.. contents:: Table of Contents
-.. sectnum::
-
-General information and availability
-====================================
-
-What is Jython?
----------------
-Jython is the successor to JPython. The Jython project was created in
-accordance with the CNRI JPython 1.1.x license, in order to ensure the
-continued existence and development of this important piece of Python
-software. The intent is to manage this project with the same open policies
-that are serving CPython so well.
-
-Mailing lists, CVS and all current information on the Jython project is
-available at SourceForge, at http://sourceforge.net/projects/jython
-
-The name had to be changed to something other than JPython, because of
-paragraph 4 in the JPython-1.1 license: ::
-
- 4. Licensee may not use CNRI trademarks or trade name, including
- JPython [...] to endorse or promote products [...]
-
-Is Jython the same language as Python?
---------------------------------------
-We will always strive to ensure that Jython remains as compatible with
-CPython as possible. Nevertheless, there are a number of differences
-between the two implementations that are unlikely to go away. These range
-from the trivial - Jython's code objects don't have a co_code attribute
-because they don't have any Python bytecodes; to the significant -
-Jython uses Java's true garbage collection rather than Python's reference
-counting scheme.
-
- http://jython.sourceforge.net/docs/differences.html
-
-Python has never really had much of a language definition beyond it's
-C-based implementation. The existence of Jython changed that for the first
-time and will hopefully lead to a much clearer sense of what Python the
-language is; independent of any specific implementation.
-
-.. FIXME: move/edit this paragraph.
-
-We will be preparing a version of Python's regression test that would
-be appropriate for new implementations of the language. This is a good
-first step towards defining what parts of Python are essential and which
-are incidental
-
-What is the current status of Jython?
---------------------------------------
-The Jython project was announced on 19-oct-2000. The first alpha release
-occured on 26-nov-2000.
-
-The final release of Jython-2.0 occured on 17-jan-2001. The final release
-of Jython-2.1 occured on 31-dec-2001.
-
-Current work include improvements to java integration and implementing
-the lastest features from CPython 2.2/3.
-
-How fast is Jython?
--------------------
-The startup time and runtime performance for Jython are largely determined
-by the JVM.
-
-Current status is that CPython 2.3 on Windows2000 is about twice as
-fast as Jython 2.1 on JDK1.4 on Windows2000. However, because of Java's
-slow startup time, Jython starts much more slowly (2.4 s) than CPython
-(80 ms). This means you don't want to do standard CGI in Jython, but
-long-running processes are fine.
-
-The following notes are retained for historical interest.
-
-At IPC-6 JimH reported speeds equal to CPython 1.4 on the pystone
-benchmark. When Guido released CPython 1.5 he succeeded in making it
-about 2x faster than the 1.4 release. The current release of CPython
-is 1.5.2 which might be only slightly faster than 1.5. JimH re-ran his
-benchmark tests against CPython 1.5 and his then current release of
-Jython, finding that Jython was about 2.5x slower than CPython 1.5. I
-have recently run a few informal benchmarks and found some interesting
-numbers: using Sun's JDK 1.2.1 with JIT on a Solaris 2.6 Sparc Ultra 2,
-I found Jython 1.1beta3 to produce pystone numbers equal to (or very
-slightly better than) CPython 1.5.2+.
-
-The problem, of course, is that JITs are still not reliable enough for
-Jython. Turning off the JIT on the above platform, can slow Jython down
-by a factor of 10.
-
-The speed of Jython is tied very tightly to the speed of the underlying
-JVM. The benchmark results that JimH reported were all using Microsoft's
-JVM from Internet Explorer 4.0. The next fastest JVM that he used was
-almost a factor of 2 slower than this. Since the performance of JVMs
-changes nearly every day, at some point I'll need to collect a set of
-scores comparing pystone performance on a wider variety of JVM's.
-
-Finally, pystone is not the last word in benchmarking. At the moment
-I'm more concerned with making Jython complete and correct than with
-performance. We will continually be revisiting performance issues both to
-examine better benchmark's for comparing Jython and CPython (as well as
-other scripting languages for the JVM) and work at optimizing Jython's
-performance.
-
-Installing Jython
-=================
-
-Why do I get NoClassDefFoundError when running the installer
-------------------------------------------------------------
-Make sure that the class name on the command line doesn't end in
-.class. Also make sure that the installer actually exists in your current
-working directory.
-
-Why can't I use "from java import ..." on Windows?"
----------------------------------------------------
-This problem can occur if you are using Microsoft's VM (i.e. jview.exe)
-which provides the standard classes in a different format. You need to
-run the following command in a console window before using Jython: ::
-
- clspack -auto
-
-What is "python.path" and "python.prepath" mean in the Jython registry
-----------------------------------------------------------------------
-
-.. FIXME: do we need to even talk about pre-2.0 anymore?
-
-The key "python.path" in the Jython registry changed in the 2.0 version. This
-FAQ entry is intended to clarify registry keys related to sys.path
-settings.
-
-Before Fri, December 15, 2000- the "python.path" key in the registry file
-appended the given value to the sys.path list before the (sys.prefix)/lib
-directory is added. This means for Jython-2.0a1 and before, the above
-behavior is expected.
-
-Changes committed on December 15, 2000 change the behavior so that
-the registry's "python.path" key is appended to sys.path after
-(sys.prefix)/lib directory. This applies to CVS versions and any
-subsequently released versions of Jython.
-
-This mimics the behavior of the appending that takes place in the
-autoloaded site.py. Traditionally JPython users have appended the CPython
-path in this registry key; however, this was unsafe as it then preceded
-the Jython lib directory. This change eliminates errors associated with
-appending the CPython lib path in this key.
-
-For those instances where you do intend to add something to the
-sys.path before (sys.prefix)/lib, there is a new registry key called
-"python.prepath". This exists only after the 20001215 change date.
-
-Here is the summary of changing sys.path:
-
-Before 20001215:
-
- 1. python.path key appends given path before (sys.prefix)/lib.
- Do not put the CPython Lib dir in the python.path key unless
- you precede it with the Jython lib path. (using site.py may be
- a better choice).
- 2. Jython-2.0a1 autoloads site.py (as does Python20) and appends
- path changes after (sys.prefix)/lib- a better alternative to
- appending to sys.path.
-
-After 20001215:
-
- 1. python.path key appends given path after (sys.prefix)/lib.
- Same as autoloaded site.py file.
- 2. A new key, "python.prepath", was added to append path's before
- (sys.prefix)/lib if needed.
-
-If there is confusion about site.py:
-
- site.py is automatically loaded on normal startup in Python 2.0
- and Jython-2.0a1. This used to be user-loaded in Python 1.5.2
- and JPython11.
-
-Edit this entry / Log info
-
-Why no command-line history in Jython?
---------------------------------------
-The shells and other tools commonly associated with having a command-line
-history get this functionality from the C 'readline' package. There is
-experimental 'readline' classes in Java, and is likely to be in Jython's
-future. For the current release, there is console.py in the demo directory
-that adds a simple up/down.
-
-It is not commonly the case that programs look to the shell for this
-functionality, it is more common that readline is compiled in to the shell
-(or CPython) you are using which provides this functionality. However,
-some shells wrap the stdin/out of other programs (Jython). Shell mode in
-emacs is an excellent example. "rlterm", a shell that comes with the Unix
-version of Yorick, also does this (i.e. "rlterm jython"). There may be
-many others do the same so you can supplant the functionality of readline.
-
-Why do I get the error, "can't create package cache dir, '/cachedir/packages'"
-------------------------------------------------------------------------------
-An essential optimization in Jython is the caching of Java package
-information. The caching requires '/cachedir/packages/' in the python.home
-directory. It is often the case on `*nix` that users lack sufficient
-priveledges to create or write to this directory.
-
-Because the problem is merely permissions, something similar to "mkdir
-cachedir; chmod a+rw cachedir" within Jython's directory should eliminate
-this error message.
-
-Where's the registry file
--------------------------
-Jython's installation includes a file called "registry" that you will find
-in the root directory of the Jython installation (e.g. /usr/local/jython
-or c:\jython).
-
-At initialization, Jython searches for the "registry" file in the
-directory specified by the "python.home" property, or the ".jython"
-file in the user's home directory.
-
-The "python.home" property is often set in the startup with Java's -D
-switch. The shell script that starts Jython (jython.bat or jython)
-demonstrates the use of the -D switch to set the "python.home"
-property. When embedding Jython, it is often still best to use the -D
-switch because the -D properties appear in System.getProperties(),
-which is usually the "preProperties" (first arg) in the static
-PythonInterpreter.initialize method. With python.home in the
-preProperties, the interpreter successfully loads preProperties,
-registry properties, and postProperties (the second arg to initialize)
-in the correct order.
-
-If you wish to use your home directory, and do not know where your home
-directory is, don't worry- Jython knows:
-
- >>> print java.lang.System.getProperty("user.home")
-
-If you run into complaints about create ".jython", don't worry-
-Jython can:
-
- >>> import java, os
- >>> filename = os.path.join(java.lang.System.getProperty("user.home"),
- ".jython")
- >>> open(filename, "w")
-
-GUI-less installer?
--------------------
-If you do not have a GUI, then add -o dir_to_install_to to the
-command. Jython will install to the specified directory without bringing
-up the graphical installer. E.g. to install all modules to a Jython-2.1
-subdirectory in the current directory do: ::
-
- <java interpreter> jython-21 -o Jython-2.1 demo lib source
-
-Programming in Jython
-=====================
-
-Why can't I multiply inherit from two Java classes?
----------------------------------------------------
-In earlier versions of JPython, you actually could. This was deliberately
-disabled in 1.1 for a variety of good reasons. For a detailed discussion
-on this issue see the following archive messages: ::
-
- http://www.python.org/pipermail/jpython-interest/1998-April/000213.html
- http://www.python.org/pipermail/jpython-interest/1999-June/001874.html
-
-Note that you can still multiply inherit from any number of Python
-classes.
-
-Why does dir(someJavaObject) return the empty list?
----------------------------------------------------
-Because the built-in dir() function returns a list of names called
-from the object's __dict__, __methods__, and __members__ attributes. In
-Python, an instance's methods live in the instance's class's dictionary,
-so dir(someJavaObject.__class__) would return a list of the method names
-(although only for the direct class, not for any base classes).
-
-I'm trying to execute a 'protected' or 'private' Java Instance Method or attribute in a Java package. How can I get access?
----------------------------------------------------------------------------------------------------------------------------
-By default, as in Java, these methods are protected from external access,
-but there may be reasons, such as test scaffolding scripts, that this
-feature is not wanted. In the [jython home]/registry file:
-
- # Setting this to false will allow Jython to provide access to
- # non-public fields, methods, and constructors of Java objects.
- python.security.respectJavaAccessibility = false
-
-Can I reload a java class as is possible for python modules?
-------------------------------------------------------------
-The support for reloading java classes through reload(java-class),
-is disabled. The reload(java-class) only worked when the java class
-was a standalone class without any dependencies on other java classes
-(except the system class). When there was more than one class involved,
-the simple reload(java-class) no longer worked.
-
-Now on the other hand Jython 2.0 comes with some alternative
-(experimental) user-level support for java classes reloading ("jreload"
-module).
-
-See: http://www.jython.org/docs/jreload.html
-
-Further Jython 2.0 internal changes enable the expert user to play with
-reloading and class-loaders as he would from native java.
-
-How can I access Java protected (static) members from a Jython subclass?
-------------------------------------------------------------------------
-The short answer: you can't. At least not without setting the registry
-option python.security.respectJavaAccessibility to false.
-
-It is difficult to add in a nice manner. The problem is a bit like this:
-
-A normal (public) static method is from jython called on the parent
-java class:
-
- javaclass.method()
-
-Such a call does not originate from the subclass, but from internal
-reflection code in jython. If we want to add support for calling protected
-static methods from a jython subclass, the call will have to originate
-from the subclass (ie. the proxy class), so we will have to generate a
-referring method in subclass proxy like::
-
- public static void method() {
- javaclass.method()
- }
-
-(with the right return type and throws clauses) and the jython subclass
-will have to call the method on its own class, not the java class.
-
-
-How can I use a Java null value in Jython?
-------------------------------------------
-A java null is turned into a Python None value.
-
-import java
->>> h = java.util.Hashtable()
->>> print h.get("abc")
-None
->>> if h.get("abc") is None:
-... print "null returned"
-...
-null returned
->>>
-
-
-Where's the -O switch
----------------------
-Jython 2.0 does not have a -O command-line switch.
-
-Assigning __debug__=0 has been used to get -O behavior from things like
-"assert", but such assignments to __debug__ are considered an error,
-and in the future, will raise an exception. __debug__ is supposed to be
-a read-only variable.
-
-When I write to a file, it's empty. Why?
-----------------------------------------
-The addition of buffering to the org.python.core.PyFile class in the 2.1
-development cycle changed the autoflushing of Jython file objects. In
-Jython 2.1x, you must explicitly flush() and/or close() a file object
-opened for writing or appending before any data will actually be saved.
-
-This reflects the current status and is not meant to imply this will
-always be the case for Jython (but it may be for certain java versions).
-
-Currently, For example:
-
- f = open("myFile", "w")
- # if the program terminates here, the file is empty
- f.flush() # or f.close()
- # If the program terminates here ,the file has data
-
-Another example:
-
- open("myFile", "w").write("some data")
-
-This will create an empty file, but note that the standard lib does not
-use write on anonymouse file objects as it is considered poor practice
-anyway.
-
-
-The Jython's os module is missing some functions, why?
-------------------------------------------------------
-Python's and Jython's os modules differ necessarily because of differences
-Java imposes on natvie system access. For example, Java does not have
-a chdir equivalent, so it does not exist in Jython's os.
-
-There is an alternative os module that does provide additional
-functionality, and it is the jnios module found at:
-
- http://sourceforge.net/projects/jnios
-
-The jnios module replaces the default os module with a Java/JNI
-implementation of Python's os and posix modules.
-
-Jython CVS also has more functions in the os module (like system
-and the popen* functions). See FAQ 3.10 for more information:
-http://www.jython.org/cgi-bin/faqw.py?req=show&file=faq03.010.htp
-
-or:
-
-Use the os.system or os.popen* functions from Jython CVS.
-
-To use these functions, you'll need javaos.py, javashell.py, and
-popen2.py:
-
- http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jython/jython/Lib/
-
-You'll need to delete the 'from __future__ import division' line from
-javaos.py (this is a Python 2.2 feature not supported in Jython 2.1)
-
-Alternatively, you could use java.lang.Runtime.exec() directly, but the
-os functions handle a lot of complexity for you.
-
-
-Jython modules
-==============
-
-What parts of the Python library are supported?
------------------------------------------------
-The good news is that Jython now supports a large majority of the
-standard Python library. The bad news is that this has moved so rapidly,
-it's hard to keep the documentation up to date.
-
-Built-in modules (e.g. those that are written in C for CPython) are a
-different story. These would have to be ported to Java, or implemented
-with a JNI bridge in order to be used by Jython. Some built-in modules
-have been ported to JPython, most notably cStringIO, cPickle, struct,
-and binascii. It is unlikely that JNI modules will be included in Jython
-proper though.
-
-If you want to use a standard Python module, just try importing it. If
-that works, you're probably all set. You can also do a dir() on the
-modules to check the list of functions it implements.
-
-If there is some standard Python module that you have a real need for
-that doesn't work with JPython yet, please send us mail.
-
-Can I use the python DB API from Jython?
-----------------------------------------
-Take a look at zxJDBC which gives data database connectivity from Jython
-using the Python DB API 2.0 interface. zxJDBC comes with Jython 2.1 or
-later.
-
-Can I use the Numeric package from Jython?
-------------------------------------------
-Take a look at at Tim Hochberg's Java implementation of Numeric, JNumeric.
-
-- http://members.home.net/tim.hochberg/
-
-Extending Jython
-================
-
-Java classes that emulate Jython Dictionaries and Sequences
------------------------------------------------------------
-
-.. FIXME: document new support in Jython 2.2/3.
-
-In order to emulate Dictionaries and Sequences, first your Java class must
-"extend" the org.python.core.PyObject class. The following methods can
-then be defined on your class in order to emulate these basic Jython
-types:
-
-public PyObject __finditem__(PyObject key);
-
-public void __setitem__(PyObject key, PyObject value);
-
-public void __delitem__(PyObject key);
-
-Additionally, you might want to throw the org.python.core.Py.KeyError
-object if you have any exceptions (Note, you need not declare the Java
-method as throwing anything.)
-
-Emulating Jython object attribute access with a Java class
-----------------------------------------------------------
-You can develop your own Java class that emulates Jython objects by
-first extending the org.python.core.PyObject class. Then, implement the
-following methods on your Java class:
-
-public PyObject __findattr__(String name);
-
-public void __setattr__(String name, PyObject value);
-
-public void __delattr__(String name);
-
-You may also want to raise exceptions using the
-org.python.core.Py.AttributeError error class. (Note, you do not need
-to declare that the method throws this class.)
-
-As in CPython, "a = foo.bar" calls the __findattr__ method on foo,
-"foo.bar = 'baz'" calls the __setattr__ method on foo, and "delattr(foo,
-'bar')" calls the __delattr__ method on foo.
-
-If you plan on storing functions as attributes of your Java object (so
-that you could say "foo.bar('baz', 'fizzle')", be forwarned that Jython
-*may or may not* call the __findattr__ method to find the function object
-depending on the number/types of parameters. You should, additionally,
-implement the following methods:
-
-public PyObject invoke(String name);
-
-public PyObject invoke(String name, PyObject arg1);
-
-public PyObject invoke(String name, PyObject arg1, PyObject arg2);
-
-public PyObject invoke(String name, PyObject[] args);
-
-public PyObject invoke(String name, PyObject[] args, String[] keywords);
-
-.. Note: Writing new-style classes (only possible in versions > 2.1)
- is a bit more complicated. This needs more documentation.
-
-Supporting `*args` and `**kw` in Java methods
----------------------------------------------
-
-Embedding Jython
-================
-(thanks to Finn Bock for the information)
-
-In Jython (note, this does not work in JPython), you can support keyword
-arguments on Java methods by defining the method like so (the parameters
-are the important point):
-
-public PyObject foo(PyObject[] args, String[] keywords);
-
-The keywords array contains all of the keywords for the keyword-defined
-arguments. For example, if you called foo with:
-
-foo(1,2,3,four=4,five=5)
-
-args would be: [1, 2, 3, 4, 5] and keywords would be: ['four', 'five']
-(an array of 2 elements.)
-
-Additionally, you can use the experimental argument parser
-org.python.core.ArgParser to deal mapping these two arrays. Consult the
-Javadocs (or source) for further details on org.python.core.ArgParser.
-
-How can I use jython classes from my java application?
-------------------------------------------------------
-There are several ways to do that. The best way depends on the needs of
-your application. One possible way is to compile the python class into
-a real java class using the jythonc command. This real java can be used
-and instances can be created from your application.
-
-(See FAQ X.Y for other ways to access python classes from java)
-
-Create a python module (say Foo.py) and make a class with the same
-name as the python module. The class must inherit from a java class
-or interface. If you don't need a particular java superclass, just use
-java.lang.Object.::
-
- import java
- class Foo(java.util.Date):
- def toString(self):
- return "Foo[" + java.util.Date.toString(self) + "]"
-
-The python class can overwrite all existing methods on the java superclass
-or interface and these overridden methods can be called from the java
-application. New methods can by default not be accessed from java. If
-we add a "bar" method, the method can be used from python, but not from
-java. ::
-
- import java
- class Foo(java.util.Date):
- def __init__(self):
- self.count = 0
- def bar(self, incr=1):
- self.count += incr
- return self.count
- def toString(self):
- cnt = self.bar()
- return "Foo[" + java.util.Date.toString(self) + " " + `cnt` +
- "]"
-
-The jythonc compiler can also create java methods for the python methods,
-but it need some additional help. This help is specified as a @sig line
-in the doc-string for the method. A doc-string is added to the example
-above. ::
-
- import java
- class Foo(java.util.Date):
- def __init__(self):
- self.count = 0
- def bar(self, incr=1):
- """@sig void bar(int incr)"""
- self.count += incr
- return self.count
- def toString(self):
- cnt = self.bar()
- return "Foo[" + java.util.Date.toString(self) + " " + `cnt` +
- "]"
-
-When this class is compiled with jythonc, A java class Foo.java and
-Foo.class is created with the java methods toString(), bar() and bar(int
-incr).
-
-When compiling the Foo.py class, make sure that the Foo actually extends
-the desired java class. You can check the output from the compilation. It
-should contain lines like: ::
-
- Required packages:
- java.util
-
- Creating adapters:
-
- Creating .java files:
- Foo module
- Foo extends java.util.Date
-
-If jython fails to recognize the superclass as a java class, it will
-silently assume that it is a python class and will not generate the
-desired java methods.
-
-The new Foo class can be used from java java class like this: ::
-
- public class FooTest {
- public static void main(String[] args) {
- Foo foo = new Foo();
- System.out.println(foo);
- foo.bar();
- foo.bar(43);
- System.out.println(foo);
- }
- }
-
-When compiling the FooTest.java class, the "jpywork" directory should
-be appended to your classpath.
-
-When running this little application, the jython.jar runtime must be
-available on the CLASSPATH or specified on the java command line.
-
-My modules can not be found when imported from an embedded application
-----------------------------------------------------------------------
-The default value for sys.path in an embedded application depend on
-several things:
-
-1) A python.path property, if found in the registry file or in the
-$HOME/.jython file will be used.
-
-2) The <python.home>/Lib directory is added.
-
-An application can override the python.path property by calling
-PythonInterpreter.initialize(..) before any other python code is
-called: ::
-
- Properties props = new Properties();
- props.setProperty("python.path", "/home/modules:scripts");
- PythonInterpreter.initialize(System.getProperties(), props,
- new String[] {""});
-
-The value for python.path must follow the operating system conventions
-for the PATH environment var (':' separator for unix, ';' for windows)
-
Deleted: trunk/sandbox/wierzbicki/mockup/Project/userdoc.txt
===================================================================
--- trunk/sandbox/wierzbicki/mockup/Project/userdoc.txt 2006-05-28 13:19:06 UTC (rev 2771)
+++ trunk/sandbox/wierzbicki/mockup/Project/userdoc.txt 2006-05-28 13:19:57 UTC (rev 2772)
@@ -1,1572 +0,0 @@
-=================
-Jython User Guide
-=================
-
-.. contents:: Table of Contents
-
------
-Intro
------
-
-.. FIXME: need intro.
-
-For a look at the Jython internal API see the generated
-`JavaDoc documentation`_
-
-General Python Documentation
-============================
-
-Since Jython is an implementation of Python for the JVM, most of
-the standard Python documentation applies. Look in the following places for general information:
-
-* The `Python Tutorial`_ (start here)
-* The `Python Library Reference`_. Although many of these modules are not
- yet implemented (those coded in C for CPython must be re-implemented
- in Java for Jython), those that are implemented follow the library
- reference as closely as possible.
-* The `Python Language Reference`_ (for language lawyers).
-
-Other Useful Links
-==================
-
-* Jython and CPython are two different implementations of the
- same language. There are naturally some differences between the
- two implementations, sometimes reflecting undefined aspects of
- the Python language, sometimes reflecting quirks of the independent
- implementations.
-* The `Jython FAQ`_ may already contain the answer to your question.
-* If it doesn't, then check `Jython-users mailing list archives`_.
-* If you are still stuck you can post a question to the `Jython-users mailing list`_
-
--------------------------------
-Invoking the Jython Interpreter
--------------------------------
-Jython is invoked using the "jython" script, a short script that invokes your local JVM, sets the Java
-property install.path to an appropriate value, and then runs the Java
-classfile org.python.util.jython.
-
-jython [options] [-jar jar | -c cmd | file | -] [args]
-
-options
- -i: Inspect interactively after running script; force prompts even if stdin is not a terminal.
- -S: Do not imply import site on initialization
- -Dprop=[value]: Set the jython property prop to value.
-
--jar jar
- the program to run is read from the __run__.py file in the specified jar file
-
--c cmd
- program to run is passed in as the cmd string. This option terminates the options list file run file as the program script file
-
--
- program is read from standard-in (default; interactive mode is used if on a tty). This flag allows you to pipe a file into Jython and have it be treated correctly. For example:
- filter file | jython -
-
-args
- arguments passed to the program in sys.argv[1:]
-
---help
- print a usage message and exit
-
---version
- print Jython version number and exit
-
-
-
-
-
-Making Jython Scripts Executable
-================================
-
-To make a jython ".py" file executable on a Unix system:
-
-* Make sure that jython is on your standard PATH.
-* Make the ".py" file executable. Typically, this is done with the command chmod +x foo.py
-* Add the following line to the top of the file:
-
-#! /usr/bin/env jython
-
-.. Note:: "#! <...>/jython" will generally not work to make your script
- executable. This is because "jython" is itself a script, and #!
- requires that the file to execute is a binary executable on most Unix
- variants. Using "/usr/bin/env" will get around this problem - and make
- your scripts more portable in the bargain.
-
--------------------
-The Jython Registry
--------------------
-
-Because there is no good platform-independent equivalent of the Windows
-Registry or Unix environment variables, Java has its own environment
-variable namespace. Jython aquires its namespace from the following
-sources (later sources override defaults found in earlier places):
-
-* The Java system properties, typically passed in on the command line
- as options to the java interpreter.
-* The Jython "registry" file, containing prop=value pairs. See below
- for the algorithm Jython uses to find the registry file.
-* The user's personal registry file, containing similarly formated
- prop/value pairs. The user's registry file can be found at "user.home"+"/.jython"
-* Jython properties specified on the command line as options to the
- jython class. See the -D option to the interpreter.
-
-Registry Properties
-===================
-
-The following properties are recognized by Jython. There may be others
-that aren't documented here; consult the comments in registry file
-for details.
-
-python.path
- Equivalent to CPython's PYTHONPATH environment variable
-python.cachedir
- The directory to use for caches - currently just package
- information. This directory must be writable by the user. If the
- directory is an absolute path, it is used as given, otherwise it is
- interpreted as relative to sys.prefix.
-python.verbose
- Sets the verbosity level for varying degrees of informative
- messages. Valid values in order of increasing verbosity are "error",
- "warning", "message", "comment", "debug"
-python.security.respectJavaAccessibility
- Normally, Jython can only provide access to public members of
- classes. However if this property is set to false and you are
- using Java 1.2 then Jython can access non-public fields, methods,
- and constructors.
-python.jythonc.compiler
- The Java compiler to use with the jythonc tool, which now generates
- Java source code. This should be the absolute path to a Java compiler,
- or the name of a compiler on your standard PATH.
-python.jythonc.classpath
- Extensions to the standard java.class.path property for use with
- jythonc. This is useful if you use Jikes as your compiler.
-python.jythonc.compileropts
- Options to pass to the Java compiler when using jythonc.
-python.console
- The name of a console class. An alternative console class that
- supports GNU readline can be installed with this property. Jython
- already include such a console class and it can be enabled by setting
- this property to org.python.util.ReadlineConsole
-python.console.readlinelib
- Allow a choice of backing implementation for GNU readline support. Can
- be either GnuReadline or Editline. This property is only used when
- python.console is set to org.python.util.ReadlineConsole.
-
-Finding the Registry File
-=========================
-
-To find the Jython registry file and
-set the Python values for sys.prefix, you must first locate a root directory.
-
-* If a "python.home" exists, it is used as the root directory by default.
-* If "python.home" does not exist, "install.root" is used.
-* If neither of these exist, then Jython searches for the
- file "jython.jar" on the Java classpath, as defined in the system
- property java.class.path. (The actual file system isn't searched, only
- the paths defined on the classpath and one of them must literally include
- "jython.jar").
-
-Once the root directory is found, sys.prefix and sys.exec_prefix are set
-to this, and sys.path has rootdir/Lib appended to it. The registry file
-used is then rootdir/registry.
-
-
-
-------------------------------
-Interaction with Java Packages
-------------------------------
-
-Most Jython applications will want to use the vast array of Java
-packages available. The following documentation helps you work with Java
-packages.
-
-* Working with JavaBean properties, making all Java classes easier to
- use from Python.
-* Special care is necessary to build and use Java arrays from Python.
-* This document describes how to subclass Java classes in Python.
-* The jythonc utility compiles Python source code to real Java classes,
- and is used for building applets, servlets, beans, etc.
-* Unloading of java classes and internalTablesImpl option.
-* Reloading java classes.
-
-Accessing Java from Jython
-==========================
-
-One of the goals of Jython is to make it as simple as possible to use
-existing Java libraries from Python.
-Example
-
-The following example of an interactive session with Jython shows how
-a user could create an instance of the Java random number class (found
-in java.util.Random) and then interact with that instance. ::
-
- C:\jython>jython
- Jython 2.0 on java1.2.1
- Type "copyright", "credits" or "license" for more information.
- >>> from java.util import Random
- >>> r = Random()
- >>> r.nextInt()
- -790940041
- >>> for i in range(5):
- ... print r.nextDouble()
- ...
- 0.23347681506123852
- 0.8526595592189546
- 0.3647833839988137
- 0.3384865260567278
- 0.5514469740469587
- >>>
-
-More Details
-============
-
-Hopefully, this example should make it clear that there are very few
-differences between using Java packages and using Python packages when
-working under Jython. There are a few things to keep in mind.
-
-Importing
-=========
-
-::
-
- Jython 2.0 on java1.2.1
- Type "copyright", "credits" or "license" for more information.
- >>> from java.util import *
- >>> Random
- <jclass java.util.Random at 31702169>
- >>> Hashtable
- <jclass java.util.Hashtable at 7538094>
- >>>
-
-Creating Class Instances
-========================
-
-You can create an instance of a Java class exactly the way you would
-create an instance of a Python class. You must "call" the class with
-a set of arguments that is appropriate for one of the Java class's
-constructors. See the section below for more details on what constitutes
-appropriate arguments.
-
-Calling Java Methods and Functions
-==================================
-
-Java classes have both static and instance methods this makes them
-behave much like a cross between a Python module and class. As a user,
-you should rarely need to be concerned with this difference.
-
-Java methods and functions are called just exactly like their Python
-counterparts. There is some automatic type coercion that goes on both for
-the types being passed in and for the value returned by the method. The
-following table shows how Python objects are coerced to Java objects
-when passed as arguments in a function call. The Java Types show the
-expected Java type for the argument, and the Allowed Python Types shows
-what Python objects can be converted to the given Java type. Notice the
-special behavior of String's when a java.lang.Object is expected. This
-behavior might change if it is shown to cause problems.
-
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| Java Types | Allowed Python Types |
-+==================================+=======================================================================================================+
-| char | String (must have length 1) |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| boolean | Integer (true = nonzero) |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| byte, short, int, long | Integer |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| float, double | Float |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| java.lang.String, byte[], char[] | String |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| java.lang.Class Class | (only if class subclasses from exactly one Java class; mutiple inheritance from more than one Java |
-| or JavaClass | class is now illegal) |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| Foo[] |Array (must contain objects of class or subclass of Foo) |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| java.lang.Object | String->java.lang.String, all others unchanged |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| org.python.core.PyObject | All unchanged |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-| Foo |Instance->Foo (if Instance is subclass of Foo); |
-| |JavaInstance -> Foo (if JavaInstance is instance of Foo or subclass) |
-+----------------------------------+-------------------------------------------------------------------------------------------------------+
-
-Returned values from a Java method are also possibly coerced back to an
-object that is more readily usable in Python. The following table shows
-those coercions.
-
-+----------------------------------------+---------------------------------------------------------+
-| Java Type | Returned Python Type |
-+========================================+=========================================================+
-| char | String (of length 1) |
-+----------------------------------------+---------------------------------------------------------+
-| boolean | Integer (true = 1, false = 0) |
-+----------------------------------------+---------------------------------------------------------+
-| byte, short, int, long | Integer |
-+----------------------------------------+---------------------------------------------------------+
-| float, double | Float |
-+----------------------------------------+---------------------------------------------------------+
-| java.lang.String | String |
-+----------------------------------------+---------------------------------------------------------+
-| java.lang.Class | JavaClass which represents given Java class |
-+----------------------------------------+---------------------------------------------------------+
-| Foo[] | Array (containing objects of class or subclass of Foo) |
-+----------------------------------------+---------------------------------------------------------+
-| org.python.core.PyObject (or subclass) | Unchanged |
-+----------------------------------------+---------------------------------------------------------+
-| Foo | JavaInstance which represents the Java Class Foo |
-+----------------------------------------+---------------------------------------------------------+
-
-Overloaded Java Method Signatures
-=================================
-
-Java methods are allowed to be overloaded for different signatures (types
-and number of arguments). When different versions of the method differ
-in the number of arguments that they expect, the appropriate method can
-be easily determined from the number of arguments passed to the method.
-
-When the difference is instead in the types of the arguments, more
-work is required. The possible signatures are sorted in a consistent
-order that should ensure the appropriate method is chosen first. TBD:
-document this order!
-
-.. FIXME -- really figure it out and document it.
-
-If you need to call a Java method with a particular signature and this
-is not happening in the easy way, you can use the following workaround:
-
-Assume that foo has two methods, "void foo(int x); void foo(byte x);". To
-call the second method you could write the following: ::
-
- from java.lang import Byte
- foo(Byte(10))
-
-I'm not convinced that any better solution to this problem is possible.
-
-.. Note:: Look into IronPython's solution to this for ideas.
-
-Naming Conflicts with Python Keywords
-=====================================
-
-Because Java has a different set of keywords than Python, there are
-many Java classes that have method and function names that conflict with
-Python's keyword set. Where the intent can be unambiguously determined,
-no identifier mangling is necessary, such as when keywords are used as
-attributes on objects. Thus you can naturally write:
-
- java.lang.System.out.print("hi")
-
-or
-
- java.lang.Runtime.getRuntime().exec(cmd)
-
-In the rare case where the conflict can't be resolved due to Python's
-grammar, you should modify the reserved word by appended an underscore
-to the end of it, e.g. `print_`
-
--------------------
-JavaBean Properties
--------------------
-
-Properties
-==========
-Jython uses JavaBean properties to make it easier to interact with most Java classes. These properties can be used as normal object attributes, and can also be specified to the class constructor as keyword arguments (this idea is stolen from TkInter where it seems to work extremely well).
-
-These properties are generated automatically using the JavaBean Introspector which identifies properties either from common design patterns, or from explicitly specified BeanInfo.
-
-As a first example, consider the case where you wish to create a button that is disabled.
-
-The first example shows how you would do this in the typical Java fashion:
-
-b = awt.Button()
-b.setEnabled(0)
-
-The second example shows how enabled can be set as a property:
-
-b = awt.Button()
-b.enabled = 0
-
-The final example sets this property at instantiation time using a keyword argument:
-
-b = awt.Button(enabled=0)
-
-Tuples
-======
-If the value of a property is specified as a tuple, then the property will be created by applying the constructor for the type of the property to the tuple. This is particularly handy for specifying sizes:
-
-frame = awt.Frame(size=(500,100))
-
-It can also be handy for specifying color as an RGB triple:
-
-frame.background = 255,255,0
-
-will set the background color of the frame to yellow.
-
-Event Properties
-================
-In standard Java, the event handlers for a widget are specified by passing in an instance of a class that implements the appropriate interface. This is the only reasonable approach to take in a language that doesn't have first-class functions. In Jython, for every event listener supported by a class, there will be a property added to the class for each method supplied by the event listener class. These properties can be set to give a function to be called when the appropriate event occurs.
-
-The standard Java style for setting an event listener is shown below:
-
- class action(awt.event.ActionListener):
- def actionPerformed(self,event):
- java.lang.System.exit(0)
-
-button = awt.Button("Close Me!")
-button.addActionListener(action())
-
-This can be written in a more Pythonesque (and compact) style by using event properties as follows:
-
-::
-
- def exit(event):
- java.lang.System.exit(0)
-
-button = awt.Button("Close Me!", actionPerformed=exit)
-
-Methods, Properties and Event Properties
-========================================
-Jython have only one namespace for these three class attributes. Java can be seen as having a unique namespace for each of the three types. As a consequense, there can be conflicts between methods, properties and event properties. These conflicts are resolved so that:
-
- properties < event-properties < fields < methods
-
-This means that a method will override a field with the same name. Some carefull handling of properties and static fields allow for the existence of, and access to, both an instance property and a static field with the same name.
-
------------
-Java Arrays
------------
-Java Arrays in Jython - JArray
-Many Java methods require Java array objects as arguments. The way that these arguments are used means that they must correspond to fixed-length, mutable sequences, sometimes of primitive data types. The PyArray class is added to support these Java arrays and instances of this class will be automatically returned from any Java method call that produces an array. In addition, the "jarray" module is provided to allow users of Jython to create these arrays themselves, primarily for the purpose of passing them to a Java method.
-
-The jarray module exports two functions:
-
-array(sequence, type)
-zeros(length, type)
-
-array will create a new array of the same length as the input sequence and will populate it with the values in sequence. zeros will create a new array of the given length filled with zeros (or null's if appropriate).
-
-type can either be a single character typecode (using the same mappings as Python's array module) or it can be an instance of a JavaClass object. The valid typecodes are shown in the following table:
-
-+--------------------+-------------------------+
-| Character Typecode | Corresponding Java Type |
-+====================+=========================+
-| z | boolean |
-+--------------------+-------------------------+
-| c | char |
-+--------------------+-------------------------+
-| b | byte |
-+--------------------+-------------------------+
-| h | short |
-+--------------------+-------------------------+
-| i | int |
-+--------------------+-------------------------+
-| l | long |
-+--------------------+-------------------------+
-| f | float |
-+--------------------+-------------------------+
-| d | double |
-+--------------------+-------------------------+
-
-----------------------------------
-Subclassing Java Classes in Jython
-----------------------------------
-
-A Short Example
-===============
-
-The example below should both demonstrate how this subclassing is
-performed and why it is useful. At first glance, the code looks exactly
-like subclassing any other Python class. The key difference in this
-example is that awt.event.ActionListener is a Java class, not a Python
-one. In the 4th line from the end, "b.addListener(SpamListener())",
-a Java method is being called that requires an instance of the Java
-class ActionListener. By providing a Python subclass of this Java class,
-everybody is happy. ::
-
- from java import awt
-
- class SpamListener(awt.event.ActionListener):
- def actionPerformed(self,event):
- if event.getActionCommand() == "Spam":
- print 'Spam and eggs!'
-
- f = awt.Frame("Subclassing Example")
- b = awt.Button("Spam")
- b.addActionListener(SpamListener())
- f.add(b, "Center")
- f.pack()
- f.setVisible(1)
-
-Note: This example can be accomplished much more elegantly by using
-JavaBeans properties (and event properties).
-
-Calling Methods in Your Superclass
-==================================
-
-In Python, if I want to call the foo method in my superclass, I use the
-form: ::
-
- SuperClass.foo(self)
-
-This works with the majority of methods, but protected methods cannot
-be called from subclasses in this way. Instead you have to use the
-"self.super__foo()" call style.
-
-Example
-=======
-
-The following example shows how the java.io.InputStream class can be
-effectively subclassed. What makes this class difficult is that the read
-method is overloaded for three different method signatures:
-
-1. abstract int read()
-2. int read(byte[])
-3. int read(byte[], int, int)
-
-The first one of these methods must be overridden in a subclass. The
-other two versions can be ignored. Unfortunately, Python has no notion of
-method overloading based on type signatures (this might be related to the
-fact that Python doesn't have type signatures ;-) In order to implement
-a subclass of java.io.InputStream that overrides the "read" method,
-a Python method must be implemented that handles all three possible
-cases. The example below shows the easiest way to acheive this: ::
-
- from java.io import InputStream
-
- class InfiniteOnes(InputStream):
- def read(self, *args):
- if len(args) > 0:
- # int read(byte[])
- # int read(byte[], int, int)
- return apply(InputStream.read, (self,)+args)
- return 1
-
- io = InfiniteOnes()
-
- for i in range(10):
- print io.read(),
- print
-
-Example Continued
-=================
-
-To continue the example above, this new instance of java.io.InputStream
-can be passed to any Java method that expects an InputStream as shown
-below: ::
-
- from java.io import DataInputStream
-
- dp = DataInputStream(io)
- dp.skipBytes(1000)
- print dp.readByte()
- print dp.readShort()
- print dp.readInt()
-
-Invoking Your Superclass's Constructor
-======================================
-
-You can explictly invoke your superclass's constructor using the standard
-Python syntax of explictly calling the "__init__" method on the superclass
-and passing in "self" as the first argument. If you wish to call your
-superclass's constructor, you must do so within your own "__init__"
-method. When your "__init__" method finishes, if your Java superclasses
-have not yet been explicitly initialized, their empty constructors will
-be called at this point.
-
-It's important to realize that your superclass is not initialized until
-you either explictly call it's "__init__" method, or your own "__init__"
-method terminates. You must do one of these two things before accessing
-any methods in your superclass.
-
-Example
-=======
-
-::
-
- from java.util import Random
-
- class rand(Random):
- def __init__(self, multiplier=1.0, seed=None):
- self.multiplier = multiplier
- if seed is None:
- Random.__init__(self)
- else:
- Random.__init__(self, seed)
-
- def nextDouble(self):
- return Random.nextDouble(self) * self.multiplier
-
- r = rand(100, 23)
-
- for i in range(10):
- print r.nextDouble()
-
-This example shows how the superclass's constructor can be effectively
-called in order to explictly choose a non-empty version.
-
---------------------------------------------
-Compiling Python Source to Real Java Classes
---------------------------------------------
-
-The previous section describes how Python classes can be created that
-subclass from Java classes. This works very well when you want to pass
-a Python class into Java from Jython. This is not adequate for building
-real Java ".class" files that implement a Java class and can be passed
-directly to Java programs. This sort of functionality is required to
-build applets, servlets, or JavaBeans in Jython that can be used exactly
-like their Java equivalents. It is also very valuable for users who wish
-to subclass Python classes in Java.
-
-In order to build a real java class from a Python class, you will use
-the jythonc tool. A script called "jythonc" should have been installed in
-the Jython installation directory when you installed the package. If it
-was not, it can be invoked as follows: "jython Tools\jythonc\jythonc.py".
-
-The jythonc tool generates actual Java source code, and then invokes a
-Java compiler over this source code to create the .class files. Thus,
-you will need access to a Java compiler in order to use jythonc. It
-is recommended that you use Sun's standard javac compiler, or IBM's
-excellent jikes compiler. Specifically, the Microsoft SDK jvc compiler
-is not recommended.
-
-Invoke jythonc like this: ::
-
- jythonc [options] [module]*
-
-Options are given in the table below. Note that jythonc now uses the
-standard Python getopt module, meaning that both long and short forms
-of the options are available. The old option names still work, and are
-described below, but noted as deprecated and will be removed in a future
-version. ::
-
- --package package
- -p package
- -package package Put all compiled code into the named Java package.
- --jar jarfile
- -j jarfile
- -jar jarfile Specifies a .jar file to create and put the results of
- the freeze into. Implies the --deep option.
- --deep
- -d
- -deep Compile all Python dependencies of the module. This is
- used for creating applets.
- --core
- -c
- -core Include the core Jython libraries (about 130K). Needed for
- applets since Netscape doesn't yet support multiple archives. Implies
- the --deep option.
- --all
- -a
- -all Include all of the Jython libraries (everything in core +
- compiler and parser). Implies the --deep option.
- --bean jarfile
- -b jarfile
- -bean jarfile Compile into jarfile, including the correct
- manifest for the bean.
- --addpackages pkgs
- -A pkgs
- -addpackages pkgs Include Java dependencies from this list of
- packages. Default is org.python.modules and org.apache.oro.text.regex.
- --workdir directory
- -w directory
- -workdir directory Specify the working directory where the generated
- Java source code is placed. Default is "./jpywork"
- --skip modules
- -s modules
- -skip modules Don't include any of these modules in
- compilation. This is a comma-separated list of modules.
- --compiler path
- -C path
- -compiler path Use a different compiler than `standard'
- javac. If this is set to "NONE" then compile ends with the generation
- of the Java source file. Alternatively, you can set the property
- python.jythonc.compiler in the registry.
- --compileropts options
- -J options Options passed directly to the Java
- compiler. Alternatively, you can set the property
- python.jythonc.compileropts in the registry.
- --falsenames names
- -f names
- -falsenames names A comma-separated list of names that are always
- false. Can be used to short-circuit if clauses.
- --help
- -h Print a usage message and exit.
- [module]* A list of Python modules to freeze. Can be either modules
- names that are on the python.path or .py files
-
-In order to create real java class, the Python module must contain a
-Python class with the same name as the module, and that Python class
-must subclass exactly one Java class or interface. The real Java class
-created will be a subclass of whatever Java class is subclassed.
-
-Compiling python methods to java methods
-========================================
-
-Normally, compiled python methods are not directly callable from
-java. There is simple not sufficient information in a python method
-definition to create a useable java method. There are however two ways a
-python method be made into real java method. Both ways require that the
-python class have a java class or a java interface as its base classes.
-
-* Overriding / Implementing a java method.
-
- By overriding a java method, the overridden method's signature is
- used for the real java class. That includes return type, privacy
- modifier, arguments, argument types and throws clauses.
-
-* Adding java method signature to python methods docstrings.
-
- Using a special convention in the method docstring allow for
- the creation of a corresponding java method. The signature must
- be written on one line and must start with the text "@sig". All
- class names (except those ion java.lang) must be specified as
- fully qualified class names. Example: ::
-
- def setExpression(self, e):
- "@sig public void setExpression(java.lang.String e)"
-
-
-Examples
-========
-
-On my Windows NT machine, I used the following command to create the
-file appletdemo.jar (containing all of the applet demos on the web site,
-as well as the core Jython libraries): ::
-
- c:\jython\Demo\applet> jythonc --core --deep --jar appletdemo.jar *.py
-
-Note: One special thing to consider when building applets is the java VM
-version used when compiling the sources must usually be the same as the
-VM version used by the browser. If a newer JVM is used when compiling
-the applets, the compiled code may have references to classes that does
-not exists in older JVM's.
-
-To generate a skeleton class to allow a Python class to be used as
-java.awt.Component in a Java gui program, I used the following command: ::
-
- c:\jython\Demo\javaclasses> jythonc Graph.py
-
-To generate a Jython-based bean I do the following: ::
-
- c:\jython\Demo\bean> jythonc --deep --bean f2c.jar
- conversion.FahrenheitToCelsius
-
-To use this with SUN's BDK, I do the following (the important steps are
-to make the bean and the Jython libraries known to the tool).
-
-1. modify BDK\beanbox\run.bat (or run.sh) to include the jython\JavaCode
- in the CLASSPATH
-2. copy f2c.jar to BDK\jars
-
-You should now be able to access the FahrenheitToCelsius bean from SUN's
-BeanBox (or other Bean-aware tool).
-
-Freezing modules
-================
-
-jythonc can also be used to freeze a python application. The frozen
-application can then be distributed and deployed as any other java
-application.
-
-Some diffrences between an interpreted application and a frozen
-application exists:
-
-* Properties are diffrent. XXX
-* sys.argv[0]
-* loading of python classes.
-
-Examples
-========
-
-
-----------------
-Embedding Jython
-----------------
-
-There are two options for embedding Jython in a Java
-application. You can make a real Java class out of a Python class, and then call it from your Java code, as previously described, or you can use the PythonInterpreter object
-
-Information on the PythonInterpreter can be found in the JavaDoc documentation for `org.python.util.PythonInterpreter`_.
-
-The following example demonstrates how to use the PythonInterpreter to execute a simple Python program.
-
-The python program:
-::
-
- import sys
- print sys
- a=42
- print a
- x=2+2
- print "x:",x
-
-
-
-The java code required to execute the python program:
-::
-
- import org.python.util.PythonInterpreter;
- import org.python.core.*;
-
- public class SimpleEmbedded {
- public static void main(String []args)
- throws PyException
- {
- PythonInterpreter interp =
- new PythonInterpreter();
-
- System.out.println("Hello, brave new world");
- interp.exec("import sys");
- interp.exec("print sys");
-
- interp.set("a", new PyInteger(42));
- interp.exec("print a");
- interp.exec("x = 2+2");
- PyObject x = interp.get("x");
-
- System.out.println("x: "+x);
- System.out.println("Goodbye, cruel world");
- }
- }
-
-
----------------------------------------------------
-Java Reload (experimental) simple Support - JReload
----------------------------------------------------
-
-Introduction and usage, plus some notes on java classes unloading and
-internalTablesImpl option
-
-The "jreload" module is not the definitive word about java classes
-reloading under jython. It is still experimental and its interface may
-improve or change to become more pythonic.
-
-"jreload" cannot cover all the possible reload-flavors, and its goal
-is to offer a simple interface for the most common cases, e.g. quick
-trial-and-error experimenting.
-
-Java classes reloading in jython is not enabled by "jreload", some of
-the modifications occurred to jython run-time have made it possible. Now
-jython can deal with java classes with the same name (without clashes)
-and run-time supports unloading of java classes by different ways,
-which is a must feature for some uses of reloading
-
-[The expert user can now play directly with class-loaders and reloading
-as he would from java.]
-
-The main idea of the "jreload" interface is that of a load-set. A
-load-set is a package-like object that can host a complete hierarchy of
-java packages, which can be reloaded as a whole.
-
-Why there is no support for reloading a single class? Java classes are
-loaded through class-loaders, actually there is no support in java to
-redefine an already loaded class through its class-loader. In order to
-reload a class one should create a new class-loader, but classes from
-different class-loaders cannot interoperate, so we need to reload all
-related classes through the new class-loader. Note: The normal python
-reload built-in does nothing for java classes and simply returns the
-old version.
-
-The "jreload" module exports the following functions: ::
-
- makeLoadSet(name, path)
- reload(loadSet)
-
-makeLoadSet creates and returns a new load-set with the given name. The
-created load-set will behave like a package and import statement related
-to it can be issued. name should be a valid python identifier like any
-python module name and should not clash with any module that has been
-or will be imported. Internally the created load-set will be added to
-sys.modules, the same way it happens to modules on import. You can issue
-the same makeLoadSet from many places, it is idempotent like modules
-imports are.
-
-path should be a list of directory or jar paths. The created load-set will
-enable importing the classes present there. path should be disjoint from
-both sys.path and java classpath, otherwise one can get very confusing
-results.
-
-For example: if a load-set 'X' is created and its hierarchy contains
-java packages 'p' and 'p.q', then the following references can be used
-in import statements: 'X', 'X.p', 'X.p.q'.
-
-reload(loadSet) reloads all the classes in the package hierarchy hosted
-by loadSet and returns loadSet.
-
-.. note:: The current version of "jreload" (jreload.__version__=='0.3')
- does not support removing or substituting jars on the fly.
-
-Example
-=======
-
-The following example should help make things clearer: (its files should
-be present in the jython Demo dir)
-# Demo/jreload/example.jar contains example.Version (source) and
-example.PrintVer (source)
-# Demo/jreload/_xample contains a slightly modified version of
-example.Version (source) ::
-
- >>> import sys
- >>> import os
- >>> import jreload
- >>> def xp(name): return os.path.join(sys.prefix,'Demo/jreload/'+name)
- # builds a path under 'Demo/jreload'
- ...
- >>> X=jreload.makeLoadSet('X',[xp('.'),xp('example.jar')])
- >>> from X import example
- >>> dir(example)
- ['PrintVer', 'Version', '__name__']
- >>> X.example.Version
- <jclass example.Version at 6781345>
- >>> from X.example import * # works but in general import * from java
- pkgs is not for production code
- >>> v=Version(1)
- >>> PrintVer.print(v)
- version 1
- >>> os.rename(xp('_xample'),xp('example')) # _xample becomes example,
- hiding and "patching" jar contents
- >>> jreload.reload(X) # (re)loads example dir example.Version and
- jar example.PrintVer
- <java load-set X>
- >>> nv2=example.Version(2)
- >>> example.PrintVer.print(nv2)
- new version 2
- >>> PrintVer.print(nv2)
- Traceback (innermost last):
- File "<console>", line 1, in ?
- TypeError: print(): 1st arg can't be coerced to example.Version
- >>> example.PrintVer.print(v)
- Traceback (innermost last):
- File "<console>", line 1, in ?
- TypeError: print(): 1st arg can't be coerced to example.Version
- >>> os.rename(xp('example'),xp('_xample'))
-
-.. note:: Differently from python packages reload, load-sets reload the
- complete hosted hierarchy.
-.. note:: Class versions across reloads are not interoperable.
-
-Like for python classes and python reload, old versions are kept around,
-if there are still references to them. But what happens if they are no
-longer used?
-
-Java Classes Unloading
-======================
-
-One would expect that no longer referenced java classes would be unloaded,
-but the situation is not that simple.
-
-In order to give a python-class-like view on python side and for
-implementation reasons jython wraps java classes (in instances of
-org.python.core.PyJavaClass). Clearly the mapping from java classes to
-their wrapped version should be unique (e.g. to guarantee == and 'is'
-semantic). So jython keeps this mapping in an internal table. This is
-also good because building the wrappers is expensive.
-
-Note: Typically one should care about java classes unloading only for
-very dynamic applications, like IDEs or long-running apps, that would
-go out memory if old versions of reloaded classes would not be collected.
-
-Clearly the entries somehow block unloading. On the other hand java
-classes unloading is just a memory consumption optimization (and as such
-is it presented in Java Language Specification). Actual jvms clearly
-support this. JPython simply kept the entries in the table forever but
-Jython and "jreload" try to make unloading possible.
-
-Note: java never unloads system classes (java.* etc) nor classes from
-classpath. Further Jython cannot unload sys.path java classes. So
-the whole unload issue makes sense only with "jreload" or custom
-class-loaders.
-Java 2 and jython internalTablesImpl option
-
-Under java2 jython offers table implementations that exploit soft/weak
-references in order to discard entries (when this is OK) for unloading.
-
-A possible policy would be to keep an entry as long as the corresponding
-java class is still referenced outside the table (both by java or jython
-code). But this one cannot be implemented. [Tech.: One cannot add fields
-to final java class java.lang.Class!] So entries are kept as long as
-the wrapped version is still in use.
-These implementations can be chosen trough
-python.options.internalTablesImpl registry option. Note: they only
-influence classes unloading, there is no need and reason to use them,
-unless one depends on class unloading to avoid memory leakage.
-
-internalTablesImpl = weak -- Sets implementation using weak-refs. Table
-entries for not referenced (outside the table) wrapped versions are
-"discarded" at garbage collection points. If a class or some of its
-instances are continuously passed from java to jython side, but no
-long-living reference to it is kept from jython side, this can imply a
-performance penalty (rebuilding the wrapped version is expensive). On
-the other hand this is a good setting for testing if unloading actually
-happens or some references hunting around prevent it.
-
-[Note: With jdk 1.3 java -verbose:class can help tracking class unloads,
-and System.gc forces class unloading. With jdk 1.2 java -verbose:gc should
-give some information on class unloading, but unloading of classes happen
-at unpredictable points and System.gc does not trigger it. Also weak-refs
-allow testing for unloading and gc.]
-
-internalTablesImpl = soft --Sets implementation using soft-refs. Table
-entries for not referenced (outside the table) wrapped
-versions are "discarded" on memory shortage, given soft-reference
-definition. Soft-references behavior is not specified in full details,
-so the actual behavior will depend on the concrete jvm. But if actual
-(jvm) implementations are not too bad, this should be a good setting
-for production code, which relies on unloading to avoid out of memory
-failures.
-
-Java 1.1
-========
-
-To be honest the unloading support that jython can offer under java
-1.1 (given the absence of weak/soft-refs) is error-prone and anything
-serious would require "too much" caution, but this should not be a real
-issue. Support is offered only for "jreload" needs, in these forms:
-
-# Before reload(X) one can issue X.unload(). X.unload() discards all the
-entries for the old versions of the classes in X. This is safe only if
-all python subclasses and all instances of them have been destroyed.
-# One can "extract" the information needed in order to discard the
-entries for the versions actually present in X at a later point (after
-a whole series of reloads):
-
- u_t1=X.unload # extract unload info for time t1 versions
- ... reloads ...
- u_t1() # discard entries for time t1 versions
-
-u_t1() is safe only if at that point all subclasses/instances of the
-involved versions have been destroyed.
-
-.. note:: these idioms work also with the standard internal tables
- implementation under java2, and for compatibility even with the weak/soft
- implementations.
-
-JReload Example Source Files
-============================
-
-Jar example.Version ::
-
- package example;
-
- public class Version {
-
- private int ver;
-
- public Version(int ver) {
- this.ver = ver;
- }
-
- public String toString() {
- return "version "+ver;
- }
-
- }
-
-example.PrintVer ::
-
- package example;
-
- public class PrintVer {
-
- static public void print(Version ver) {
- System.out.println(ver);
- }
-
- }
-
-New example.Version ::
-
- package example;
-
- public class Version {
-
- private int ver;
-
- public Version(int ver) {
- this.ver = ver;
- }
-
- public String toString() {
- return "new version "+ver;
- }
-
- }
-
-
--------------------------------
-Database connectivity in Jython
--------------------------------
-
-The zxJDBC package provides a nearly 100% Python DB API 2.0 compliant
-interface for database connectivity in Jython. It is implemented entirely
-in Java and makes use of the JDBC API. This means any database capable
-of being accessed through JDBC, either directly or using the JDBC-ODBC
-bridge, can be manipulated using zxJDBC.
-Getting a Connection
-
-First, make sure a valid JDBC driver is in your classpath. Then start
-Jython and import the zxJDBC connection factory.
-Using a Driver
-
-The most common way to establish a connection is through a Driver. Simply
-supply the database, username, password and JDBC driver classname to
-the connect method. If your driver requires special arguments, pass them
-into the connect method as standard Python keyword arguments. You will
-be returned a connection object. ::
-
- Jython 2.1b1 on java1.4.0-beta3 (JIT: null)
- Type "copyright", "credits" or "license" for more information.
- >>> from com.ziclix.python.sql import zxJDBC
- >>> d, u, p, v = "jdbc:mysql://localhost/test";, None, None,
- "org.gjt.mm.mysql.Driver"
- >>> db = zxJDBC.connect(d, u, p, v)
- optionally
- >>> db = zxJDBC.connect(d, u, p, v, CHARSET='iso_1')
- >>>
-
-Using a DataSource (or ConnectionPooledDataSource)
-==================================================
-
-The only required argument is the fully-qualified classname of the
-DataSource, all keywords will use JavaBeans reflection to set properties
-on the DataSource. ::
-
- Jython 2.1b1 on java1.4.0-beta3 (JIT: null)
- Type "copyright", "credits" or "license" for more information.
- >>> from com.ziclix.python.sql import zxJDBC
- >>> params = {}
- >>> params['serverName'] = 'localhost'
- >>> params['databaseName'] = 'ziclix'
- >>> params['user'] = None
- >>> params['password'] = None
- >>> params['port'] = 3306
- >>> db = apply(zxJDBC.connectx, ("org.gjt.mm.mysql.MysqlDataSource",),
- params)
- >>>
-
-Using a JNDI lookup
-===================
-
-It is possible for zxJDBC to use a Connection found through a JNDI
-lookup. This is particularly useful in an application server (such as when
-using PyServlet). The bound object can be either a String, Connection,
-DataSource or ConnectionPooledDataSource. The lookup will figure out
-the instance type and access the Connection accordingly,
-
-The only required argument is the JNDI lookup name. All keyword arguments
-will be converted to their proper Context field value if the keyword
-matches one of the constants. If a field name does not exist for the
-keyword, it will passed as declared. The resulting environment will be
-used to build the InitialContext.
-
-This example uses the simple Sun FileSystem JNDI reference
-implementation. Please consult the JNDI implementation you intend to use
-for the InitialContextFactory classname as well as the connection URL. ::
-
- Jython 2.1b1 on java1.4.0-beta3 (JIT: null)
- Type "copyright", "credits" or "license" for more information.
- >>> from com.ziclix.python.sql import zxJDBC
- >>> jndiName = "/temp/jdbc/mysqldb"
- >>> factory = "com.sun.jndi.fscontext.RefFSContextFactory"
- >>> db = zxJDBC.lookup(jndiName, INITIAL_CONTEXT_FACTORY=factory)
- >>>
-
-Getting a Cursor
-================
-
-In order execute any operation, a cursor is required from the
-connection. There are two different kinds of cursors: static and dynamic.
-
-The primary difference between the two is the way they manage the
-underlying ResultSet. In the static version, the entire ResultSet is
-iterated immediately, the data converted and stored with the cursor
-and the ResultSet closed. This allows the cursor to know the rowcount
-(not available otherwise within JDBC) and set the .rowcount attribute
-properly. The major disadvantage to this approach is the space/time
-constraints might be extraordinary.
-
-The solution to the problem are dynamic cursors which keep a handle to
-the open ResultSet and iterate as required. This drastically decreases
-memory consumption and increases perceived response time because no work
-is done until asked. The drawback is the .rowcount attribute can never
-be accurately set.
-
-To execute a query simply provide the SQL expression and call
-execute. The cursor now has a description attribute detailing the column
-information. To navigate the result set, call one of the fetch methods
-and a list of tuples will be returned. ::
-
- >>> c = db.cursor() # this gets a static cursor
- or
- >>> c = db.cursor(1) # this gets a dynamic cursor
- >>> c.execute("select count(*) c from player")
- >>> c.description
- [('c', 3, 17, None, 15, 0, 1)]
- >>> for a in c.fetchall():
- ... print a
- ...
- (13569,)
- >>>
-
-When finished, close the connections. ::
-
- >>> c.close()
- >>> db.close()
- >>>
-
-To call a stored procedure or function provide the name and any params
-to callproc. The database engine must support stored procedures. The
-examples below have been tested with Oracle, SQLServer and Informix. Refer
-to the Python DP API spec for how OUT and INOUT parameters work.
-
-.. note:: The name of the stored procedure can either be a string or
- tuple. This is NOT portable to other DB API implementations.
-
-SQL Server
-----------
-
->>> c = db.cursor() # open the database as in the examples above
->>> c.execute("use northwind")
->>> c.callproc(("northwind", "dbo", "SalesByCategory"), ["Seafood",
-"1998"], maxrows=2)
->>> for a in c.description:
-... print a
-...
-('ProductName', -9, 40, None, None, None, 0)
-('TotalPurchase', 3, 17, None, 38, 2, 1)
->>> for a in c.fetchall():
-... print a
-...
-('Boston Crab Meat', 5318.0)
-('Carnarvon Tigers', 8497.0)
->>> c.nextset()
-1
->>> print c.fetchall()
-[(0,)]
->>> print c.description
-[('@RETURN_VALUE', 4, -1, 4, 10, 0, 0)]
->>>
-
-Oracle
-------
-
->>> c = db.cursor() # open the database as in the examples above
->>> c.execute("create or replace function funcout (y out varchar2)
-return varchar2 is begin y := 'tested'; return 'returned'; end;")
->>> params = [None]
->>> c.callproc("funcout", params)
->>> print params
-['tested']
->>> print c.description
-[(None, 12.0, -1, None, None, None, 1)]
->>> print c.fetchall()
-[('returned',)]
->>>
-
-When finished, close the connections.
-
->>> c.close()
->>> db.close()
->>>
-
-Standard extensions to the Python DB API
-
-* connection.dbname: Same as DatabaseMetaData.getDatabaseProductName
-* connection.dbversion: Same as DatabaseMetaData.getDatabaseProductVersion
-* cursor.updatecount: The value obtained from calling Statement.getUpdateCount
-* cursor.lastrowid: The value obtained from calling DataHandler.getRowId
-* cursor.tables(qualifier,owner,table,type): Same as DatabaseMetaData.getTables
-* cursor.columns(qualifier,owner,table,column): Same as DatabaseMetaData.getColumns
-* cursor.foreignkeys(primary_qualifier,primary_owner,pimary_table, foreign_qualifier,foreign_owner,foreign_table): Same as DatabaseMetaData.getCrossReference
-* cursor.primarykeys(qualifier,owner,table): Same as DatabaseMetaData.getPrimaryKeys
-* cursor.procedures(qualifier,owner,procedure): Same as DatabaseMetaData.getProcedures
-* cursor.procedurecolumns(qualifier,owner,procedure,column): Same as DatabaseMetaData.getProcedureColumns
-* cursor.statistics(qualifier,owner,table,unique,accuracy): Same as DatabaseMetaData.getIndexInfo
-
-Datatype mapping callbacks through DataHandler
-==============================================
-
-The DataHandler interface has three methods for handling type
-mappings. They are called at two different times, one when fetching and
-the other when binding objects for use in a prepared statement. I have
-chosen this architecture for type binding because I noticed a number
-of discrepancies in how different JDBC drivers handled database types,
-in particular the additional types available in later JDBC versions.
-
-life cycle
-----------
-
-public void preExecute(Statement stmt) throws SQLException;
- A callback prior to each execution of the statement. If the statement
- is a PreparedStatement (created when parameters are sent to the
- execute method), all the parameters will have been set.
-
-public void postExecute(Statement stmt) throws SQLException;
- A callback after successfully executing the statement. This is
- particularly useful for cases such as auto-incrementing columns
- where the statement knows the inserted value.
-
-developer support
------------------
-
-public String getMetaDataName(String name);
- A callback for determining the proper case of a name used in a
- DatabaseMetaData method, such as getTables(). This is particularly
- useful for Oracle which expects all names to be upper case.
-
-public PyObject getRowId(Statement stmt) throws SQLException;
- A callback for returning the row id of the last insert statement.
-
-binding prepared statements
----------------------------
-
-public Object getJDBCObject(PyObject object, int type);
- This method is called when a PreparedStatement is created through
- use of the execute method. When the parameters are being bound to
- the statement, the DataHandler gets a callback to map the type. This
- is only called if type bindings are present.
-
-public Object getJDBCObject(PyObject object);
- This method is called when no type bindings are present during the
- execution of a PreparedStatement.
-
-building results
-----------------
-
-public PyObject getPyObject(ResultSet set, int col, int type);
- This method is called upon fetching data from the database. Given
- the JDBC type, return the appropriate PyObject subclass from the
- Java object at column col in the ResultSet set.
-
-callable statement support
---------------------------
-
-::
-
- public PyObject getPyObject(CallableStatement stmt, int col, int type)
- throws SQLException;
- This method is called upon fetching data from the database after
- calling a stored procedure or function. Given the JDBC type, return
- the appropriate PyObject subclass from the Java object at column
- col in the CallableStatement.
-
- public void registerOut(CallableStatement statement, int index, int
- colType, int dataType, String dataTypeName) throws SQLException;
- This method is called to register an OUT or INOUT parameter on the
- stored procedure. The dataType comes from java.sql.Types while the
- dataTypeName is a vendor specific string.
-
- public String getProcedureName(PyObject catalog, PyObject schema,
- PyObject name);
- This method is called to build a stored procedure's name.
-
-It is simple to use these callbacks to achieve the desired result for your
-database driver. In the majority of cases nothing needs to be done to get
-the correct datatype mapping. However, in the cases where drivers differ
-from the spec or handle values differently, the DataHandler callbacks
-should provide the solution.
-Example DataHandler for Informix booleans
-
-One such case where a driver needs a special mapping is Informix
-booleans. The are represented as the characters 't' and 'f' in the
-database and have their own type boolean. You can see from the example
-below, without the special DataHandler, the boolean type mapping fails. ::
-
- Jython 2.1b1 on java1.4.0-beta3 (JIT: null)
- Type "copyright", "credits" or "license" for more information.
- >>> from com.ziclix.python.sql import zxJDBC
- >>> zxJDBC.autocommit = 0
- >>> d, u, p, v = "database", "user", "password",
- "com.informix.jdbc.IfxDriver"
- >>> db = zxJDBC.connect(d, u, p, v)
- >>> c = db.cursor()
- >>> c.execute("create table g (a boolean)")
- >>> c.execute("insert into g values (?)", [1])
- Traceback (innermost last):
- File "<console>", line 1, in ?
- Error: No cast from integer to boolean. [SQLCode: -9634]
- >>> from com.ziclix.python.sql.informix import InformixDataHandler
- >>> c.datahandler = InformixDataHandler(c.datahandler)
- >>> c.execute("insert into g values (?)", [1], {0:zxJDBC.OTHER})
- >>>
-
-As you can see, the default handler fails to convert the Python 1 into
-an Informix boolean because the IfxDriver treats booleans as JDBC type
-OTHER. The InformixDataHandler is intimately aware of the IfxDriver
-mappings and understands how to interpret Python values as booleans when
-the JDBC type is OTHER.
-
-This functionality is also useful in handling the more advanced JDBC
-2.0 types CLOB, BLOB and Array.
-
-You can also implement the DataHandler from within Jython as in this
-simple example: ::
-
- >>> class PyHandler(DataHandler):
- >>> def __init__(self, handler):
- >>> self.handler = handler
- >>> def getPyObject(self, set, col, datatype):
- >>> return self.handler.getPyObject(set, col, datatype)
- >>> def getJDBCObject(self, object, datatype):
- >>> print "handling prepared statement"
- >>> return self.handler.getJDBCObject(object, datatype)
- >>>
- >>> c.datahandler = PyHandler(c.datahandler)
- >>> c.execute("insert into g values (?)", [1])
- handling prepared statement
- >>>
-
-dbexts
-======
-
-dbexts is a wrapper around DB API 2.0 compliant database modules. It
-currently supports zxJDBC and mxODBC but could easily be modified to
-support others. It allows developers to write scripts without knowledge
-of the implementation language of Python (either C or Java). It also
-greatly eases the burden of database coding as much of the functionality
-of the Python API is exposed through easier to use methods.
-
-Configuration file
-==================
-
-dbexts needs a configuration file in order to create a connection. The
-configuration file has the following format:
-
-[default]
-name=mysql
-
-[jdbc]
-name=mysql
-url=jdbc:mysql://localhost/ziclix
-user=
-pwd=
-driver=org.gjt.mm.mysql.Driver
-datahandler=com.ziclix.python.sql.handler.MySQLDataHandler
-
-[jdbc]
-name=ora
-url=jdbc:oracle:thin:@localhost:1521:ziclix
-user=ziclix
-pwd=ziclix
-driver=oracle.jdbc.driver.OracleDriver
-datahandler=com.ziclix.python.sql.handler.OracleDataHandler
-
-API
-===
-
-dbexts will default to looking for a file named 'dbexts.ini' in the same
-directory as dbexts.py but can optionally be passed a filename to the
-cfg attribute.
-
-::
-
- __init__(self, dbname=None, cfg=None, resultformatter=format_resultset,
- autocommit=1)
- The initialization method for the dbexts class. If dbname is None,
- the default connection, as specified in the cfg file will be used.
-
- isql(self, sql, params=None, bindings=None, maxrows=None)
- Interactively execute sql statement. If self.verbose is true, then
- the results (if any) are displayed using the result formatting
- method. If maxrows is specified, only maxrows are displayed.
-
- raw(self, sql, params=None, bindings=None, delim=None, comments=comments)
- Executes the sql statement with params and bindings as
- necessary. Returns a tuple consisting of (headers, results).
-
- schema(table, full=0, sort=1)
- Displays the schema (indicies, foreign keys, primary keys and
- columns) for the table parameter. If full is true, also compute
- the exported (or referenced) keys. If sort is true (the default),
- sort the column names.
-
- >>> d.schema("store")
- Table
- store
-
- Primary Keys
- store_id {store_3}
-
- Imported (Foreign) Keys
- location (city.city_id) {store_7}
-
- Exported (Referenced) Keys
- store_id (site_store.store_id) {site_store_8}
-
- Columns
- location int(4), non-nullable
- store_id serial(4), non-nullable
- store_name varchar(32), non-nullable
-
- Indices
- unique index {523_8115} on (store_id)
- unique index {store_ix_1} on (store_name)
- >>>
-
- table(table=None, types=("TABLE",), owner=None, schema=None)
- If no table argument, displays a list of all tables. If a table
- argument, displays the columns of the given table.
-
- proc(self, proc=None, owner=None, schema=None)
- If no proc argument, displays a list of all procedures. If a proc
- argument, displays the parameters of the given procedure.
-
- bcp(src, table, where='(1=1)', parameters=[], selective=[], ignorelist=[],
- autobatch=0)
- Bulk Copy from one database/table to another. The current instance
- of dbexts is the source database to which the results of the query
- on the foreign database will be inserted. An optional where clause
- can narrow the number of rows to be copied.
-
-The following are generally not called since isql and raw can handle
-almost all cases.
-
-begin(self)
- Creates a new cursor.
-
-rollback(self)
- Rollback all the statements since the creation of the cursor.
-
-commit(self, cursor=None, maxrows=None)
- Commit all the statements since the creation of the cursor.
-
-display(self)
- Display the results using the formatter.
-
-Example session
-===============
-
-::
-
- Jython 2.1b1 on java1.4.0-beta3 (JIT: null)
- Type "copyright", "credits" or "license" for more information.
- >>> from dbexts import dbexts
- >>> d = dbexts()
- >>> d.isql("create table store (store_id int, store_name varchar(32),
- location int)")
- >>> d.isql("insert into store values (?, ?, ?)", [(1, "amazon.com", 3),
- (2, "egghead.com", 4)])
- >>> d.isql("insert into store values (?, ?, ?)", [(15, "800.com", 1),
- (19, "fogdog.com", 3)])
- >>> d.isql("insert into store values (?, ?, ?)", [(5, "nike.com", 4)])
- >>> d.isql("select * from store order by store_name")
-
- STORE_ID | STORE_NAME | LOCATION
- ---------------------------------
- 15 | 800.com | 1
- 1 | amazon.com | 3
- 2 | egghead.com | 4
- 19 | fogdog.com | 3
- 5 | nike.com | 4
-
- 5 rows affected
-
- >>>
-
-.. _JavaDoc documentation: http://www.jython.org/docs/javadoc/index.html
-.. _`Python Tutorial`: http://www.python.org/doc/tut/tut.html
-.. _Python Library Reference: http://www.python.org/doc/lib/lib.html
-.. _Python Language Reference: http://www.python.org/doc/current/ref/ref.html
-.. _Jython FAQ: http://www.jython.org/Project/faq.html
-.. _Jython-users mailing list archives: http://sourceforge.net/mailarchive/forum.php?forum_id=5586
-.. _Jython-users mailing list: http://lists.sourceforge.net/lists/listinfo/jython-users
-.. _org.python.util.PythonInterpreter: http://www.jython.org/docs/javadoc/org/python/util/PythonInterpreter.html
Copied: trunk/sandbox/wierzbicki/mockup/Project/userfaq.txt (from rev 2753, trunk/sandbox/wierzbicki/mockup/Project/faq.txt)
===================================================================
--- trunk/sandbox/wierzbicki/mockup/Project/userfaq.txt (rev 0)
+++ trunk/sandbox/wierzbicki/mockup/Project/userfaq.txt 2006-05-28 13:19:57 UTC (rev 2772)
@@ -0,0 +1,645 @@
+==========
+Jython FAQ
+==========
+
+.. contents:: Table of Contents
+.. sectnum::
+
+General information and availability
+====================================
+
+What is Jython?
+---------------
+Jython is the successor to JPython. The Jython project was created in
+accordance with the CNRI JPython 1.1.x license, in order to ensure the
+continued existence and development of this important piece of Python
+software. The intent is to manage this project with the same open policies
+that are serving CPython so well.
+
+Mailing lists, CVS and all current information on the Jython project is
+available at SourceForge, at http://sourceforge.net/projects/jython
+
+The name had to be changed to something other than JPython, because of
+paragraph 4 in the JPython-1.1 license: ::
+
+ 4. Licensee may not use CNRI trademarks or trade name, including
+ JPython [...] to endorse or promote products [...]
+
+Is Jython the same language as Python?
+--------------------------------------
+We will always strive to ensure that Jython remains as compatible with
+CPython as possible. Nevertheless, there are a number of differences
+between the two implementations that are unlikely to go away. These range
+from the trivial - Jython's code objects don't have a co_code attribute
+because they don't have any Python bytecodes; to the significant -
+Jython uses Java's true garbage collection rather than Python's reference
+counting scheme.
+
+ http://jython.sourceforge.net/docs/differences.html
+
+Python has never really had much of a language definition beyond it's
+C-based implementation. The existence of Jython changed that for the first
+time and will hopefully lead to a much clearer sense of what Python the
+language is; independent of any specific implementation.
+
+.. FIXME: move/edit this paragraph.
+
+We will be preparing a version of Python's regression test that would
+be appropriate for new implementations of the language. This is a good
+first step towards defining what parts of Python are essential and which
+are incidental
+
+What is the current status of Jython?
+--------------------------------------
+The Jython project was announced on 19-oct-2000. The first alpha release
+occured on 26-nov-2000.
+
+The final release of Jython-2.0 occured on 17-jan-2001. The final release
+of Jython-2.1 occured on 31-dec-2001.
+
+Current work include improvements to java integration and implementing
+the lastest features from CPython 2.2/3.
+
+How fast is Jython?
+-------------------
+The startup time and runtime performance for Jython are largely determined
+by the JVM.
+
+Current status is that CPython 2.3 on Windows2000 is about twice as
+fast as Jython 2.1 on JDK1.4 on Windows2000. However, because of Java's
+slow startup time, Jython starts much more slowly (2.4 s) than CPython
+(80 ms). This means you don't want to do standard CGI in Jython, but
+long-running processes are fine.
+
+The following notes are retained for historical interest.
+
+At IPC-6 JimH reported speeds equal to CPython 1.4 on the pystone
+benchmark. When Guido released CPython 1.5 he succeeded in making it
+about 2x faster than the 1.4 release. The current release of CPython
+is 1.5.2 which might be only slightly faster than 1.5. JimH re-ran his
+benchmark tests against CPython 1.5 and his then current release of
+Jython, finding that Jython was about 2.5x slower than CPython 1.5. I
+have recently run a few informal benchmarks and found some interesting
+numbers: using Sun's JDK 1.2.1 with JIT on a Solaris 2.6 Sparc Ultra 2,
+I found Jython 1.1beta3 to produce pystone numbers equal to (or very
+slightly better than) CPython 1.5.2+.
+
+The problem, of course, is that JITs are still not reliable enough for
+Jython. Turning off the JIT on the above platform, can slow Jython down
+by a factor of 10.
+
+The speed of Jython is tied very tightly to the speed of the underlying
+JVM. The benchmark results that JimH reported were all using Microsoft's
+JVM from Internet Explorer 4.0. The next fastest JVM that he used was
+almost a factor of 2 slower than this. Since the performance of JVMs
+changes nearly every day, at some point I'll need to collect a set of
+scores comparing pystone performance on a wider variety of JVM's.
+
+Finally, pystone is not the last word in benchmarking. At the moment
+I'm more concerned with making Jython complete and correct than with
+performance. We will continually be revisiting performance issues both to
+examine better benchmark's for comparing Jython and CPython (as well as
+other scripting languages for the JVM) and work at optimizing Jython's
+performance.
+
+Installing Jython
+=================
+
+Why do I get NoClassDefFoundError when running the installer
+------------------------------------------------------------
+Make sure that the class name on the command line doesn't end in
+.class. Also make sure that the installer actually exists in your current
+working directory.
+
+Why can't I use "from java import ..." on Windows?"
+---------------------------------------------------
+This problem can occur if you are using Microsoft's VM (i.e. jview.exe)
+which provides the standard classes in a different format. You need to
+run the following command in a console window before using Jython: ::
+
+ clspack -auto
+
+What is "python.path" and "python.prepath" mean in the Jython registry
+----------------------------------------------------------------------
+
+.. FIXME: do we need to even talk about pre-2.0 anymore?
+
+The key "python.path" in the Jython registry changed in the 2.0 version. This
+FAQ entry is intended to clarify registry keys related to sys.path
+settings.
+
+Before Fri, December 15, 2000- the "python.path" key in the registry file
+appended the given value to the sys.path list before the (sys.prefix)/lib
+directory is added. This means for Jython-2.0a1 and before, the above
+behavior is expected.
+
+Changes committed on December 15, 2000 change the behavior so that
+the registry's "python.path" key is appended to sys.path after
+(sys.prefix)/lib directory. This applies to CVS versions and any
+subsequently released versions of Jython.
+
+This mimics the behavior of the appending that takes place in the
+autoloaded site.py. Traditionally JPython users have appended the CPython
+path in this registry key; however, this was unsafe as it then preceded
+the Jython lib directory. This change eliminates errors associated with
+appending the CPython lib path in this key.
+
+For those instances where you do intend to add something to the
+sys.path before (sys.prefix)/lib, there is a new registry key called
+"python.prepath". This exists only after the 20001215 change date.
+
+Here is the summary of changing sys.path:
+
+Before 20001215:
+
+ 1. python.path key appends given path before (sys.prefix)/lib.
+ Do not put the CPython Lib dir in the python.path key unless
+ you precede it with the Jython lib path. (using site.py may be
+ a better choice).
+ 2. Jython-2.0a1 autoloads site.py (as does Python20) and appends
+ path changes after (sys.prefix)/lib- a better alternative to
+ appending to sys.path.
+
+After 20001215:
+
+ 1. python.path key appends given path after (sys.prefix)/lib.
+ Same as autoloaded site.py file.
+ 2. A new key, "python.prepath", was added to append path's before
+ (sys.prefix)/lib if needed.
+
+If there is confusion about site.py:
+
+ site.py is automatically loaded on normal startup in Python 2.0
+ and Jython-2.0a1. This used to be user-loaded in Python 1.5.2
+ and JPython11.
+
+Edit this entry / Log info
+
+Why no command-line history in Jython?
+--------------------------------------
+The shells and other tools commonly associated with having a command-line
+history get this functionality from the C 'readline' package. There is
+experimental 'readline' classes in Java, and is likely to be in Jython's
+future. For the current release, there is console.py in the demo directory
+that adds a simple up/down.
+
+It is not commonly the case that programs look to the shell for this
+functionality, it is more common that readline is compiled in to the shell
+(or CPython) you are using which provides this functionality. However,
+some shells wrap the stdin/out of other programs (Jython). Shell mode in
+emacs is an excellent example. "rlterm", a shell that comes with the Unix
+version of Yorick, also does this (i.e. "rlterm jython"). There may be
+many others do the same so you can supplant the functionality of readline.
+
+Why do I get the error, "can't create package cache dir, '/cachedir/packages'"
+------------------------------------------------------------------------------
+An essential optimization in Jython is the caching of Java package
+information. The caching requires '/cachedir/packages/' in the python.home
+directory. It is often the case on `*nix` that users lack sufficient
+priveledges to create or write to this directory.
+
+Because the problem is merely permissions, something similar to "mkdir
+cachedir; chmod a+rw cachedir" within Jython's directory should eliminate
+this error message.
+
+Where's the registry file
+-------------------------
+Jython's installation includes a file called "registry" that you will find
+in the root directory of the Jython installation (e.g. /usr/local/jython
+or c:\jython).
+
+At initialization, Jython searches for the "registry" file in the
+directory specified by the "python.home" property, or the ".jython"
+file in the user's home directory.
+
+The "python.home" property is often set in the startup with Java's -D
+switch. The shell script that starts Jython (jython.bat or jython)
+demonstrates the use of the -D switch to set the "python.home"
+property. When embedding Jython, it is often still best to use the -D
+switch because the -D properties appear in System.getProperties(),
+which is usually the "preProperties" (first arg) in the static
+PythonInterpreter.initialize method. With python.home in the
+preProperties, the interpreter successfully loads preProperties,
+registry properties, and postProperties (the second arg to initialize)
+in the correct order.
+
+If you wish to use your home directory, and do not know where your home
+directory is, don't worry- Jython knows:
+
+ >>> print java.lang.System.getProperty("user.home")
+
+If you run into complaints about create ".jython", don't worry-
+Jython can:
+
+ >>> import java, os
+ >>> filename = os.path.join(java.lang.System.getProperty("user.home"),
+ ".jython")
+ >>> open(filename, "w")
+
+GUI-less installer?
@@ Diff output truncated at 100000 characters. @@
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 2777
Author: fwierzbicki
Date: 2006-05-29 12:10:35 -0700 (Mon, 29 May 2006)
ViewCVS: http://svn.sourceforge.net/jython/?rev=2777&view=rev
Log Message:
-----------
Adding more developer guidance.
Modified Paths:
--------------
trunk/sandbox/wierzbicki/mockup/Project/bugs.txt
trunk/sandbox/wierzbicki/mockup/Project/devfaq.txt
trunk/sandbox/wierzbicki/mockup/Project/devguide.txt
Added Paths:
-----------
trunk/sandbox/wierzbicki/mockup/Project/patchadmin.txt
Modified: trunk/sandbox/wierzbicki/mockup/Project/bugs.txt
===================================================================
--- trunk/sandbox/wierzbicki/mockup/Project/bugs.txt 2006-05-28 21:58:10 UTC (rev 2776)
+++ trunk/sandbox/wierzbicki/mockup/Project/bugs.txt 2006-05-29 19:10:35 UTC (rev 2777)
@@ -2,9 +2,15 @@
Reporting Bugs
===============
--------------------------------
-Guidelines for submitting a bug
--------------------------------
+-----------------------------
+Viewing and submitting a bugs
+-----------------------------
-Bug Tracker http://sourceforge.net/tracker/?group_id=12867&atid=112867
+The Jython project uses SourceForge's bug tracking facility. Go to http://sourceforge.net/bugs/?group_id=12867 for all bug management needs.
+Using the sourceforge bug manager
+=================================
+
+By default, you will see the list of all Open bugs. You can change which bugs you're viewing by selecting the assigned_to/status/area/type select boxes.
+To submit a bug, use the "Submit a Bug" link, near the top of the page.
+
Modified: trunk/sandbox/wierzbicki/mockup/Project/devfaq.txt
===================================================================
--- trunk/sandbox/wierzbicki/mockup/Project/devfaq.txt 2006-05-28 21:58:10 UTC (rev 2776)
+++ trunk/sandbox/wierzbicki/mockup/Project/devfaq.txt 2006-05-29 19:10:35 UTC (rev 2777)
@@ -22,11 +22,13 @@
Who is who?
===========
-To get the real name, click on "View members" in the "Developer Info" box on the SourceForge project page. This presents a list of developers, giving their names and SourceForge IDs. A separate list of committers lists people with commit privileges to the Subversion repository.
+The list of developers with commit access is here: http://sourceforge.net/project/memberlist.php?group_id=12867
+This presents a list of developers, giving their names and SourceForge IDs.
+
How can I become a developer?
=============================
-Submit patches that fix bugs or implement features, especially features that exist in CPython but are not yet implemented in Jython. Once we accept a large enough patch from you (or many small patches) we will offer you commit access.
+Submit patches that fix bugs or implement features, especially features that exist in CPython but are not yet implemented in Jython.
----------------
Subversion (svn)
@@ -359,100 +361,4 @@
Note: If you are sure that you have the right permissions and a drop-box does not appear, check that you are actually logged in to SourceForge!
-For more information about the use of the "Status:" and "Assigned To:" fields consult the Patch Manager Guidelines; A recent copy can be found in the Appendix of this FAQ.
-
-----
-Bugs
-----
-
-Where can I submit/view bugs for Jython?
-========================================
-
-The Jython project uses SourceForge's bug tracking facility. Go to http://sourceforge.net/bugs/?group_id=5470 for all bug management needs. You will need to create a SourceForge account for yourself before submitting the first bug report; anonymous reports have been disabled since it was too difficult to get in contact with submitters.
-
-How do I use the sourceforge bug manager?
-=========================================
-
-By default, you will see the list of all Open bugs. You can change which bugs you're viewing by selecting the assigned_to/status/area/type select boxes.
-
-To submit a bug, use the "Submit a Bug" link, near the top of the page.
-
-------------------------
-Patch Manager Guidelines
-------------------------
-
-Intended use of SourceForge patch Resolution, Status & "Assigned To" fields Revision 4 16-Mar-2001
-
-In general, the Resolution and Status fields should be close to self-explanatory, and the "Assigned to:" field should be the person responsible for taking the next step in the patch process. Both fields are expected to change value over the life of a patch; the normal workflow is detailed below.
-
-When you've got the time and the ability, feel free to move any patch that catches your eye along, whether or not it's been assigned to you. And if you're assigned to a patch but aren't going to take reasonably quick action (for whatever reason), please assign it to someone else ASAP: at those times you can't actively help, actively get out of the way.
-
-If you're an expert in some area and know that a patch in that area is both needed and non-controversial, just commit your changes directly -- no need then to get the patch mechanism involved in it.
-
-You should add a comment to every patch assigned to you at least once a week, if only to say that you realize it's still on your plate. This rule is meant to force your attention periodically: patches get harder & harder to deal with the longer they sit.
-
-Status Open, Resolution None
-============================
-
-The initial state of all patches. The patch is under consideration, but has not been reviewed yet, or s under review but not yet Accepted or Rejected.
-
-The Resolution will normally change to Accepted or Rejected next. The person submitting the patch should (if they can) assign it to the person they most want to review it.
-
-Else the patch will be assigned via [xxx a list of expertise areas should be developed] [xxx but since this hasn't happened and volunteers are too few, andom assignment is better than nothing: if you're a Jython developer, expect to get assigned out of the blue!]
-
-Discussion of major patches is carried out on the Jython-Dev mailing list. For simple patches, the SourceForge comment mechanism should be sufficient. [xxx an email gateway would be great, ditto Ping's Roundup] For the reviewer: If you're certain the patch should be applied, change the Resolution to Accepted and assign it back to the submitter (if possible) for checkin. If you're certain the patch should never be accepted, change the Resolution to Rejected, Status to Closed, and assign it to None.
-
-If you have specific complaints that would cause you to change your mind, explain them clearly in a comment, leave the status Open, and reassign back to the submitter. If you're uncertain, leave the status Open, explain your uncertainties in a comment, and reassign the patch to someone you believe can address your remaining questions; or leave the status Open and bring it up on Jython-Dev.
-
-Status Open, Resolution Accepted
-================================
-
-The powers that be accepted the patch, but it hasn't been applied yet. [xxx flesh out -- Guido Bottleneck avoidable here?]
-
-The Status will normally change to Closed next.
-
-The person changing the Resolution to Accepted should, at the same time, assign the patch to whoever they believe is most likely to be able & willing to apply it (the submitter if possible).
-
-Status Closed, Resolution Accepted
-==================================
-
-The patch has been accepted and applied.
-
-The previous Resolution was Accepted, or possibly None if the submitter was Guido (or moral equivalent in some particular area of expertise).
-
-Status Closed, Resolution Rejected
-==================================
-
-The patch has been reviewed and rejected.
-
-There are generally no transitions out of this state: the patch is dead.
-
-The person setting this state should also assign the patch to None.
-
-Status Open, Resolution Out of date
-===================================
-
-Previous Resolution was Accepted or Postponed, but the patch no longer works.
-
-Please enter a comment when changing the Resolution to "Out of date", to record the nature of the problem and the previous state.
-
-Also assign it back to the submitter, as they need to upload a new version.
-
-Status Open, Resolution Postponed
-=================================
-
-The previous Resolution was None or Accepted, but for some reason (e.g., pending release) the patch should not be reviewed or applied until further notice.
-
-The Resolution will normally change to None or Accepted next.
-
-Please enter a comment when changing the Resolution to Postponed, to record the reason, the previous Resolution, and the conditions under which the patch should revert to Resolution None or Accepted. Also assign the patch to whoever is most likely able and willing to decide when the state should change again.
-
-Status Deleted
-==============
-
-Bit bucket.
-
-Use only if it's OK for the patch and its SourceForge history to disappear. As of 09-July-2000, SF does not actually throw away Deleted patches, but that may change.
-
-..Note: This FAQ was adapted from Python developers FAQ at http://www.python.org/dev/faq/
-
+..FIXME: For more information about the use of the "Status:" and "Assigned To:" fields consult the Patch Manager Guidelines.
Modified: trunk/sandbox/wierzbicki/mockup/Project/devguide.txt
===================================================================
--- trunk/sandbox/wierzbicki/mockup/Project/devguide.txt 2006-05-28 21:58:10 UTC (rev 2776)
+++ trunk/sandbox/wierzbicki/mockup/Project/devguide.txt 2006-05-29 19:10:35 UTC (rev 2777)
@@ -169,9 +169,100 @@
Coding Guidance
===============
- * CodingStandards : The standards for writing Java code for Jython
- * JythonModulesInJava : How to write a Jython module in Java
- * JythonClassesInJava : How to write a Jython class in Java
+ * CodingStandards_ : The standards for writing Java code for Jython
+ * JythonModulesInJava_ : How to write a Jython module in Java
+ * JythonClassesInJava_ : How to write a Jython class in Java
+
+New Style Classes
+=================
+`Unifying types and classes in Python`_
+
+svn co jython/trunk/sandbox
+
+cd sandbox/jt
+
+There are two primary objectives:
+
+ 1. expose the necessary methods for making an existing class 'new-style'
+ 2. generating a wrapper class for subclasses in python to implement
+
+To do this there are two scripts:
+
+ * gexpose.py (for exposing)
+ * gderived.py (for deriving or subclassing)
+
+They each have a simple input language for determing exactly what to implement. Note that these .expose and .derived files are hand generated.
+
+For example, looking at a partial listing of list.expose:
+
+type_name: list
+type_class: PyList
+# exposed methods
+expose_meth: :- append o
+expose_meth: :i count o
+expose_meth: pop i?
+expose_meth: :b __nonzero__
+
+So the type_name is 'list'.
+
+>>> type([])
+<type 'list'>
+
+It is intended to expose methods for PyList.
+
+ * It exposes the method 'append' which takes a PyObject and returns void.
+ * It exposes the method 'count' which takes a PyObject and returns an int.
+ * It exposes the method 'pop' which takes an optional int and returns a PyObject.
+ * It exposes the method '__nonzero__' which takes no arguments and returns a boolean.
+
+Running gexpose.py produces some Java code.
+
+$ python gexpose.py list.expose > list.txt
+
+Opening the file list.txt in your favorite editor you'll see the Java code. This code should then be pasted into the class PyList at the top of the file. This will result in a slew of compiler problems.
+
+The problem is PyList doesn't have any of the methods. The generated code expected 'list_append' but PyList has only 'append' so the compiler complains. This is intended. Now for the boring part. For each method exposed, we need to create a new method. For example:
+
+public void append(PyObject o) {
+ list_append(o);
+}
+
+final void list_append(PyObject o) {
+ resize(length+1);
+ list[length-1] = o;
+}
+
+Notice the new method is final and package protected. So follow the pattern for each method that needs to be exposed.
+
+The special method __init__ should delegate to 'list_init' which needs to handle the constructor arguments of a list. If there is no argument, create a new list. If an argument, copy it's contents to a new list.
+
+Make sure the class has a constructor which takes a PyType.
+
+Finally, make sure the type is registered with __builtin__.
+
+ * It should also be noted an existing 'list' was registered which provided the construction of a new list under the old scheme. I moved this code to PyList and deleted it from __builtin__. This is much better since all list construction now happens in one spot.
+
+Run some quick tests:
+
+>>> list()
+[]
+>>> list([1,2,3])
+[1, 2, 3]
+>>> type([])
+<type 'list'>
+>>> list
+<type 'list'>
+>>>
+
+After that was done, run the regrtest and the bugtests. The bugtests caught a bug in my original effort. I had forgotten to make the constructor with PyType argument so any list(arg) call failed quickly as the PyType instance was the argument to the PyList(PyObject) constuctor and since PyType is not iterable, the call failed. The tests were great in tracking this down.
+
+Next steps:
+
+ * automate this process a bit more if possible
+ * [].index.__self__ does not work correctly
+ * mutable __bases__ and __class__
+ * support for __del__
+ * support for __slots__
+
.. _Jim Hugunin's JPython paper: http://www.python.org/workshops/1997-10/proceedings/hugunin.html
-
Added: trunk/sandbox/wierzbicki/mockup/Project/patchadmin.txt
===================================================================
--- trunk/sandbox/wierzbicki/mockup/Project/patchadmin.txt (rev 0)
+++ trunk/sandbox/wierzbicki/mockup/Project/patchadmin.txt 2006-05-29 19:10:35 UTC (rev 2777)
@@ -0,0 +1,79 @@
+========================
+Patch Manager Guidelines
+========================
+
+Intended use of SourceForge patch Resolution, Status & "Assigned To" fields Revision 4 16-Mar-2001
+
+In general, the Resolution and Status fields should be close to self-explanatory, and the "Assigned to:" field should be the person responsible for taking the next step in the patch process. Both fields are expected to change value over the life of a patch; the normal workflow is detailed below.
+
+When you've got the time and the ability, feel free to move any patch that catches your eye along, whether or not it's been assigned to you. And if you're assigned to a patch but aren't going to take reasonably quick action (for whatever reason), please assign it to someone else ASAP: at those times you can't actively help, actively get out of the way.
+
+If you're an expert in some area and know that a patch in that area is both needed and non-controversial, just commit your changes directly -- no need then to get the patch mechanism involved in it.
+
+You should add a comment to every patch assigned to you at least once a week, if only to say that you realize it's still on your plate. This rule is meant to force your attention periodically: patches get harder & harder to deal with the longer they sit.
+
+Status Open, Resolution None
+============================
+
+The initial state of all patches. The patch is under consideration, but has not been reviewed yet, or s under review but not yet Accepted or Rejected.
+
+The Resolution will normally change to Accepted or Rejected next. The person submitting the patch should (if they can) assign it to the person they most want to review it.
+
+Else the patch will be assigned via [xxx a list of expertise areas should be developed] [xxx but since this hasn't happened and volunteers are too few, andom assignment is better than nothing: if you're a Jython developer, expect to get assigned out of the blue!]
+
+Discussion of major patches is carried out on the Jython-Dev mailing list. For simple patches, the SourceForge comment mechanism should be sufficient. [xxx an email gateway would be great, ditto Ping's Roundup] For the reviewer: If you're certain the patch should be applied, change the Resolution to Accepted and assign it back to the submitter (if possible) for checkin. If you're certain the patch should never be accepted, change the Resolution to Rejected, Status to Closed, and assign it to None.
+
+If you have specific complaints that would cause you to change your mind, explain them clearly in a comment, leave the status Open, and reassign back to the submitter. If you're uncertain, leave the status Open, explain your uncertainties in a comment, and reassign the patch to someone you believe can address your remaining questions; or leave the status Open and bring it up on Jython-Dev.
+
+Status Open, Resolution Accepted
+================================
+
+The powers that be accepted the patch, but it hasn't been applied yet. [xxx flesh out -- Guido Bottleneck avoidable here?]
+
+The Status will normally change to Closed next.
+
+The person changing the Resolution to Accepted should, at the same time, assign the patch to whoever they believe is most likely to be able & willing to apply it (the submitter if possible).
+
+Status Closed, Resolution Accepted
+==================================
+
+The patch has been accepted and applied.
+
+The previous Resolution was Accepted, or possibly None if the submitter was Guido (or moral equivalent in some particular area of expertise).
+
+Status Closed, Resolution Rejected
+==================================
+
+The patch has been reviewed and rejected.
+
+There are generally no transitions out of this state: the patch is dead.
+
+The person setting this state should also assign the patch to None.
+
+Status Open, Resolution Out of date
+===================================
+
+Previous Resolution was Accepted or Postponed, but the patch no longer works.
+
+Please enter a comment when changing the Resolution to "Out of date", to record the nature of the problem and the previous state.
+
+Also assign it back to the submitter, as they need to upload a new version.
+
+Status Open, Resolution Postponed
+=================================
+
+The previous Resolution was None or Accepted, but for some reason (e.g., pending release) the patch should not be reviewed or applied until further notice.
+
+The Resolution will normally change to None or Accepted next.
+
+Please enter a comment when changing the Resolution to Postponed, to record the reason, the previous Resolution, and the conditions under which the patch should revert to Resolution None or Accepted. Also assign the patch to whoever is most likely able and willing to decide when the state should change again.
+
+Status Deleted
+==============
+
+Bit bucket.
+
+Use only if it's OK for the patch and its SourceForge history to disappear. As of 09-July-2000, SF does not actually throw away Deleted patches, but that may change.
+
+..Note: This FAQ was adapted from Python developers FAQ at http://www.python.org/dev/faq/
+
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.