This class provides a parser for the positional and keyword arguments supplied during a call to a built-in function or method. The purpose of an argument parser is to provide the body of a function, or perhaps a MethodHandle with an array of values, corresponding in order and number to its parameters (formal arguments).

This parser transforms several argument presentations that occur in a Python implementation, and arranges them into an array. This array is either created by the parser, or designated by the caller. The parser may therefore be used to prepare arguments for a pure a Java method (or MethodHandle) that accepts an array, or to insert arguments as initial values of local variables in an an optimised interpreter frame (PyFrame).

The fields of the parser that determine the acceptable numbers of positional arguments and their names are essentially those of a code object (PyCode). Defaults are provided values that mirror the defaults built into a function object (PyFunction).

Consider for example a function that in Python would have the function definition:

def func(a, b, c=3, d=4, /, e=5, f=6, *aa, g=7, h, i=9, **kk):
    pass

This could be described by a constructor call and modifiers:

String[] names = {"a", "b", "c", "d",  "e", "f",  "g", "h", "i",
        "aa", "kk"};
ArgParser ap = new ArgParser("func", names,
        names.length - 2, 4, 3, true, true) //
                .defaults(3, 4, 5, 6) //
                .kwdefaults(7, null, 9);

Note that "aa" and "kk" are at the end of the parameter names. (This is how a CPython frame is laid out.)

Defaults are provided, after the parser has been constructed, as values corresponding to parameter names, when right-justified in the space to which they apply. (See diagram below.) Both the positional and keyword defaults are given by position in this formulation. The kwdefaults(Object...) call is allowed to supply null values at positions it does not define.

When parsed to an array, the layout of the argument values, in relation to fields of the parser will be as follows.

A Python `frame`
names	a	b	c	d	e	f	g	h	i	aa	kk
layout	posOnly						kwOnly
			defaults				kwdefaults

The most readable way of specifying a parser (although one that is a little costly to construct) is to list the parameters as they would be declared in Python, including the furniture that marks up the positional-only, keyword-only, positional varargs, and keyword varargs. This is the API offered by fromSignature(String, String...). In practice we only use this in unit tests. For serious applications we construct the ArgParser with a complex of arguments derived by inspection of the Java or Python signature.

Nested and Inner Type Summary

Modifier and Type	Class and Description
pack-priv class	ArgParser.ArrayFrameWrapper Wrap an array provided by a client so that the enclosing argument parser may fill it from the arguments to a Python call.
pack-priv abstract class	ArgParser.FrameWrapper Abstract wrapper for storage that the enclosing argument parser should be able to fill from the arguments to a Python call.

Field Summary

Modifier and Type	Field and Description
pack-priv final int	argcount The number of positional parameters.
pack-priv final String[]	argnames Names of parameters that could be satisfied by position or keyword, including the collector parameters.
private Object[]	defaults The (positional) default parameters or `null` if there are none.
pack-priv String	doc The documentation string of the method.
private Map<Object, Object>	kwdefaults The keyword defaults, may be a `dict` or `null` if there are none.
pack-priv final int	kwonlyargcount The number of keyword-only parameters.
pack-priv final MethodKind	methodKind The kind of method (instance, static or class) that this parser works for.
pack-priv final String	name The name of the function, mainly for error messages.
private static final Object[]	NO_OBJECTS Empty object array.
private static final String[]	NO_STRINGS Empty names array.
pack-priv final int	posonlyargcount The number of parameters that can only be satisfied by arguments given by position.
pack-priv final int	regargcount The number of positional or keyword parameters, excluding the "collector" (`args` and `*kwargs`) parameters, and any data that may follow the legitimate parameter names.
pack-priv final ScopeKind	scopeKind The kind of object (type or module) in which the method is found.
private static final String	TOO_MANY_DEFAULTS
private static final String	TOO_MANY_KWDEFAULTS
pack-priv final int	varArgsIndex The frame has a collector (`tuple`) for excess positional arguments at this index, if it is `>=0`.
pack-priv final int	varKeywordsIndex The frame has a collector (`dict`) for excess keyword arguments at this index, if it is `>=0`.

Constructor Summary

Access Constructor and Description

Access	Constructor and Description
pack-priv	ArgParser(String of the function name, String[] of the parameters including any collectors (varargs) names, int number of regular (non-collector) parameters regargcount, int number of positional-only parameters posOnly, int number of keyword-only parameters kwOnly, boolean whether there is positional collector varargs, boolean whether there is a keywords collector varkw) Construct a parser for a named function, with defined numbers of positional-only and keyword-only parameters, and parameter names in an array prepared by client code.
pack-priv	ArgParser(String of the function name, ScopeKind whether module, etc. scopeKind, MethodKind whether static, etc. methodKind, String[] of the parameters including any collectors (varargs) names, int number of regular (non-collector) parameters regargcount, int number of positional-only parameters posOnly, int number of keyword-only parameters kwOnly, boolean whether there is positional collector varargs, boolean whether there is a keywords collector varkw) Construct a parser from descriptive parameters that may be derived from a the annotated declarations (`Exposed` methods) that appear in type and module definitions written in Java.

