Top Description Inners Fields Constructors Methods
org.python.core

public Class CPython311Code

extends PyCode
Class Inheritance
Imports
java.nio.ShortBuffer, java.util.Arrays, .EnumSet, .Spliterator, java.util.function.Consumer, java.util.stream.Stream, .StreamSupport, org.python.core.stringlib.ByteArrayBuilder
Our equivalent to the Python code object (PyCodeObject in CPython's C API).

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
CPython311Code.CPythonLayout

Store information about the variables required by a CPython311Code object and where they will be stored in the frame it creates.

Field Summary

Modifier and TypeField and Description
private static final int
CO_FAST_CELL

private static final int
CO_FAST_FREE

private static final int
CO_FAST_LOCAL

pack-priv final byte[]
exceptiontable

Table of byte code address ranges mapped to handler addresses in a compact byte encoding (defined by CPython and appearing in the serialised form of a code object).

pack-priv final CPython311Code.CPythonLayout
layout

Describe the layout of the frame local variables (including arguments), cell and free variables allowing implementation-level access to CPython-specific features.

private static final String
LENGTHS_UNEQUAL

pack-priv final byte[]
linetable

Table of byte code address ranges mapped to source lines, presentable as defined in PEP 626.

private static final String
NAME_TUPLES_STRING

Hides org.python.core.PyCode.NAME_TUPLES_STRING.

pack-priv final int
stacksize

Number of entries needed for evaluation stack.

pack-priv final short[]
wordcode

Instruction opcodes, not null.

Inherited from org.python.core.PyCode:
argcountCO_ASYNC_GENERATORCO_COROUTINECO_GENERATORCO_ITERABLE_COROUTINECO_NESTEDCO_NEWLOCALSCO_OPTIMIZEDCO_VARARGSCO_VARKEYWORDSconstsEMPTY_STRING_ARRAYfilenamefirstlinenoflagskwonlyargcountnamenamesposonlyargcountqualnametraitsTYPE

Constructor Summary

AccessConstructor and Description
public
CPython311Code(String
co_filename
filename, String
co_name
name, String
co_qualname
qualname, int
co_flags a bitmap of traits
flags, short[]
co_code as unsigned 16-bit words
wordcode, int
first source line of this code
firstlineno, byte[]
mapping byte code ranges to source lines
linetable, Object[]
co_consts
consts, String[]
co_names
names, CPython311Code.CPythonLayout
variable names and properties, in the order co_varnames + co_cellvars + co_freevars but without repetition.
layout, 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, int
co_stacksize
stacksize, byte[]
supports exception processing
exceptiontable)

Full constructor based on CPython's PyCode_NewWithPosOnlyArgs.

Method Summary

Modifier and TypeMethod and Description
pack-priv ArgParser

Returns:

parser reflecting the frame layout of this code object
buildParser()

Build an ArgParser to match the code object and given defaults.

pack-priv PyBytes
co_code()

Overrides org.python.core.PyCode.co_code.

pack-priv int
co_stacksize()

Overrides org.python.core.PyCode.co_stacksize.

public static CPython311Code

Returns:

a new code object
create(Object
(str) = co_filename
filename, Object
(str) = co_name
name, Object
(str) = co_qualname
qualname, int
(int) = @code co_flags} a bitmap of traits
flags, Object
(bytes) = co_code
bytecode, int
(int) = co_firstlineno
firstlineno, Object
(bytes) = co_linetable
linetable, Object
(tuple) = co_consts
consts, Object
(tuple[str]) = co_names
names, Object
(tuple[str]) variable names
localsplusnames, Object
(bytes) variable kinds
localspluskinds, int
(int) = co_argcount
argcount, int
(int) = co_posonlyargcount
posonlyargcount, int
(int) = co_kwonlyargcount
kwonlyargcount, int
(int) = co_stacksize
stacksize, Object
(tuple) supports exception processing
exceptiontable)

Essentially equivalent to the (strongly-typed) constructor, but accepting Object arguments, which are checked for type here.

pack-priv CPython311Function

Returns:

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

Overrides org.python.core.PyCode.createFunction.

