Top Description Inners Fields Constructors Methods
org.python.core

public abstract Class PyCode

extends Object
implements CraftedPyObject
Class Inheritance
All Implemented Interfaces
org.python.core.CraftedPyObject
Known Direct Subclasses
org.python.core.CPython311Code
Imports
java.lang.invoke.MethodHandles, java.util.ArrayList, .EnumSet, java.util.stream.Stream, org.python.core.Exposed.Getter, .Exposed.Member

The Python code object. A code object describes the layout of a PyFrame, and is a factory for frames of matching type.

In this implementation, while there is only one Python type code, we allow alternative implementations of it. In particular, we provide for a code object that is the result of compiling to JVM byte code, in addition to the expected support for Python byte code.

The abstract base PyCode has a need to store fewer attributes than the concrete CPython code object, where the only realisation holds a block of byte code with broadly similar needs from one version to the next. We provide get-methods matching all those of CPython, and each concrete class can override them where meaningful.

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static interface
PyCode.Layout

Interface on a store of information about the variables required by a code object and where they will be stored in the frame it creates.

pack-priv static enum
PyCode.Trait

Characteristics of a PyCode (as CPython co_flags).

pack-priv static enum
PyCode.VariableTrait

Traits characterising local variables of the frame this code object will produce.

Field Summary

Modifier and TypeField and Description
pack-priv final int
argcount

Number of positional parameters (not counting *args).

public static final int
CO_ASYNC_GENERATOR

The code object is an asynchronous generator function.

public static final int
CO_COROUTINE

The code is for a coroutine function (defined with async def).

public static final int
CO_GENERATOR

The code is for a generator function, i.e. a generator object is returned when the code object is executed..

public static final int
CO_ITERABLE_COROUTINE

The flag is used to transform generators into generator-based coroutines.

public static final int
CO_NESTED

The code is for a nested function.

public static final int
CO_NEWLOCALS

A new dict should be created for local variables.

public static final int
CO_OPTIMIZED

The code uses fast local local variables, not a map.

public static final int
CO_VARARGS

The function has a collector for excess positional arguments

private static final int
public static final int
CO_VARKEYWORDS

The function has a collector for excess keyword arguments

private static final int
pack-priv final Object[]
consts

Constant objects needed by the code.

protected static final String[]
EMPTY_STRING_ARRAY

Empty (zero-length) array of String.

pack-priv final String
filename

Source file from which compiled.

pack-priv final int
firstlineno

First source line number of this code.

pack-priv final int
flags

int bitmap of code traits compatible with CPython.

pack-priv final int
kwonlyargcount

Number of keyword-only parameters.

pack-priv final String
name

Name of function etc.

private static final String
pack-priv final String[]
names

Names referenced in the code.

pack-priv final int
posonlyargcount

Number of positional-only parameters.

pack-priv final String
qualname

Fully qualified name of function etc.

pack-priv final EnumSet<PyCode.Trait>
traits

Characteristics of this PyCode (as CPython co_flags).

public static final PyType
TYPE

The Python type code.

Constructor Summary

AccessConstructor and Description
public
PyCode(String
co_filename
filename
,
String
co_name
name
,
String
co_qualname
qualname
,
int
co_flags a bitmap of traits
flags
,
int
co_firstlineno
firstlineno
,
Object[]
co_consts
consts
,
String[]
co_names
names
,
int
co_argcount the number of positional parameters (including positional-only arguments and arguments with default values)
argcount
,
int
co_posonlyargcount the number of positional-only arguments (including arguments with default values)
posonlyargcount
,
int
co_kwonlyargcount the number of keyword-only arguments (including arguments with default values)
kwonlyargcount
)

Full constructor.

Method Summary

Modifier and TypeMethod and Description
private Object
private Object
protected static PyBytes

Returns:

v
castBytes
(Object
to check is a Python bytes
v
,
String
name of argument (for message only)
arg
)

protected static String

Returns:

v
castString
(Object
to check and cast/convert
v
,
String
the name of the argument (for error production)
argName
)

Cast a Python str to a Java String or raise a TypeError mentioning an argument name.

protected static PyTuple

Returns:

v
castTuple
(Object
to check is a Python tuple
v
,
String
name of argument (for message only)
arg
)

pack-priv PyTuple

Returns:

co_cellvars as a tuple
co_cellvars
()

Get co_cellvars as a tuple.

pack-priv PyBytes
pack-priv PyTuple