pack-priv

ArgParser(String

of the function

name, String[]

of the parameters including any collectors (varargs)

names, int

number of regular (non-collector) parameters

regargcount, int

number of positional-only parameters

posOnly, int

number of keyword-only parameters

kwOnly, boolean

whether there is positional collector

varargs, boolean

whether there is a keywords collector

varkw)

Construct a parser for a named function, with defined numbers of positional-only and keyword-only parameters, and parameter names in an array prepared by client code.

pack-priv

ArgParser(String

of the function

name, ScopeKind

whether module, etc.

scopeKind, MethodKind

whether static, etc.

methodKind, String[]

of the parameters including any collectors (varargs)

names, int

number of regular (non-collector) parameters

regargcount, int

number of positional-only parameters

posOnly, int

number of keyword-only parameters

kwOnly, boolean

whether there is positional collector

varargs, boolean

whether there is a keywords collector

varkw)

Construct a parser from descriptive parameters that may be derived from a the annotated declarations (Exposed methods) that appear in type and module definitions written in Java.

Method Summary

Modifier and Type	Method and Description
private void	checkShape() The number of keyword-only parameters and positional-only parameters must not together exceed the number of parameters named in the constructor.
pack-priv ArgParser	Returns: `this` defaults(Object... replacement positional defaults (or `null`) values) Provide the positional defaults.
pack-priv static ArgParser	Returns: the constructed parser fromSignature(String of function name, String... names of parameters and indicators "/", "", "*" decl) Create a parser, for a named function, with defined numbers of positional-only and keyword-only parameters, and naming the parameters.
pack-priv Object[]	Returns: a copy of default positional arguments (or empty array). getDefaults()
pack-priv boolean	Returns: true if default positional arguments are available. hasDefaults()
pack-priv boolean	Returns: true if default keyword-only arguments are available. hasKwdefaults()
pack-priv boolean	Returns: true if there is an excess positional argument collector. hasVarArgs()
pack-priv boolean	Returns: true if there is an excess keyword argument collector. hasVarKeywords()
pack-priv ArgParser	Returns: `this` kwdefaults(Object... keyword values aligned to the parameter names values) Provide the keyword-only defaults as values.
pack-priv ArgParser	Returns: `this` kwdefaults(Map<Object, Object> replacement keyword defaults (or `null`) kwd) Provide the keyword-only defaults, perhaps as a `dict`.
private String	nameArg(int i) Get the name of arg i or make one up.
private String	parameterToString(int i, int d) Return ith positional parameter name and default value if available.
private String	parameterToString(int i) Return ith parameter name and keyword default value if available.
pack-priv Object[]	Returns: array of parsed arguments parse(Object[] all arguments, positional then keyword args, String[] of keyword arguments names) Parse `__call__` arguments and create an array, using the arguments supplied and the defaults held in the parser.
pack-priv Object[]	Returns: array of parsed arguments parse(Object[] positional and keyword arguments s, int position of arguments in the array p, int number of positional and keyword arguments n, String[] of keyword arguments or `null` names) Parse CPython-style vector call arguments and create an array, using the arguments supplied and the defaults held in the parser.
pack-priv Object[]	Returns: array of parsed arguments parse(PyTuple positional arguments args, PyDict keyword arguments kwargs) Parse classic arguments and create an array, using the arguments supplied and the defaults held in the parser.
pack-priv void	parseToFrame(ArgParser.FrameWrapper to populate with argument values frame, PyTuple positional arguments given args, PyDict keyword arguments given kwargs) Parse when an args tuple and keyword dictionary are supplied, that is, for a classic call.
pack-priv void	parseToFrame(ArgParser.FrameWrapper to populate with argument values frame, Object[] array containing all arguments stack, int of the slice in the stack start, int number of arguments in the slice, whether position or keyword nargs, String[] (implying number) of keyword arguments kwnames) Parse when an args array and keyword array are supplied, that is, for a vector call on a stack slice.
pack-priv void	parseToFrame(ArgParser.FrameWrapper to populate with argument values frame, Object[] all arguments, positional then keyword args, String[] of keyword arguments (or `null`) kwnames) Parse when an args array and keyword array are supplied, that is, for a standard `__call__`.
private static String	Returns: poorman's `repr(o)` repr(Object object to reproduce o) Weak substitute for `repr()` that will do for common types of default argument.
pack-priv String	Returns: the signature of the arguments textSignature() Return a string representing the argument list of the method.
public String	toString() Overrides java.lang.Object.toString. The representation of an `ArgParser` is based on the `__text_signature__` attribute of built-in methods (see `textSignature()`) and the specifications found in CPython Argument Clinic.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

argcount	back to summary
pack-priv final int argcount The number of positional parameters.

argnames back to summary

argnames	back to summary
pack-priv final String[] argnames Names of parameters that could be satisfied by position or keyword, including the collector parameters. Elements are guaranteed to be interned, and not `null` or empty. The array must name all the parameters, of which there are: `argcount + kwonlyargcount + (hasVarArgs() ? 1 : 0) + (hasVarKeywords() ? 1 : 0)` It is often is longer since it suits us to re-use an array that names all the local variables of a frame.