Create a PyFunction that will execute this PyCode (adequate for module-level code).
pack-priv CPython311Function
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)

Implements abstract org.python.core.PyCode.createFunction.

Create a PyFunction that will execute this PyCode.
pack-priv CPython311Code.CPythonLayout
layout()

Implements abstract org.python.core.PyCode.layout.

Describe the layout of the frame local variables (at least the arguments), cell and free variables.
private static short[]

Returns:

16-bit word code
wordcode(PyBytes
as compiled by Python as bytes
bytecode)

Convert the contents of a Python bytes to 16-bit word code as expected by the eval-loop in CPython311Frame.

Inherited from org.python.core.PyCode:
castBytescastStringcastTupleco_cellvarsco_constsco_freevarsco_lnotabco_namesco_varnamesgetTypenamestoStringtotalargstotalargs

Field Detail

CO_FAST_CELLback to summary
private static final int CO_FAST_CELL
CO_FAST_FREEback to summary
private static final int CO_FAST_FREE
CO_FAST_LOCALback to summary
private static final int CO_FAST_LOCAL
exceptiontableback to summary
pack-priv final byte[] exceptiontable

Table of byte code address ranges mapped to handler addresses in a compact byte encoding (defined by CPython and appearing in the serialised form of a code object).

layoutback to summary
pack-priv final CPython311Code.CPythonLayout layout

Describe the layout of the frame local variables (including arguments), cell and free variables allowing implementation-level access to CPython-specific features.

LENGTHS_UNEQUALback to summary
private static final String LENGTHS_UNEQUAL
linetableback to summary
pack-priv final byte[] linetable

Table of byte code address ranges mapped to source lines, presentable as defined in PEP 626.

NAME_TUPLES_STRINGback to summary
private static final String NAME_TUPLES_STRING

Hides org.python.core.PyCode.NAME_TUPLES_STRING.

stacksizeback to summary
pack-priv final int stacksize

Number of entries needed for evaluation stack.

wordcodeback to summary
pack-priv final short[] wordcode

Instruction opcodes, not null. Treat these as unsigned 16-bit patterns in which the low 8 bits is the argument and the upper 8 bits is the opcode itself.

Constructor Detail

CPython311Codeback to summary
public CPython311Code(String filename, String name, String qualname, int flags, short[] wordcode, int firstlineno, byte[] linetable, Object[] consts, String[] names, CPython311Code.CPythonLayout layout, int argcount, int posonlyargcount, int kwonlyargcount, int stacksize, byte[] exceptiontable)

Full constructor based on CPython's PyCode_NewWithPosOnlyArgs. 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

wordcode:short[]

co_code as unsigned 16-bit words

firstlineno:int

first source line of this code

linetable:byte[]

mapping byte code ranges to source lines

consts:Object[]

co_consts

names:String[]

co_names

layout:CPython311Code.CPythonLayout

variable names and properties, in the order co_varnames + co_cellvars + co_freevars but without repetition.

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)

stacksize:int

co_stacksize

exceptiontable:byte[]

supports exception processing

Method Detail

buildParserback to summary
pack-priv ArgParser buildParser()

Build an ArgParser to match the code object and given defaults. This is a call-back when constructing a CPython311Function from this code object and also when the code object of a function is replaced. The method ensures the parser reflects the variable names and the frame layout implied by the code object. The caller (the function definition) supplies the default values of arguments on return.

Returns:ArgParser

parser reflecting the frame layout of this code object

co_codeback to summary
pack-priv PyBytes co_code()

Overrides org.python.core.PyCode.co_code.

Annotations
@Override
co_stacksizeback to summary
pack-priv int co_stacksize()

Overrides org.python.core.PyCode.co_stacksize.

Annotations
@Override
createback to summary
public static CPython311Code create(Object filename, Object name, Object qualname, int flags, Object bytecode, int firstlineno, Object linetable, Object consts, Object names, Object localsplusnames, Object localspluskinds, int argcount, int posonlyargcount, int kwonlyargcount, int stacksize, Object exceptiontable)

Essentially equivalent to the (strongly-typed) constructor, but accepting Object arguments, which are checked for type here. This is primarily designed for use by the marshal module.

