Top Description Fields Constructors Methods
org.python.core

pack-priv Class Clinic

extends Object
Class Inheritance
Imports
java.lang.invoke.MethodHandle, .MethodHandles, .MethodHandles.Lookup, .MethodType, org.python.base.InterpreterError
A collection of methods and MethodHandles for converting arguments when calling a Java method from Python. The class enables the implementation of built-in (or extension) Python types to be written in a natural way using Java standard and primitive types.

The class name refers to the CPython Argument Clinic (by Larry Hastings) which generates argument processing code for exposed methods defined in C and by a textual header.

Field Summary

Modifier and TypeField and Description
private static final MethodHandle
booleanValueMH

private static final MethodHandle
doubleArgMH

private static final MethodHandle
doubleValueMH

private static final MethodHandle
intArgMH

private static final MethodHandle
intValueMH

private static final MethodHandles.Lookup
LOOKUP

Lookup for resolving handles throughout the class.

private static final Class<?>
O

private static final MethodHandle
stringArgMH

private static final MethodHandle
voidValueMH

Constructor Summary

AccessConstructor and Description
private
Clinic()

Method Summary

Modifier and TypeMethod and Description
private static MethodHandle

Returns:

filter converting Python object to c.
adaptParameterToObject(Class<?>
Java type
c)

The logic of this method defines the standard for converting Python types to a specified Java type.

private static MethodHandle

Returns:

filter converting c to a Python object.
adaptReturnToObject(Class<?>
Java type
c)

The logic of this method defines the standard for converting specified Java types to Python.

pack-priv static MethodHandle[]

Returns:

array of filter-adaptors to expect Object.
argumentFilter(MethodType
type to adapt.
mt, int
index in the type at which to start.
pos)

Create an array of filters to convert an existing method handle, with the given type, to one that expects arguments (starting at a given index) that are all Object in the converted locations.

pack-priv static MethodHandle[]

Returns:

array of filter-adaptors to expect Object.
argumentFilter(MethodType
type to adapt.
mt)

Equivalent to argumentFilter(mt, 0)

pack-priv static MethodHandle

Returns:

null or a filter-adapter to return Object.
returnFilter(MethodType
type to adapt.
mt)

Return a filter that will adapt an existing method handle with the given type, to one that the returns Object or a sub-class.

private static String

Returns:

Java String value of an object
stringArg(Object
to convert
o)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

booleanValueMHback to summary
private static final MethodHandle booleanValueMH
doubleArgMHback to summary
private static final MethodHandle doubleArgMH
doubleValueMHback to summary
private static final MethodHandle doubleValueMH
intArgMHback to summary
private static final MethodHandle intArgMH
intValueMHback to summary
private static final MethodHandle intValueMH
LOOKUPback to summary
private static final MethodHandles.Lookup LOOKUP

Lookup for resolving handles throughout the class.

Oback to summary
private static final Class<?> O
stringArgMHback to summary
private static final MethodHandle stringArgMH
voidValueMHback to summary
private static final MethodHandle voidValueMH

Constructor Detail

Clinicback to summary
private Clinic()

Method Detail

adaptParameterToObjectback to summary
private static MethodHandle adaptParameterToObject(Class<?> c)

The logic of this method defines the standard for converting Python types to a specified Java type.

Parameters
c:Class<?>

Java type

Returns:MethodHandle

filter converting Python object to c.

adaptReturnToObjectback to summary
private static MethodHandle adaptReturnToObject(Class<?> c)

The logic of this method defines the standard for converting specified Java types to Python.

Parameters
c:Class<?>

Java type

Returns:MethodHandle

filter converting c to a Python object.

argumentFilterback to summary
pack-priv static MethodHandle[] argumentFilter(MethodType mt, int pos)

Create an array of filters to convert an existing method handle, with the given type, to one that expects arguments (starting at a given index) that are all Object in the converted locations. The returned array is suitable as an argument to MethodHandles.filterArguments. (Some elements may be null, meaning no adapter is applied.)

Where the existing method (described by MethodType mt) expects a primitive type, or a supported reference type (such as BigInteger), the handle to a standard conversion accepting an Object argument will be supplied. These conversions will throw a Python exception (often TypeError), when invoked on objects they cannot convert, according to the usual behaviour of Python.

Where the existing method expects some other reference type, a null conversion will be supplied. If the reference type is Object, no problem arises.

When using this filter to adapt a handle on a purported implementation of an exposed Python method, types Clinic cannot convert will remain unchanged in the MethodType of the adapted handle. Such a handle must be invoked with arguments of exactly matching static type. If (as is likely), in the invocation context, the arguments will all be statically Object, the adapted handle would lead to a Java WrongMethodTypeException.

Parameters
mt:MethodType

type to adapt.

pos:int

index in the type at which to start.

Returns:MethodHandle[]

array of filter-adaptors to expect Object.

argumentFilterback to summary
pack-priv static MethodHandle[] argumentFilter(MethodType mt)

Equivalent to argumentFilter(mt, 0)

Parameters
mt:MethodType

type to adapt.

Returns:MethodHandle[]

array of filter-adaptors to expect Object.

returnFilterback to summary
pack-priv static MethodHandle returnFilter(MethodType mt)

Return a filter that will adapt an existing method handle with the given type, to one that the returns Object or a sub-class. If not null, The handle produced is suitable as an argument to MethodHandle.filterReturnValue.

This adapter will often be a constructor for the implementation type or equivalent convenience method. If the return type of is void.class, the adapter takes no arguments and produces Py#None. .

If the return type is already Object or a sub-class, this method returns null (which is not suitable as an argument to MethodHandle.filterReturnValue). Client code must test for this.

Parameters
mt:MethodType

type to adapt.

Returns:MethodHandle

null or a filter-adapter to return Object.

stringArgback to summary
private static String stringArg(Object o) throws TypeError, Throwable
Parameters
o:Object

to convert

Returns:String

Java String value of an object

Annotations
@SuppressWarnings:unused
Exceptions
TypeError:
if not interpretable as a string
Throwable:
from o.__str__ if called