pack-priv final String[] argnames

Names of parameters that could be satisfied by position or keyword, including the collector parameters. Elements are guaranteed to be interned, and not null or empty. The array must name all the parameters, of which there are: argcount + kwonlyargcount + (hasVarArgs() ? 1 : 0) + (hasVarKeywords() ? 1 : 0)

It is often is longer since it suits us to re-use an array that names all the local variables of a frame.

defaults	back to summary
private Object[] defaults The (positional) default parameters or `null` if there are none.

doc	back to summary
pack-priv String doc The documentation string of the method.

kwdefaults	back to summary
private Map<Object, Object> kwdefaults The keyword defaults, may be a `dict` or `null` if there are none.

kwonlyargcount	back to summary
pack-priv final int kwonlyargcount The number of keyword-only parameters.

methodKind	back to summary
pack-priv final MethodKind methodKind The kind of method (instance, static or class) that this parser works for.

name	back to summary
pack-priv final String name The name of the function, mainly for error messages.

NO_OBJECTS	back to summary
private static final Object[] NO_OBJECTS Empty object array.

NO_STRINGS	back to summary
private static final String[] NO_STRINGS Empty names array.

posonlyargcount	back to summary
pack-priv final int posonlyargcount The number of parameters that can only be satisfied by arguments given by position. This differs from `argcount` by excluding parameters that may be given by keyword or position.

regargcount	back to summary
pack-priv final int regargcount The number of positional or keyword parameters, excluding the "collector" (`args` and `*kwargs`) parameters, and any data that may follow the legitimate parameter names. Equal to `argcount + kwonlyargcount`.

scopeKind	back to summary
pack-priv final ScopeKind scopeKind The kind of object (type or module) in which the method is found. This makes a difference to the signature reported for an instance method.

TOO_MANY_DEFAULTS	back to summary
private static final String TOO_MANY_DEFAULTS

TOO_MANY_KWDEFAULTS	back to summary
private static final String TOO_MANY_KWDEFAULTS

varArgsIndex	back to summary
pack-priv final int varArgsIndex The frame has a collector (`tuple`) for excess positional arguments at this index, if it is `>=0`.

varKeywordsIndex	back to summary
pack-priv final int varKeywordsIndex The frame has a collector (`dict`) for excess keyword arguments at this index, if it is `>=0`.

Constructor Detail

ArgParser back to summary

ArgParser	back to summary
pack-priv ArgParser(String name, String[] names, int regargcount, int posOnly, int kwOnly, boolean varargs, boolean varkw) Construct a parser for a named function, with defined numbers of positional-only and keyword-only parameters, and parameter names in an array prepared by client code. The array of names is used in-place (not copied). The client code must therefore ensure that it cannot be modified after the parser has been constructed. The array of names may be longer than is necessary: the caller specifies how much of the array should be treated as regular parameter names, and whether zero, one or two further elements will name collectors for excess positional or keyword arguments. The rest of the elements will not be examined by the parser. The motivation for this design is to permit efficient construction when the the array of names is the local variable names in a Python `code` object. Parameters name:String of the function names:String[] of the parameters including any collectors (varargs) regargcount:int number of regular (non-collector) parameters posOnly:int number of positional-only parameters kwOnly:int number of keyword-only parameters varargs:boolean whether there is positional collector varkw:boolean whether there is a keywords collector

pack-priv ArgParser(String name, String[] names, int regargcount, int posOnly, int kwOnly, boolean varargs, boolean varkw)

Construct a parser for a named function, with defined numbers of positional-only and keyword-only parameters, and parameter names in an array prepared by client code.

The array of names is used in-place (not copied). The client code must therefore ensure that it cannot be modified after the parser has been constructed.

The array of names may be longer than is necessary: the caller specifies how much of the array should be treated as regular parameter names, and whether zero, one or two further elements will name collectors for excess positional or keyword arguments. The rest of the elements will not be examined by the parser. The motivation for this design is to permit efficient construction when the the array of names is the local variable names in a Python code object.

Parameters

name:String: of the function
names:String[]: of the parameters including any collectors (varargs)
regargcount:int: number of regular (non-collector) parameters
posOnly:int: number of positional-only parameters
kwOnly:int: number of keyword-only parameters
varargs:boolean: whether there is positional collector
varkw:boolean: whether there is a keywords collector

ArgParser back to summary

pack-priv ArgParser(String name, ScopeKind scopeKind, MethodKind methodKind, String[] names, int regargcount, int posOnly, int kwOnly, boolean varargs, boolean varkw)

Construct a parser from descriptive parameters that may be derived from a the annotated declarations (Exposed methods) that appear in type and module definitions written in Java. For;

def func(a, b, c=3, d=4, /, e=5, f=6, *aa, g=7, h, i=9, **kk):
    pass

The constructor arguments should specify this layout:

A Python `frame`
names	a	b	c	d	e	f	g	h	i	aa	kk
layout	posOnly						kwOnly			varargs	varkw
			defaults				kwdefaults

Parameters

name:String: of the function
scopeKind:ScopeKind: whether module, etc.
methodKind:MethodKind: whether static, etc.
names:String[]: of the parameters including any collectors (varargs)
regargcount:int: number of regular (non-collector) parameters
posOnly:int: number of positional-only parameters
kwOnly:int: number of keyword-only parameters
varargs:boolean: whether there is positional collector
varkw:boolean: whether there is a keywords collector

Method Detail

checkShape	back to summary
private void checkShape() The number of keyword-only parameters and positional-only parameters must not together exceed the number of parameters named in the constructor. (The last two are defined in the constructor.) Nor must there be excess default values for the number of parameters.

defaults back to summary

defaults	back to summary
pack-priv ArgParser defaults(Object... values) Provide the positional defaults. * The `ArgParser` keeps a reference to this array, so that subsequent changes to it will affect argument parsing. (Concurrent access to the array and parser is a client issue.) If L values are provided, they correspond to `arg[max-L] ... arg[max-1]`, where `max` is the index of the first keyword-only parameter, or the number of parameters if there are no keyword-only parameters. The minimum number of positional arguments will then be `max-L`. Parameters values:Object[] replacement positional defaults (or `null`) Returns:ArgParser `this`

pack-priv ArgParser defaults(Object... values)

Provide the positional defaults. * The ArgParser keeps a reference to this array, so that subsequent changes to it will affect argument parsing. (Concurrent access to the array and parser is a client issue.)

If L values are provided, they correspond to arg[max-L] ... arg[max-1], where max is the index of the first keyword-only parameter, or the number of parameters if there are no keyword-only parameters. The minimum number of positional arguments will then be max-L.

Parameters

values:Object[]: replacement positional defaults (or null)

Returns:ArgParser

this

fromSignature	back to summary
pack-priv static ArgParser fromSignature(String name, String... decl) Create a parser, for a named function, with defined numbers of positional-only and keyword-only parameters, and naming the parameters. Parameters that may only be given by position need not be named. ("" is acceptable in the names array.) This is a convenient way to construct a reference result in unit tests. Parameters name:String of function decl:String[] names of parameters and indicators "/", "", "*" Returns:ArgParser the constructed parser

fromSignature

back to summary

pack-priv static ArgParser fromSignature(String name, String... decl)

Create a parser, for a named function, with defined numbers of positional-only and keyword-only parameters, and naming the parameters. Parameters that may only be given by position need not be named. ("" is acceptable in the names array.)

This is a convenient way to construct a reference result in unit tests.

Parameters

name:String: of function
decl:String[]: names of parameters and indicators "/", "*", "**"

Returns:ArgParser

the constructed parser

getDefaults	back to summary
pack-priv Object[] getDefaults() Returns:Object[] a copy of default positional arguments (or empty array).

hasDefaults	back to summary
pack-priv boolean hasDefaults() Returns:boolean true if default positional arguments are available.

hasKwdefaults	back to summary
pack-priv boolean hasKwdefaults() Returns:boolean true if default keyword-only arguments are available.

hasVarArgs	back to summary
pack-priv boolean hasVarArgs() Returns:boolean true if there is an excess positional argument collector.

hasVarKeywords	back to summary
pack-priv boolean hasVarKeywords() Returns:boolean true if there is an excess keyword argument collector.

kwdefaults back to summary

kwdefaults	back to summary
pack-priv ArgParser kwdefaults(Object... values) Provide the keyword-only defaults as values. If K values are provided, they correspond to `arg[N-K] ... arg[N-1]`, where `N` is the number of regular parameters (`regargcount`). If the argument is empty, it is converted to `null` internally. The number of keyword-only parameters and positional-only parameters must not together exceed the number of regular parameters named in the constructor. Parameters values:Object[] keyword values aligned to the parameter names Returns:ArgParser `this`

pack-priv ArgParser kwdefaults(Object... values)

Provide the keyword-only defaults as values. If K values are provided, they correspond to arg[N-K] ... arg[N-1], where N is the number of regular parameters (regargcount). If the argument is empty, it is converted to null internally. The number of keyword-only parameters and positional-only parameters must not together exceed the number of regular parameters named in the constructor.

Parameters

values:Object[]: keyword values aligned to the parameter names

Returns:ArgParser

this

kwdefaults back to summary

kwdefaults	back to summary
pack-priv ArgParser kwdefaults(Map<Object, Object> kwd) Provide the keyword-only defaults, perhaps as a `dict`. The `ArgParser` keeps a reference to this map, so that subsequent changes to it will affect argument parsing, as required for a Python `function`. (Concurrent access to the mapping and parser is a client issue.) Parameters kwd:Map<Object, Object> replacement keyword defaults (or `null`) Returns:ArgParser `this`

pack-priv ArgParser kwdefaults(Map<Object, Object> kwd)