Returns:

consts as a tuple
co_consts
()

Get consts as a tuple.

pack-priv PyTuple

Returns:

co_freevars as a tuple
co_freevars
()

Get co_freevars as a tuple.

pack-priv PyBytes
pack-priv PyTuple

Returns:

names as a tuple
co_names
()

Get names as a tuple.

pack-priv int
pack-priv PyTuple

Returns:

co_varnames as a tuple
co_varnames
()

Get co_varnames as a tuple.

pack-priv abstract PyFunction<? extends PyCode>

Returns:

the function from this code
createFunction
(Interpreter
providing the module context
interpreter
,
PyDict
name space to treat as global variables
globals
,
Object[]
default positional argument values or null
defaults
,
PyDict
default keyword argument values or null
kwdefaults
,
Object
type annotations (dict, null or maybe tuple)
annotations
,
PyCell[]
variables referenced but not defined here, must be size expected by code or null if empty.
closure
)

Create a PyFunction that will execute this PyCode.

pack-priv PyFunction<? extends PyCode>

Returns:

the function
createFunction
(Interpreter
providing the module context
interpreter
,
PyDict
name space to treat as global variables
globals
)

Create a PyFunction that will execute this PyCode (adequate for module-level code).

public PyType
getType()

Implements org.python.core.CraftedPyObject.getType.

The Python type of this object.
pack-priv abstract PyCode.Layout

Returns:

a Layout object describing the variables
layout
()

Describe the layout of the frame local variables (at least the arguments), cell and free variables.

protected static String[]

Returns:

the names as String[]
names
(Object
of names
v
,
String
the name of the argument (for error production)
tupleName
)

Check that all the argument is a tuple and that all objects in it are str, and return them as an array of String.

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
pack-priv int

Returns:

total space in frame for arguments
totalargs
()

Return the total space in a frame of a code object, that must be reserved for arguments.

pack-priv static int

Returns:

total space in frame for arguments
totalargs
(int
argument count excluding collector parameters.
argcount
,
int
bit map of code traits
flags
)

From the values of co_argcount and co_flags (in practice, as they are de-marshalled), compute the total space in a frame of a code object, that must be reserved for arguments.

private static EnumSet<PyCode.Trait>
traitsFrom(int flags)

Convert a CPython-style flags specifier to traits.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

argcountback to summary
pack-priv final int argcount

Number of positional parameters (not counting *args).

Annotations
@Member:co_argcount
CO_ASYNC_GENERATORback to summary
public static final int CO_ASYNC_GENERATOR

The code object is an asynchronous generator function. When the code object is executed it returns an asynchronous generator object. See PEP 525 for more details.

CO_COROUTINEback to summary
public static final int CO_COROUTINE

The code is for a coroutine function (defined with async def). When the code object is executed it returns a coroutine object.

CO_GENERATORback to summary
public static final int CO_GENERATOR

The code is for a generator function, i.e. a generator object is returned when the code object is executed..

CO_ITERABLE_COROUTINEback to summary
public static final int CO_ITERABLE_COROUTINE

The flag is used to transform generators into generator-based coroutines. Generator objects with this flag can be used in await expression, and can yield from coroutine objects. See PEP 492 for more details.

CO_NESTEDback to summary
public static final int CO_NESTED

The code is for a nested function.

CO_NEWLOCALSback to summary
public static final int CO_NEWLOCALS

A new dict should be created for local variables.

CO_OPTIMIZEDback to summary
public static final int CO_OPTIMIZED

The code uses fast local local variables, not a map.

CO_VARARGSback to summary
public static final int CO_VARARGS

The function has a collector for excess positional arguments

CO_VARARGS_SHIFTback to summary
private static final int CO_VARARGS_SHIFT
CO_VARKEYWORDSback to summary
public static final int CO_VARKEYWORDS

The function has a collector for excess keyword arguments

CO_VARKEYWORDS_SHIFTback to summary
private static final int CO_VARKEYWORDS_SHIFT
constsback to summary
pack-priv final Object[] consts

Constant objects needed by the code. Not null.

EMPTY_STRING_ARRAYback to summary
protected static final String[] EMPTY_STRING_ARRAY

Empty (zero-length) array of String.

filenameback to summary
pack-priv final String filename

Source file from which compiled.

Annotations
@Member:co_filename
firstlinenoback to summary
pack-priv final int firstlineno

First source line number of this code.