The traits of the code are supplied here as CPython reports them: as a bitmap 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:Object

(str) = co_filename

name:Object

(str) = co_name

qualname:Object

(str) = co_qualname

flags:int

(int) = @code co_flags} a bitmap of traits

bytecode:Object

(bytes) = co_code

firstlineno:int

(int) = co_firstlineno

linetable:Object

(bytes) = co_linetable

consts:Object

(tuple) = co_consts

names:Object

(tuple[str]) = co_names

localsplusnames:Object

(tuple[str]) variable names

localspluskinds:Object

(bytes) variable kinds

argcount:int

(int) = co_argcount

posonlyargcount:int

(int) = co_posonlyargcount

kwonlyargcount:int

(int) = co_kwonlyargcount

stacksize:int

(int) = co_stacksize

exceptiontable:Object

(tuple) supports exception processing

Returns:CPython311Code

a new code object

createFunctionback to summary
pack-priv CPython311Function createFunction(Interpreter interpreter, PyDict globals)

Overrides org.python.core.PyCode.createFunction.

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:CPython311Function

the function

Annotations
@Override
createFunctionback to summary
pack-priv CPython311Function createFunction(Interpreter interpreter, PyDict globals, Object[] defaults, PyDict kwdefaults, Object annotations, PyCell[] closure)

Implements abstract org.python.core.PyCode.createFunction.

Doc from org.python.core.PyCode.createFunction.

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:CPython311Function

the function from this code

Annotations
@Override
layoutback to summary
pack-priv CPython311Code.CPythonLayout layout()

Implements abstract org.python.core.PyCode.layout.

Doc from org.python.core.PyCode.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:CPython311Code.CPythonLayout

a Layout object describing the variables

Annotations
@Override
wordcodeback to summary
private static short[] wordcode(PyBytes bytecode)

Convert the contents of a Python bytes to 16-bit word code as expected by the eval-loop in CPython311Frame.

Parameters
bytecode:PyBytes

as compiled by Python as bytes

Returns:short[]

16-bit word code

org.python.core back to summary

pack-priv final Class CPython311Code.CPythonLayout

extends Object
implements Layout
Class Inheritance
All Implemented Interfaces
org.python.core.PyCode.Layout
Store information about the variables required by a CPython311Code object and where they will be stored in the frame it creates.

Field Summary

Modifier and TypeField and Description
private final int
cell0

Index of first cell (which may be a parameter).

pack-priv final int
free0

Index of first free variable.

private final byte[]
kinds

Kinds of all the variables in frame order.

private final String[]
localnames

Names of all the variables in frame order.

pack-priv final int
ncellvars

Count of co_cellvars

pack-priv final int
nfreevars

Count of co_freevars

pack-priv final int
nvarnames

Count of co_varnames

Constructor Summary

AccessConstructor and Description
pack-priv
CPythonLayout(Object
tuple of all the names
localsplusnames, Object
bytes of kinds of variables
localspluskinds, int
the number (leading) that are arguments
nargs)

Construct a Layout based on a representation used internally by CPython that appears in the stream marshal writes, e.g. in a .pyc file.

Method Summary

Modifier and TypeMethod and Description
public Stream<String>
cellvars()

Implements org.python.core.PyCode.Layout.cellvars.

Return a stream of the names of variables to include in co_cellvars.
public Stream<String>
freevars()

Implements org.python.core.PyCode.Layout.freevars.

Return a stream of the names of variables to include in co_freevars.
public Stream<String>
localnames()

Implements org.python.core.PyCode.Layout.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
name(int
of variable
index)

Implements org.python.core.PyCode.Layout.name.

Return name of one local frame variable.
public int

Returns:

the length of co_cellvars
ncellvars()

Overrides default org.python.core.PyCode.Layout.ncellvars.

public int

Returns:

the length of co_freevars
nfreevars()

Overrides default org.python.core.PyCode.Layout.nfreevars.

public int
nvarnames()

Overrides default org.python.core.PyCode.Layout.nvarnames.

public int
size()

Overrides default org.python.core.PyCode.Layout.size.