Provide the keyword-only defaults, perhaps as a dict. The ArgParser keeps a reference to this map, so that subsequent changes to it will affect argument parsing, as required for a Python function. (Concurrent access to the mapping and parser is a client issue.)

Parameters

kwd:Map<Object, Object>: replacement keyword defaults (or null)

Returns:ArgParser

this

nameArg	back to summary
private String nameArg(int i) Get the name of arg i or make one up.

parameterToString	back to summary
private String parameterToString(int i, int d) Return ith positional parameter name and default value if available. Helper to `sigString()`.

parameterToString	back to summary
private String parameterToString(int i) Return ith parameter name and keyword default value if available. Helper to `sigString()`.

parse back to summary

parse	back to summary
pack-priv Object[] parse(Object[] args, String[] names) Parse `__call__` arguments and create an array, using the arguments supplied and the defaults held in the parser. Parameters args:Object[] all arguments, positional then keyword names:String[] of keyword arguments Returns:Object[] array of parsed arguments

pack-priv Object[] parse(Object[] args, String[] names)

Parse __call__ arguments and create an array, using the arguments supplied and the defaults held in the parser.

Parameters

args:Object[]: all arguments, positional then keyword
names:String[]: of keyword arguments

Returns:Object[]

array of parsed arguments

parse back to summary

parse	back to summary
pack-priv Object[] parse(Object[] s, int p, int n, String[] names) Parse CPython-style vector call arguments and create an array, using the arguments supplied and the defaults held in the parser. Parameters s:Object[] positional and keyword arguments p:int position of arguments in the array n:int number of positional and keyword arguments names:String[] of keyword arguments or `null` Returns:Object[] array of parsed arguments

pack-priv Object[] parse(Object[] s, int p, int n, String[] names)

Parse CPython-style vector call arguments and create an array, using the arguments supplied and the defaults held in the parser.

Parameters

s:Object[]: positional and keyword arguments
p:int: position of arguments in the array
n:int: number of positional and keyword arguments
names:String[]: of keyword arguments or null

Returns:Object[]

array of parsed arguments

parse	back to summary
pack-priv Object[] parse(PyTuple args, PyDict kwargs) Parse classic arguments and create an array, using the arguments supplied and the defaults held in the parser. Parameters args:PyTuple positional arguments kwargs:PyDict keyword arguments Returns:Object[] array of parsed arguments

parse

back to summary

pack-priv Object[] parse(PyTuple args, PyDict kwargs)

Parse classic arguments and create an array, using the arguments supplied and the defaults held in the parser.

Parameters

args:PyTuple: positional arguments
kwargs:PyDict: keyword arguments

Returns:Object[]

array of parsed arguments

parseToFrame	back to summary
pack-priv void parseToFrame(ArgParser.FrameWrapper frame, PyTuple args, PyDict kwargs) Parse when an args tuple and keyword dictionary are supplied, that is, for a classic call. Parameters frame:ArgParser.FrameWrapper to populate with argument values args:PyTuple positional arguments given kwargs:PyDict keyword arguments given

parseToFrame

back to summary

pack-priv void parseToFrame(ArgParser.FrameWrapper frame, PyTuple args, PyDict kwargs)

Parse when an args tuple and keyword dictionary are supplied, that is, for a classic call.

Parameters

frame:ArgParser.FrameWrapper: to populate with argument values
args:PyTuple: positional arguments given
kwargs:PyDict: keyword arguments given

parseToFrame	back to summary
pack-priv void parseToFrame(ArgParser.FrameWrapper frame, Object[] stack, int start, int nargs, String[] kwnames) Parse when an args array and keyword array are supplied, that is, for a vector call on a stack slice. Parameters frame:ArgParser.FrameWrapper to populate with argument values stack:Object[] array containing all arguments start:int of the slice in the stack nargs:int number of arguments in the slice, whether position or keyword kwnames:String[] (implying number) of keyword arguments

parseToFrame

back to summary

pack-priv void parseToFrame(ArgParser.FrameWrapper frame, Object[] stack, int start, int nargs, String[] kwnames)

Parse when an args array and keyword array are supplied, that is, for a vector call on a stack slice.

Parameters

frame:ArgParser.FrameWrapper: to populate with argument values
stack:Object[]: array containing all arguments
start:int: of the slice in the stack
nargs:int: number of arguments in the slice, whether position or keyword
kwnames:String[]: (implying number) of keyword arguments

parseToFrame back to summary

parseToFrame	back to summary
pack-priv void parseToFrame(ArgParser.FrameWrapper frame, Object[] args, String[] kwnames) Parse when an args array and keyword array are supplied, that is, for a standard `__call__`. Parameters frame:ArgParser.FrameWrapper to populate with argument values args:Object[] all arguments, positional then keyword kwnames:String[] of keyword arguments (or `null`)

pack-priv void parseToFrame(ArgParser.FrameWrapper frame, Object[] args, String[] kwnames)

Parse when an args array and keyword array are supplied, that is, for a standard __call__.

Parameters