flagsback to summary
pack-priv final int flags

int bitmap of code traits compatible with CPython.

kwonlyargcountback to summary
pack-priv final int kwonlyargcount

Number of keyword-only parameters.

Annotations
@Member:co_kwonlyargcount
nameback to summary
pack-priv final String name

Name of function etc.

Annotations
@Member:co_name
NAME_TUPLES_STRINGback to summary
private static final String NAME_TUPLES_STRING
namesback to summary
pack-priv final String[] names

Names referenced in the code. Not null.

posonlyargcountback to summary
pack-priv final int posonlyargcount

Number of positional-only parameters.

Annotations
@Member:co_posonlyargcount
qualnameback to summary
pack-priv final String qualname

Fully qualified name of function etc.

Annotations
@Member:co_qualname
traitsback to summary
pack-priv final EnumSet<PyCode.Trait> traits

Characteristics of this PyCode (as CPython co_flags).

TYPEback to summary
public static final PyType TYPE

The Python type code.

Constructor Detail

PyCodeback to summary
public PyCode(String filename, String name, String qualname, int flags, int firstlineno, Object[] consts, String[] names, int argcount, int posonlyargcount, int kwonlyargcount)

Full constructor. The traits of the code are supplied here as CPython reports them: as a bit array in an integer, but the constructor makes a conversion, and it is the traits which should be used at the Java level.

Where the parameters map directly to an attribute of the code object, that is the best way to explain them. Note that this factory method is tuned to the needs of marshal.read where the serialised form makes no secret of the version-specific implementation details.

Parameters
filename:String

co_filename

name:String

co_name

qualname:String

co_qualname

flags:int

co_flags a bitmap of traits

firstlineno:int

co_firstlineno

consts:Object[]

co_consts

names:String[]

co_names

argcount:int

co_argcount the number of positional parameters (including positional-only arguments and arguments with default values)

posonlyargcount:int

co_posonlyargcount the number of positional-only arguments (including arguments with default values)

kwonlyargcount:int

co_kwonlyargcount the number of keyword-only arguments (including arguments with default values)

Method Detail

__repr__back to summary
private Object __repr__()
Annotations
@SuppressWarnings:unused
__str__back to summary
private Object __str__()
Annotations
@SuppressWarnings:unused
castBytesback to summary
protected static PyBytes castBytes(Object v, String arg) throws TypeError
Parameters
v:Object

to check is a Python bytes

arg:String

name of argument (for message only)

Returns:PyBytes

v

Exceptions
TypeError:
if v cannot be cast to bytes
castStringback to summary
protected static String castString(Object v, String argName)

Cast a Python str to a Java String or raise a TypeError mentioning an argument name.

Parameters
v:Object

to check and cast/convert

argName:String

the name of the argument (for error production)

Returns:String

v

castTupleback to summary
protected static PyTuple castTuple(Object v, String arg)
Parameters
v:Object

to check is a Python tuple

arg:String

name of argument (for message only)

Returns:PyTuple

v

Exceptions
TypeError:
if v cannot be cast to tuple
co_cellvarsback to summary
pack-priv PyTuple co_cellvars()

Get co_cellvars as a tuple.

Returns:PyTuple

co_cellvars as a tuple

Annotations
@Getter
co_codeback to summary
pack-priv PyBytes co_code()
Annotations
@SuppressWarnings:static-method
@Getter
co_constsback to summary
pack-priv PyTuple co_consts()

Get consts as a tuple.

Returns:PyTuple

consts as a tuple

Annotations
@Getter
co_freevarsback to summary
pack-priv PyTuple co_freevars()

Get co_freevars as a tuple.

Returns:PyTuple

co_freevars as a tuple

Annotations
@Getter
co_lnotabback to summary
pack-priv PyBytes co_lnotab()
Annotations
@SuppressWarnings:static-method
@Getter
co_namesback to summary
pack-priv PyTuple co_names()

Get names as a tuple.

Returns:PyTuple

names as a tuple

Annotations
@Getter
co_stacksizeback to summary
pack-priv int co_stacksize()
Annotations
@SuppressWarnings:static-method
@Getter
co_varnamesback to summary
pack-priv PyTuple co_varnames()

Get co_varnames as a tuple.

Returns:PyTuple

co_varnames as a tuple

Annotations
@Getter
createFunctionback to summary
pack-priv abstract PyFunction<? extends PyCode> createFunction(Interpreter interpreter, PyDict globals, Object[] defaults, PyDict kwdefaults, Object annotations, PyCell[] closure)

