Information that might be useful while implementing or maintaining a type  - some notes for the Jython Wiki, based on things I discovered while trying to implement {{{bytearray}}}.

= Types in General =
== A Hook for Bootstrapping ==

{{{_builtin_.java}}} is used to load types and functions into the globals table of the interpreter. There must be a statement in the body of {{{org.python.core._builtin_.fillWithBuiltins()}}} that names the type.

== Deriving and Exposing ==

A Jython type is defined by a Java class, say {{{Piranha.java}}}. The code you write in that class has to be transformed in two ways: the source of a second class will be created from it called {{{PiranhaDerived.java}}} (see GeneratedDerivedClasses); and the compiled version of your class, {{{Piranha.class}}} will be transformed by the type exposer utility (see PythonTypesInJava).

== Naming Exposed Methods ==

A typical Jython type contains a dozen or more methods that will be exposed as methods in Python - there is a rich array of standard library methods like {{{remove}}}, {{{__add__}}} and {{{__hash__}}}, depending on what the type does. Each Python method is exposed under its standard name, but (by convention) the name of Java method that implements it is formed from the Python name of the type, an underscore and the exposed method name. So {{{remove}}} is implemented by {{{piranha_remove}}}, and {{{__add__}}} is implemented by {{{piranha___add__}}}. (That was 3 underscores and 2 underscores.) It is usually not necessary to give the exposed name of the method in the {{{@ExposedMethod}}} annotation, because the exposer understands this convention. (It takes the Python name of the type from the {{{@ExposedType}}} annotation on the class.)

The exposed implementation methods should be {{{final}}} and are usually {{{synchronized}}}.

== Documentation Strings ==

The documentation string ({{{__doc__}}}) for each type and method could be given as a string literal argument to the {{{@ExposedMethod}}} annotation, but for Python language types there is a cleverer way. The {{{@ExposedMethod}}} annotations of such types refer to a constant string defined in {{{BuiltinDocs.Java}}}. By convention, the documentation string has a name formed from the Python name of the type, an underscore, the exposed method name, and "{{{_doc}}}". So {{{list.remove}}} is documented by {{{list_remove_doc}}}, and {{{list.__add__}}} is documented by {{{list___add___doc}}}. (That was 3 underscores each time.) A script {{{Misc/make_pydocs.py}}} is used to generate {{{BuiltinDocs.Java}}} running from a working CPython implementation of the correct vintage. The script contains an easily identified table of the types and built-in function objects for which it is to do this. Thus, to make all the documentation strings for Jython 2.6, one updates the table with any missing types and functions, and runs it under (say) CPython 2.6.6 (the latest at the time of writing).

== Java API Methods ==

Each exposed method has a twin in the Java API for the class. (Typically only the Java API has Javadoc comments.) This twin is named the same as the method as Python sees it, and delegates to the exposed method. Thus {{{__add__}}} simply calls {{{piranha___add__}}}.

On further investigation, it turns out that the code generated by compiling Python (to Java bytecode, obviously) also calls {{{__add__}}} directly: this is visible in the Java stack. This invites the speculation that it might be slightly more efficient to have {{{piranha___add__}}} call {{{__add__}}}.

== Implementing Comparison Operations ==

When Python code needs to compare two objects, the interpreter disappears into a maze of twisty passages, all alike. This is partly a fault in the design of Python, that gets rectified with version 3. There are two comparison ecosystems at work: one based on {{{__cmp__}}}, that is very similar to Java's {{{Comparable<T>.compareTo}}}, intended for sort ordering, and one based on the set of six "rich comparison" operations: {{{ __eq__, __ne__, __lt__, __le__, __ge__, __gt__}}} used to support the operators {{{ ==, !=, <, <=, >=, > }}}. It is possible to define {{{__cmp__}}} and the rich comparison operations inconsistently. In Python 3, {{{__cmp__}}} has gone, sorting is based on {{{__lt__}}}, and a single rich comparison function defines all six comparisons.

It is possible to compare objects of dissimilar type. Given {{{a<b}}} Python tries {{{a.__lt__(b)}}}, but if this produces no result ({{{null}}} in the Java code) Python will try {{{b.__gt__(a)}}}.

In a further nuance, {{{a<b}}} and {{{a.__lt__(b)}}} behave differently when {{{a.__lt__(b)}}} produces no result. (And a corresponding rule applies for the other 5 operators.) When an object {{{a}}} cannot compare itself to {{{b}}} the Python expression {{{a.__lt__(b)}}} evaluates to the special object {{{NotImplemented}}}, while {{{a<b}}} evaluates to {{{False}}}.
{{{
>>> "oops".__lt__(5)
NotImplemented
>>> "oops"<5
False
}}}

In a last touch, if you define only some of the operations, Python seems to synthesize missing ones, e.g. {{{__ge__}}} from the opposite of {{{__lt__}}}.