private Spliterator<String>

Returns:

a spliterator of the names
spliterator(final int
single bit kind
mask, final int
how many of that kind
count, int
to start looking
start)

A Spliterator of local variable names of the kind indicated in the mask.

public EnumSet<PyCode.VariableTrait>
traits(int
of variable
index)

Implements org.python.core.PyCode.Layout.traits.

Return the VariableTraits of the variable at a given index .
public Stream<String>
varnames()

Implements org.python.core.PyCode.Layout.varnames.

Return a stream of the names of variables to include in co_varnames.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

cell0back to summary
private final int cell0

Index of first cell (which may be a parameter). Cell variables do not in general form a contiguous block in the frame.

free0back to summary
pack-priv final int free0

Index of first free variable. Free variables form a contiguous block in the frame from this index.

kindsback to summary
private final byte[] kinds

Kinds of all the variables in frame order.

localnamesback to summary
private final String[] localnames

Names of all the variables in frame order.

ncellvarsback to summary
pack-priv final int ncellvars

Count of co_cellvars

nfreevarsback to summary
pack-priv final int nfreevars

Count of co_freevars

nvarnamesback to summary
pack-priv final int nvarnames

Count of co_varnames

Constructor Detail

CPythonLayoutback to summary
pack-priv CPythonLayout(Object localsplusnames, Object localspluskinds, int nargs)

Construct a Layout based on a representation used internally by CPython that appears in the stream marshal writes, e.g. in a .pyc file.

Parameters
localsplusnames:Object

tuple of all the names

localspluskinds:Object

bytes of kinds of variables

nargs:int

the number (leading) that are arguments

Method Detail

cellvarsback to summary
public Stream<String> cellvars()

Implements org.python.core.PyCode.Layout.cellvars.

Doc from org.python.core.PyCode.Layout.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).

Annotations
@Override
freevarsback to summary
public Stream<String> freevars()

Implements org.python.core.PyCode.Layout.freevars.

Doc from org.python.core.PyCode.Layout.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.

Annotations
@Override
localnamesback to summary
public Stream<String> localnames()

Implements org.python.core.PyCode.Layout.localnames.

Doc from org.python.core.PyCode.Layout.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.

Annotations
@Override
nameback to summary
public String name(int index)

Implements org.python.core.PyCode.Layout.name.

Doc from org.python.core.PyCode.Layout.name.

Return name of one local frame variable.

Parameters
index:int

of variable

Returns:String

name of one variable.

Annotations
@Override
ncellvarsback to summary
public int ncellvars()

Overrides default org.python.core.PyCode.Layout.ncellvars.

Returns:int

the length of co_cellvars

Annotations
@Override
nfreevarsback to summary
public int nfreevars()

Overrides default org.python.core.PyCode.Layout.nfreevars.

Returns:int

the length of co_freevars

Annotations
@Override
nvarnamesback to summary
public int nvarnames()

Overrides default org.python.core.PyCode.Layout.nvarnames.

Returns:int

Doc from org.python.core.PyCode.Layout.nvarnames.

the length of co_varnames

Annotations
@Override
sizeback to summary
public int size()

Overrides default org.python.core.PyCode.Layout.size.

Returns:int

Doc from org.python.core.PyCode.Layout.size.

total number of local variables.

Annotations
@Override
spliteratorback to summary
private Spliterator<String> spliterator(final int mask, final int count, int start)

A Spliterator of local variable names of the kind indicated in the mask. The caller must specify where to start looking in the list and how many names there ought to be.

Parameters
mask:int

single bit kind

count:int

how many of that kind

start:int

to start looking

Returns:Spliterator<String>

a spliterator of the names

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

Implements org.python.core.PyCode.Layout.traits.

Doc from org.python.core.PyCode.Layout.traits.

Return the VariableTraits of the variable at a given index .

Parameters
index:int

of variable

Returns:EnumSet<PyCode.VariableTrait>

traits of the local variable

Annotations
@Override
varnamesback to summary
public Stream<String> varnames()

Implements org.python.core.PyCode.Layout.varnames.

Doc from org.python.core.PyCode.Layout.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.

Annotations
@Override