frame:ArgParser.FrameWrapper: to populate with argument values
args:Object[]: all arguments, positional then keyword
kwnames:String[]: of keyword arguments (or null)

repr back to summary

repr	back to summary
private static String repr(Object o) Weak substitute for `repr()` that will do for common types of default argument. Parameters o:Object object to reproduce Returns:String poorman's `repr(o)`

private static String repr(Object o)

Weak substitute for repr() that will do for common types of default argument.

Parameters

o:Object: object to reproduce

Returns:String

poorman's repr(o)

textSignature back to summary

textSignature	back to summary
pack-priv String textSignature() Return a string representing the argument list of the method. The string is like that found in the `__text_signature__` attribute of built-in methods. Returns:String the signature of the arguments

pack-priv String textSignature()

Return a string representing the argument list of the method. The string is like that found in the __text_signature__ attribute of built-in methods.

Returns:String: the signature of the arguments

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. The representation of an `ArgParser` is based on the `__text_signature__` attribute of built-in methods (see `textSignature()`) and the specifications found in CPython Argument Clinic. Returns:String Doc from java.lang.Object.toString. a string representation of the object. Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

The representation of an ArgParser is based on the __text_signature__ attribute of built-in methods (see textSignature()) and the specifications found in CPython Argument Clinic.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations

@Override

org.python.core back to summary

pack-priv Class ArgParser.ArrayFrameWrapper

Class Inheritance

extends FrameWrapper

java.lang.Object
org.python.core.ArgParser.FrameWrapper
org.python.core.ArgParser.ArrayFrameWrapper

Wrap an array provided by a client so that the enclosing argument parser may fill it from the arguments to a Python call. This array could be the local variables in the frame of a function being called, or an argument in the call of a method handle that accepts its arguments as an array. See: ArgParser#parseToFrame(FrameWrapper, PyTuple, PyDict).

Field Summary

Modifier and Type	Field and Description
pack-priv final int	start
private final Object[]	vars

Inherited from org.python.core.ArgParser.FrameWrapper:: KEYWORD_NOT_COMPARABLE KEYWORD_NOT_STRING MULTIPLE_VALUES POSITIONAL_ONLY UNEXPECTED_KEYWORD

Constructor Summary

Access	Constructor and Description
pack-priv	ArrayFrameWrapper(Object[] destination array vars, int at which to place first parsed argument start) Wrap a slice of an existing array.
pack-priv	ArrayFrameWrapper(Object[] destination array vars) Wrap an existing array.

Method Summary

Modifier and Type	Method and Description
pack-priv Object	getLocal(int index of variable name in `argnames` i) Implements abstract org.python.core.ArgParser.FrameWrapper.getLocal. Get the local variable named by `argnames[i]`
pack-priv void	setLocal(int index of variable name in `argnames` i, Object to assign to variable named `argnames[i]` v) Implements abstract org.python.core.ArgParser.FrameWrapper.setLocal. Set the local variable named by `argnames[i]`
pack-priv void	setPositionalArguments(PyTuple positional arguments argsTuple) Overrides org.python.core.ArgParser.FrameWrapper.setPositionalArguments. Copy positional arguments into local variables, making sure we don't copy more than have been allowed for in the frame.
pack-priv void	setPositionalArguments(Object[] positional and keyword arguments stack, int position of arguments in the array pos, int number of positional arguments nargs) Overrides org.python.core.ArgParser.FrameWrapper.setPositionalArguments. Copy positional arguments into local variables, making sure we don't copy more than have been allowed for in the frame.

Inherited from org.python.core.ArgParser.FrameWrapper:: applyDefaults applyKWDefaults missingArguments setKeywordArguments setKeywordArguments tooManyPositional unexpectedKeyword

Field Detail

start	back to summary
pack-priv final int start

vars	back to summary
private final Object[] vars

Constructor Detail

ArrayFrameWrapper back to summary

pack-priv ArrayFrameWrapper(Object[] vars, int start)

Wrap a slice of an existing array. The elements to fill are a slice of the destination array with specified starting index. The intended use is that start = 1 allows space for a self reference not in the argument list. The capacity of the array, between the start index and the end, must be sufficient to hold the parse result may be larger, e.g. to accommodate other local variables.

Parameters

vars:Object[]: destination array
start:int: at which to place first parsed argument

ArrayFrameWrapper

back to summary

pack-priv ArrayFrameWrapper(Object[] vars)

Wrap an existing array. The capacity of the array must be sufficient to hold the parse result.

Parameters

vars:Object[]: destination array

Method Detail

getLocal back to summary

pack-priv Object getLocal(int i)

Implements abstract org.python.core.ArgParser.FrameWrapper.getLocal.

Doc from org.python.core.ArgParser.FrameWrapper.getLocal.

Get the local variable named by argnames[i]

Parameters

i:int: index of variable name in argnames

Returns:Object

value of variable named argnames[i]

Annotations

@Override

setLocal back to summary

pack-priv void setLocal(int i, Object v)

Implements abstract org.python.core.ArgParser.FrameWrapper.setLocal.

Doc from org.python.core.ArgParser.FrameWrapper.setLocal.

