Differences between revisions 2 and 3
Revision 2 as of 2012-02-11 16:44:45
Size: 3524
Editor: JeffAllen
Comment: Notes I'm making while discovering how to use gderived.py
Revision 3 as of 2012-02-11 17:14:50
Size: 4869
Editor: JeffAllen
Comment: 1 and 0 argument forms discussed
Deletions are marked like this. Additions are marked like this.
Line 15: Line 15:
according to a brief specification. according to a brief specification. This code is connected with subclassing.
Line 19: Line 19:
actively-used in the creation of Jython. actively used in the creation of Jython.
Line 22: Line 22:
it will generate a reference to the sort of class {{{gderived.py}}} creates.

The modern exposer is described in the article PythonTypesInJava.
it will generate a reference to the sort of class {{{gderived.py}}} creates. The modern exposer is described in the article PythonTypesInJava.
Line 40: Line 38:
=== The 2-argument Forms ===
Line 41: Line 41:
python gderived.py <derived-spec> <output-file> python [--lazy] gderived.py <derived-spec> <output-file>
Line 63: Line 63:

The '''--lazy''' option causes {{{gderived.py}}} only to generate the output file if the input file is newer.

=== The 1-argument and 0-argument Forms ===

A second form of the command is:{{{
python gderived.py [--lazy] [<derived-spec>]
}}}
When using {{{gderived.py}}} in that way one is working with the same three user files as above,
and a configuration file {{{src/templates/mappings}}}. The entries in that file look like this:{{{
int.derived:org.python.core.PyIntegerDerived
object.derived:org.python.core.PyObjectDerived
random.derived:org.python.modules.random.PyRandomDerived
ast_Assert.derived:org.python.antlr.ast.AssertDerived
}}}
In effect, this file allows {{{gderived.py}}} to look up the second argument given the first,
although this second argument is now given in dotted notation.
In this form, the specification file {{{<name>.derived}}} has to be in {{{src/templates}}}
and the input and output classes will be found relative to {{{src}}}.

Finally, the <derived-spec> argument is optional. In the zero-argument form, {{{gderived.py}}} will process all of the
entries in {{{src/templates/mappings}}}. It is essentially this form, with the --lazy option, that implements the
{{{template}}} Ant target in {{{build.xml}}}.

Generating the *Derived classes

These are notes on the use of gderived.py, a tool you need when implementing new types in Jython.

Background

gderived.py and gexposed.py are a pair of Python scripts written support the wrapping of classes written in Java as Python classes. They are in the src/templates folder and they have to be run with that as the current directory.

The function of gderived.py is to read the source of the Java class and create a another Java source file in the same package, that extends the original, with highly-stylised content according to a brief specification. This code is connected with subclassing.

gexposed.py has been superseded by the exposer (org.python.expose.generate.Exposer) and the corresponding Ant task, but gderived.py remains actively used in the creation of Jython. gexposed.py is also active code, but only because gderived.py imports it. However, if you use the new exposer, even if you prohibit subclassing with @ExposedType(isBaseType=false), it will generate a reference to the sort of class gderived.py creates. The modern exposer is described in the article PythonTypesInJava.

At the time of starting these notes, there is no authoritative user-guide to gderived.py and what it achieves. These notes stem from use of the tool and a certain amount of reverse-engineering. Please improve on them by correcting misunderstandings and omissions.

The work was done on a Windows 7 system, using Python 2.7 (without trying later versions, because of the vintage of the code). The choice of OS shows sometimes in the direction of slashes in pathnames, but that shouldn't confuse anyone.

Although the motivation was to add a serious Python type (bytearray) to Jython, illustrations will be drawn from a facetiously-named type (piranha), with a Java implementation in src/org/python/ethel/the/frog/Piranha.java.

gderived.py as a Command

The 2-argument Forms

The most transparent form of the command is:

python [--lazy] gderived.py <derived-spec> <output-file>

When using gderived.py in that way one is working with three user files:

<derived-spec>, the specification for the contents of the derived Java class. By convention, this has the extension .derived, and the Python name of the type being defined. The files for Jython types are in the src/templates folder along with the scripts, but anywhere seems to work with this form of the command, so we'll use src/org/python/ethel/the/frog/piranha.derived (note lower case type name piranha).

<output-file>, the file in which the generated class will be written. This has to be in the Jython source tree under src/org/python. If your code is not there, gderived.py seems to run correctly, but will get the Java package statement wrong. You can supply any filename you like, but the class it writes will be named by adding "Derived" to the name of the input class. For our example the output file is src/org/python/ethel/the/frog/PiranhaDerived.java.

And last but not least, the class file that implements your type. The input file is identified from the directory of the output file and the class name given in the text of <derived-spec> (see below). This therefore also has to be in the Jython source tree under src/org/python. For our example the input file is src/org/python/ethel/the/frog/Piranha.java.

The --lazy option causes gderived.py only to generate the output file if the input file is newer.

The 1-argument and 0-argument Forms

A second form of the command is:

python gderived.py [--lazy] [<derived-spec>]

When using gderived.py in that way one is working with the same three user files as above, and a configuration file src/templates/mappings. The entries in that file look like this:

int.derived:org.python.core.PyIntegerDerived
object.derived:org.python.core.PyObjectDerived
random.derived:org.python.modules.random.PyRandomDerived
ast_Assert.derived:org.python.antlr.ast.AssertDerived

In effect, this file allows gderived.py to look up the second argument given the first, although this second argument is now given in dotted notation. In this form, the specification file <name>.derived has to be in src/templates and the input and output classes will be found relative to src.

Finally, the <derived-spec> argument is optional. In the zero-argument form, gderived.py will process all of the entries in src/templates/mappings. It is essentially this form, with the --lazy option, that implements the template Ant target in build.xml.

GeneratedDerivedClasses (last edited 2017-08-26 21:16:41 by JeffAllen)