Create a PyFunction that will execute this PyCode. The strongly-typed defaults, kwdefaults , closure and annotations may be null if they would otherwise be empty. annotations is always exposed as a dict, but may be presented to the constructor as a dict or tuple of keys and values (or null).

Parameters
interpreter:Interpreter

providing the module context

globals:PyDict

name space to treat as global variables

defaults:Object[]

default positional argument values or null

kwdefaults:PyDict

default keyword argument values or null

annotations:Object

type annotations (dict, null or maybe tuple)

closure:PyCell[]

variables referenced but not defined here, must be size expected by code or null if empty.

Returns:PyFunction<? extends PyCode>

the function from this code

createFunctionback to summary
pack-priv PyFunction<? extends PyCode> createFunction(Interpreter interpreter, PyDict globals)

Create a PyFunction that will execute this PyCode (adequate for module-level code).

Parameters
interpreter:Interpreter

providing the module context

globals:PyDict

name space to treat as global variables

Returns:PyFunction<? extends PyCode>

the function

getTypeback to summary
public PyType getType()

Implements org.python.core.CraftedPyObject.getType.

Doc from org.python.core.CraftedPyObject.getType.

The Python type of this object.

Returns:PyType

type of this object

Annotations
@Override
layoutback to summary
pack-priv abstract PyCode.Layout layout()

Describe the layout of the frame local variables (at least the arguments), cell and free variables. co_varnames, co_cellvars and co_freevars are derived from this, and the signature of the code as a function.

Returns:PyCode.Layout

a Layout object describing the variables

namesback to summary
protected static String[] names(Object v, String tupleName)

Check that all the argument is a tuple and that all objects in it are str, and return them as an array of String.

Parameters
v:Object

of names

tupleName:String

the name of the argument (for error production)

Returns:String[]

the names as String[]

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.

Annotations
@Override
totalargsback to summary
pack-priv int totalargs()

Return the total space in a frame of a code object, that must be reserved for arguments. This is also the size of the layout array appearing as an argument to constructors.

Returns:int

total space in frame for arguments

totalargsback to summary
pack-priv static int totalargs(int argcount, int flags)

From the values of co_argcount and co_flags (in practice, as they are de-marshalled), compute the total space in a frame of a code object, that must be reserved for arguments. This is also the size of the layout array appearing as an argument to certain constructors.

Parameters
argcount:int

argument count excluding collector parameters.

flags:int

bit map of code traits

Returns:int

total space in frame for arguments

traitsFromback to summary
private static EnumSet<PyCode.Trait> traitsFrom(int flags)

Convert a CPython-style flags specifier to traits.

org.python.core back to summary

pack-priv Interface PyCode.Layout

Known Direct Implementers
org.python.core.CPython311Code.CPythonLayout

Interface on a store of information about the variables required by a code object and where they will be stored in the frame it creates. It is used to initialise

Method Summary

Modifier and TypeMethod and Description
public Stream<String>

Returns:

names of cell variables (may be parameters).
cellvars
()

Return a stream of the names of variables to include in co_cellvars.

public Stream<String>

Returns:

names of free variables.
freevars
()

Return a stream of the names of variables to include in co_freevars.

public Stream<String>

Returns:

names of all local variables.
localnames
()