Set the local variable named by argnames[i]

Parameters

i:int: index of variable name in argnames
v:Object: to assign to variable named argnames[i]

Annotations

@Override

setPositionalArguments

back to summary

pack-priv void setPositionalArguments(PyTuple argsTuple)

Overrides org.python.core.ArgParser.FrameWrapper.setPositionalArguments.

Doc from org.python.core.ArgParser.FrameWrapper.setPositionalArguments.

Copy positional arguments into local variables, making sure we don't copy more than have been allowed for in the frame. Providing too many or too few is not an error at this stage, as there may be a collector to catch the excess arguments or positional or keyword defaults to make up the shortfall.

Parameters

argsTuple:PyTuple: positional arguments

Annotations

@Override

setPositionalArguments

back to summary

pack-priv void setPositionalArguments(Object[] stack, int pos, int nargs)

Overrides org.python.core.ArgParser.FrameWrapper.setPositionalArguments.

Doc from org.python.core.ArgParser.FrameWrapper.setPositionalArguments.

Parameters

stack:Object[]: positional and keyword arguments
pos:int: position of arguments in the array
nargs:int: number of positional arguments

Annotations

@Override

org.python.core back to summary

pack-priv abstract Class ArgParser.FrameWrapper

Class Inheritance

extends Object

java.lang.Object
org.python.core.ArgParser.FrameWrapper

Known Direct Subclasses

org.python.core.ArgParser.ArrayFrameWrapper

Abstract wrapper for storage that the enclosing argument parser should be able to fill from the arguments to a Python call. Typically this wrapper is a window onto the local variables of a function invocation (a PyFrame) that the run-time is in the process of initialising during a call.

Field Summary

Modifier and Type	Field and Description
pack-priv static final String	KEYWORD_NOT_COMPARABLE
pack-priv static final String	KEYWORD_NOT_STRING
pack-priv static final String	MULTIPLE_VALUES
pack-priv static final String	POSITIONAL_ONLY
pack-priv static final String	UNEXPECTED_KEYWORD

Constructor Summary

Access	Constructor and Description
pack-priv	FrameWrapper()

Method Summary

Modifier and Type	Method and Description
pack-priv void	applyDefaults(int number of positional arguments given in call nargs, Object[] default values by position or `null` defs) Fill in missing positional parameters from a from `defs`.
pack-priv void	applyKWDefaults(Map<Object, Object> default values by keyword or `null` kwdefs) Deal with missing keyword arguments, attempting to fill them from `kwdefs`.
private int	Returns: index of `name` in `argnames` or -1 argnamesIndexOf(Object parameter name given as keyword name) Find the given name in `argnames`, and if it is not found, return -1.
pack-priv abstract Object	Returns: value of variable named `argnames[i]` getLocal(int index of variable name in `argnames` i) Get the local variable named by `argnames[i]`
protected TypeError	Returns: TypeError listing names of the missing arguments missingArguments(int number of missing arguments missing, int number of positional defaults available (or -1) defcount) Diagnose which positional or keywords arguments are missing, and throw `TypeError` listing them.
private TypeError	missingNamesTypeError(String kind, ArrayList<String> names) Compose a `TypeError` from the missing argument names.
pack-priv void	setKeywordArguments(PyDict keyword arguments given in call kwargs) For each of the names used as keywords in the call, match it with an allowable parameter name, and assign that frame-local variable the keyword argument given in the call.
pack-priv void	setKeywordArguments(Object[] `[kwstart:kwstart+len(kwnames)]` values corresponding to `kwnames` in order stack, int start position in `kwvalues` kwstart, String[] keywords used in the call (or `**kwargs`) kwnames) For each of the names used as keywords in the call, match it with an allowable parameter name, and assign that frame-local variable the keyword argument given in the call.
pack-priv abstract void	setLocal(int index of variable name in `argnames` i, Object to assign to variable named `argnames[i]` v) Set the local variable named by `argnames[i]`
pack-priv void	setPositionalArguments(PyTuple positional arguments args) Copy positional arguments into local variables, making sure we don't copy more than have been allowed for in the frame.
pack-priv void	setPositionalArguments(Object[] positional and keyword arguments stack, int position of arguments in the array pos, int number of positional arguments nargs) Copy positional arguments into local variables, making sure we don't copy more than have been allowed for in the frame.
protected TypeError	tooManyPositional(int posGiven)
protected < type of element in keyword collection K> TypeError	Returns: TypeError diagnosing the problem unexpectedKeyword(Object the unexpected keyword encountered in the call kw, Collection<? extends K> all the keywords used in the call kwnames) Diagnose an unexpected keyword occurring in a call and represent the problem as an exception.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

KEYWORD_NOT_COMPARABLE	back to summary
pack-priv static final String KEYWORD_NOT_COMPARABLE

KEYWORD_NOT_STRING	back to summary
pack-priv static final String KEYWORD_NOT_STRING

MULTIPLE_VALUES	back to summary
pack-priv static final String MULTIPLE_VALUES

POSITIONAL_ONLY	back to summary
pack-priv static final String POSITIONAL_ONLY

UNEXPECTED_KEYWORD	back to summary
pack-priv static final String UNEXPECTED_KEYWORD

Constructor Detail

FrameWrapper	back to summary
pack-priv FrameWrapper()

Method Detail

applyDefaults back to summary

pack-priv void applyDefaults(int nargs, Object[] defs) throws TypeError

Fill in missing positional parameters from a from defs. If any positional parameters are cannot be filled, this is an error. The number of positional arguments nargs is provided so we know where to start only for their number.

It is harmless (but a waste) to call this when nargs >= argcount.

Parameters

nargs:int: number of positional arguments given in call
defs:Object[]: default values by position or null

Exceptions

TypeError:: if there are still missing arguments.

applyKWDefaults back to summary

pack-priv void applyKWDefaults(Map<Object, Object> kwdefs) throws TypeError

Deal with missing keyword arguments, attempting to fill them from kwdefs. If any parameters are unfilled after that, this is an error. It is harmless (but a waste) to call this when kwonlyargcount == 0.

Parameters

kwdefs:Map<Object, Object>: default values by keyword or null

Exceptions

TypeError:: if there are too many or missing arguments.

argnamesIndexOf back to summary

private int argnamesIndexOf(Object name)

Find the given name in argnames, and if it is not found, return -1. Only the "allowable parameter names", those acceptable as keyword arguments, are searched. It is an error if the name is not a Python str.

Parameters

name:Object: parameter name given as keyword

Returns:int

index of name in argnames or -1

getLocal back to summary

pack-priv abstract Object getLocal(int i)

Get the local variable named by argnames[i]

Parameters

i:int: index of variable name in argnames

Returns:Object

value of variable named argnames[i]

missingArguments back to summary

protected TypeError missingArguments(int missing, int defcount)

Diagnose which positional or keywords arguments are missing, and throw TypeError listing them. We call this when we have already detected a problem, and the process is one of going over the data again to create an accurate message.

Parameters

missing:int: number of missing arguments
defcount:int: number of positional defaults available (or -1)

Returns:TypeError

TypeError listing names of the missing arguments

missingNamesTypeError	back to summary
private TypeError missingNamesTypeError(String kind, ArrayList<String> names) Compose a `TypeError` from the missing argument names.

setKeywordArguments back to summary

pack-priv void setKeywordArguments(PyDict kwargs)

For each of the names used as keywords in the call, match it with an allowable parameter name, and assign that frame-local variable the keyword argument given in the call. If the variable is not null, this is an error.

"Allowable parameter name" here means the names in argnames[p:q] where p=posonlyargcount and q=argcount + kwonlyargcount. If the name used in the call is not an allowable keyword, then if this parser allows for excess keywords, add it to the frame's keyword dictionary, otherwise throw an informative error.

In this version, accept the keyword arguments passed as a dictionary, as in the "classic" (*args, **kwargs) call.

Parameters

kwargs:PyDict: keyword arguments given in call

setKeywordArguments back to summary

pack-priv void setKeywordArguments(Object[] stack, int kwstart, String[] kwnames)

In this version, accept the keyword arguments passed as a dictionary, as in the "classic" (*args, **kwargs) call.

Parameters

stack:Object[]: [kwstart:kwstart+len(kwnames)] values corresponding to kwnames in order
kwstart:int: start position in kwvalues
kwnames:String[]: keywords used in the call (or **kwargs)

setLocal back to summary

pack-priv abstract void setLocal(int i, Object v)

Set the local variable named by argnames[i]

Parameters

i:int: index of variable name in argnames
v:Object: to assign to variable named argnames[i]

setPositionalArguments

back to summary

pack-priv void setPositionalArguments(PyTuple args)

Parameters

args:PyTuple: positional arguments

setPositionalArguments

back to summary

pack-priv void setPositionalArguments(Object[] stack, int pos, int nargs)

Parameters

stack:Object[]: positional and keyword arguments
pos:int: position of arguments in the array
nargs:int: number of positional arguments

tooManyPositional	back to summary
protected TypeError tooManyPositional(int posGiven)

unexpectedKeyword back to summary

protected <K> TypeError unexpectedKeyword(Object kw, Collection<? extends K> kwnames)

Diagnose an unexpected keyword occurring in a call and represent the problem as an exception. The particular keyword may incorrectly name a positional parameter, or it may be entirely unexpected (not be a parameter at all). In any case, since this error is going to be fatal to the call, this method looks at all the keywords to see if any are positional-only parameters, and if that's not the problem, reports just the originally-offending keyword as unexpected.

We call this method when any keyword has been encountered that does not match a legitimate parameter, and there is no **kwargs dictionary to catch it. Because Python makes it possible to supply keyword arguments from a map with object keys, we accept any object as a keyword name.

Parameters

<K>: type of element in keyword collection
kw:Object: the unexpected keyword encountered in the call
kwnames:Collection<? extends K>: all the keywords used in the call

Returns:TypeError

TypeError diagnosing the problem