Return a stream of the names of all the local variables These are the parameters and then the other plain, cell and free variables, but occurring only once each (whereas co_cellvars will repeat names from co_varnames if they are parameters.

public String

Returns:

name of one variable.
name
(int
of variable
index
)

Return name of one local frame variable.

public default int

Returns:

the length of co_cellvars
ncellvars
()

public default int

Returns:

the length of co_freevars
nfreevars
()

public default int

Returns:

the length of co_varnames
nvarnames
()

public default int

Returns:

total number of local variables.
size
()

public EnumSet<PyCode.VariableTrait>

Returns:

traits of the local variable
traits
(int
of variable
index
)

Return the VariableTraits of the variable at a given index .

public Stream<String>

Returns:

names of non-cell and parameters variables.
varnames
()

Return a stream of the names of variables to include in co_varnames.

Method Detail

cellvarsback to summary
public Stream<String> cellvars()

Return a stream of the names of variables to include in co_cellvars. These are the variables defined by this code object and stored as cells. Note that some of the parameters may be cell variables.

Returns:Stream<String>

names of cell variables (may be parameters).

freevarsback to summary
public Stream<String> freevars()

Return a stream of the names of variables to include in co_freevars. These are the variables stored as cells but defined in another code object.

Returns:Stream<String>

names of free variables.

localnamesback to summary
public Stream<String> localnames()

Return a stream of the names of all the local variables These are the parameters and then the other plain, cell and free variables, but occurring only once each (whereas co_cellvars will repeat names from co_varnames if they are parameters.

Returns:Stream<String>

names of all local variables.

nameback to summary
public String name(int index)

Return name of one local frame variable.

Parameters
index:int

of variable

Returns:String

name of one variable.

ncellvarsback to summary
public default int ncellvars()
Returns:int

the length of co_cellvars

nfreevarsback to summary
public default int nfreevars()
Returns:int

the length of co_freevars

nvarnamesback to summary
public default int nvarnames()
Returns:int

the length of co_varnames

sizeback to summary
public default int size()
Returns:int

total number of local variables.

traitsback to summary
public EnumSet<PyCode.VariableTrait> traits(int index)

Return the VariableTraits of the variable at a given index .

Parameters
index:int

of variable

Returns:EnumSet<PyCode.VariableTrait>

traits of the local variable

varnamesback to summary
public Stream<String> varnames()

Return a stream of the names of variables to include in co_varnames. These are the parameters and then the plain (non-cell, non-free) variables. Note that some of the arguments may be cell variables.

Returns:Stream<String>

names of non-cell and parameters variables.

org.python.core back to summary

pack-priv final Enum PyCode.Trait

extends Enum<PyCode.Trait>
Class Inheritance

Characteristics of a PyCode (as CPython co_flags). These are not all relevant to all code types.

Field Summary

Modifier and TypeField and Description
public static final PyCode.Trait
public static final PyCode.Trait
public static final PyCode.Trait
public static final PyCode.Trait
public static final PyCode.Trait
public static final PyCode.Trait
public static final PyCode.Trait
public static final PyCode.Trait
public static final PyCode.Trait

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static PyCode.Trait
public static PyCode.Trait[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

ASYNC_GENERATORback to summary
public static final PyCode.Trait ASYNC_GENERATOR
COROUTINEback to summary
public static final PyCode.Trait COROUTINE
GENERATORback to summary
public static final PyCode.Trait GENERATOR
ITERABLE_COROUTINEback to summary
public static final PyCode.Trait ITERABLE_COROUTINE
NESTEDback to summary
public static final PyCode.Trait NESTED
NEWLOCALSback to summary
public static final PyCode.Trait NEWLOCALS
OPTIMIZEDback to summary
public static final PyCode.Trait OPTIMIZED
VARARGSback to summary
public static final PyCode.Trait VARARGS
VARKEYWORDSback to summary
public static final PyCode.Trait VARKEYWORDS

Constructor Detail

Traitback to summary
private Trait()

Method Detail

valueOfback to summary
public static PyCode.Trait valueOf(String name)
valuesback to summary
public static PyCode.Trait[] values()
org.python.core back to summary

pack-priv final Enum PyCode.VariableTrait

extends Enum<PyCode.VariableTrait>
Class Inheritance

Traits characterising local variables of the frame this code object will produce.

Field Summary

Modifier and TypeField and Description
public static final PyCode.VariableTrait
CELL

Belongs in co_cellvars.

public static final PyCode.VariableTrait
FREE

Belongs in co_freevars.

public static final PyCode.VariableTrait
PLAIN

Belongs in co_varnames.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public static PyCode.VariableTrait
public static PyCode.VariableTrait[]
Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

CELLback to summary
public static final PyCode.VariableTrait CELL

Belongs in co_cellvars. This means the non-free cell variables, even if they are also parameters to the function, in which case they have the PLAIN trait too.

FREEback to summary
public static final PyCode.VariableTrait FREE

Belongs in co_freevars. These are just the free cell variables. (They cannot also be parameters.)

PLAINback to summary
public static final PyCode.VariableTrait PLAIN

Belongs in co_varnames. For legacy reasons this means parameters to the function (even if they are also cell variables), and other local variables that are not cells (or free).

Constructor Detail

VariableTraitback to summary
private VariableTrait()

Method Detail

valueOfback to summary
public static PyCode.VariableTrait valueOf(String name)
valuesback to summary
public static PyCode.VariableTrait[] values()