Package com.inductiveautomation.ignition.common.script

Class PyArgParser

java.lang.Object

com.inductiveautomation.ignition.common.script.PyArgParser

public class PyArgParser
extends Object

A utility class for converting Jython's keyword argument signature (PyObject[], String[]) into more useful Java base classes. Argument names specified in camelCase in Java code will be accepted in either camelCase or snake_case from Jython.

See Also:

• for the older alternative with weaker type checking.
• for general utilities for working with PyObjects.
• for basic unwrapping of Python objects to Java primitives.
• for parsing Python primitive data structures into Gson elements.

Method Summary

Modifier and Type	Method	Description
boolean	containsKey(String keyword)
Optional<List<Object>>	getAsList(String keyword)	Retrieve the argument specified by keyword as a plain list.
<T> Optional<List<T>>	getAsList(String keyword, Class<T> clazz)	Retrieve the argument specified by keyword as a typed list of clazz.
Optional<Map<Object,Object>>	getAsMap(String keyword)	Retrieve the argument specified by keyword as an untyped map.
<K, V> Optional<Map<K,V>>	getAsMap(String keyword, Class<K> keyType, Class<V> valueType)	Retrieve the argument specified by keyword as a typed map.
Optional<Boolean>	getBoolean(String keyword)	Gets keyword, if and only if it was supplied as a boolean or number.
Optional<Date>	getDate(String keyword)	Gets keyword, if and only if it was supplied as a Date.
Optional<Double>	getDouble(String keyword)	Gets keyword, if and only if it was supplied as a double.
Optional<Float>	getFloat(String keyword)	Gets keyword, if and only if it was supplied as a float.
<T> Optional<T>	getIndexed(int index, Class<T> clazz)	Retrieve the positional argument (type-safe) at index or throw a TypeError.
<T> Optional<List<T>>	getIndexedAsList(int index, Class<T> clazz)	Retrieve the positional argument at index as a typed list of clazz.
Optional<Integer>	getInteger(String keyword)	Gets keyword, if and only if it was supplied as an integer.
Optional<Long>	getLong(String keyword)	Gets keyword, if and only if it was supplied as a long.
Boolean	getNullableBoolean(String keyword)	Retrieve argument keyword, if and only if it was supplied as a Boolean or number.
Date	getNullableDate(String keyword)	Retrieve argument keyword, if and only if it was supplied as a Date.
Double	getNullableDouble(String keyword)	Retrieve argument keyword, if and only if it was supplied as a Double.
Float	getNullableFloat(String keyword)	Retrieve argument keyword, if and only if it was supplied as a Float.
Integer	getNullableInteger(String keyword)	Retrieve argument keyword, if and only if it was supplied as a Integer.
Long	getNullableLong(String keyword)	Retrieve argument keyword, if and only if it was supplied as a Long.
String	getNullableString(String keyword)	Retrieve argument keyword, if and only if it was supplied as a String.
<T> T	getNullSafe(String keyword, Class<T> clazz)
Optional<org.python.core.PyObject>	getPyObject(int index)	Gets positional argument at index, directly as a PyObject; i.e., without doing any casting.
Optional<org.python.core.PyObject>	getPyObject(String keyword)	Gets keyword, directly as a PyObject; i.e., without doing any casting.
Optional<String>	getString(String keyword)	Gets keyword, if and only if it was supplied as a String.
<T> Optional<T>	getTyped(String keyword, Class<T> clazz)	If keyword was supplied, return it (type-safe) or throw a TypeError.
static PyArgParser	parseArgs(org.python.core.PyObject[] args, String[] keywords, Class<?> callingClass, String methodName)	Parses the provided arguments and keywords into a PyArgParser instance, which can then be used to retrieve type-safe arguments.
static PyArgParser	parseArgs(org.python.core.PyObject[] args, String[] keywords, String[] expectedKeywords, Class<?>[] expectedTypes, String functionName)	Parses the provided arguments and keywords into a PyArgParser instance, which can then be used to retrieve type-safe arguments.
boolean	requireBoolean(String keyword)	Retrieve required argument keyword, if and only if it was supplied as a boolean or number.
Date	requireDate(String keyword)	Retrieve required argument keyword, if and only if it was supplied as a Date.
double	requireDouble(String keyword)	Retrieve required argument keyword, if and only if it was supplied as a double.
float	requireFloat(String keyword)	Retrieve required argument keyword, if and only if it was supplied as a float.
int	requireInteger(String keyword)	Retrieve required argument keyword, if and only if it was supplied as an integer.
List<Object>	requireList(String keyword)	Retrieve required argument keyword if and only if it was supplied as a list.
<T> List<T>	requireList(String keyword, Class<T> clazz)	Retrieve required argument keyword if and only if it was supplied as a list of clazz.
long	requireLong(String keyword)	Retrieve required argument keyword, if and only if it was supplied as a long.
org.python.core.PyObject	requirePyObject(String keyword)	Retrieve keyword, directly as a PyObject; i.e., without doing any casting.
String	requireString(String keyword)	Retrieve required argument keyword, if and only if it was supplied as a String.
<T> T	requireTyped(String keyword, Class<T> clazz)	Retrieve required argument keyword, if and only if the supplied value can be coerced to clazz.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

parseArgs

public static PyArgParser parseArgs(org.python.core.PyObject[] args,
 String[] keywords,
 String[] expectedKeywords,
 Class<?>[] expectedTypes,
 String functionName)

Parses the provided arguments and keywords into a PyArgParser instance, which can then be used to retrieve type-safe arguments. The expected keywords and types are provided as arguments.

Parameters:

args - args from a function call

keywords - keyword names from a function call

expectedKeywords - expected keyword arguments

expectedTypes - expected argument types

functionName - the name of the function; used for better contextual error messages

Returns:

a PyArgParser instance

Throws:

AssertionError - if keywords is shorter than args, or the list of expected keywords doesn't match the list of expected types.

parseArgs

public static PyArgParser parseArgs(org.python.core.PyObject[] args,
 String[] keywords,
 Class<?> callingClass,
 String methodName)

Parses the provided arguments and keywords into a PyArgParser instance, which can then be used to retrieve type-safe arguments. The expected keywords and types are retrieved by looking for a method on the supplied class with the KeywordArgs annotation.

Parameters:

args - args from a function call

keywords - keyword names from a function call

callingClass - the class the method is contained in.

methodName - the name of the method. Used to look up annotations reflectively, and for thrown errors.

Returns:

a PyArgParser instance

Throws:

IllegalArgumentException - if the provided method cannot be found, or is missing the KeywordArgs annotation.

AssertionError - if keywords is shorter than args, or the list of expected keywords doesn't match the list of expected types.

org.python.core.PyException - TypeError if more arguments are provided than expected argument names

See Also:

• KeywordArgs

getIndexed

public <T> Optional<T> getIndexed(int index,
 Class<T> clazz)

Retrieve the positional argument (type-safe) at index or throw a TypeError. If the index is out of range, returns an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value cannot be coerced to clazz.

getTyped

public <T> Optional<T> getTyped(String keyword,
 Class<T> clazz)

If keyword was supplied, return it (type-safe) or throw a TypeError. If not specified or None was supplied, returns an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value cannot be coerced to clazz.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

requireTyped

public <T> T requireTyped(String keyword,
 Class<T> clazz)

Retrieve required argument keyword, if and only if the supplied value can be coerced to clazz.

Returns:

the retrieved value of keyword coerced to clazz.

Throws:

org.python.core.PyException - TypeError if the supplied value cannot be coerced to clazz.

IllegalArgumentException - if the provided keyword is not an expected argument for the function.

getNullSafe

@Nullable
public <T> T getNullSafe(String keyword,
 Class<T> clazz)

getBoolean

public Optional<Boolean> getBoolean(String keyword)

Gets keyword, if and only if it was supplied as a boolean or number.

Returns:

the boolean value of keyword, if supplied, or an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a boolean.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireBoolean(String)

requireBoolean

public boolean requireBoolean(String keyword)

Retrieve required argument keyword, if and only if it was supplied as a boolean or number.

Returns:

the boolean value of keyword

Throws:

org.python.core.PyException - TypeError if the supplied value was not a boolean, or was not specified.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• getBoolean(String)

getNullableBoolean

@Nullable
public Boolean getNullableBoolean(String keyword)

Retrieve argument keyword, if and only if it was supplied as a Boolean or number. Unlike requireBoolean(String), will accept a supplied value of PyNone and return null.

Returns:

the Boolean value of keyword, or null.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a Boolean

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireBoolean(String)

getInteger

public Optional<Integer> getInteger(String keyword)

Gets keyword, if and only if it was supplied as an integer.

Returns:

the integer value of keyword, if supplied, or an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a integer.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireInteger(String)

requireInteger

public int requireInteger(String keyword)

Retrieve required argument keyword, if and only if it was supplied as an integer.

Returns:

the integer value of keyword

Throws:

org.python.core.PyException - TypeError if the supplied value was not a integer, or was not specified.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• getInteger(String)

getNullableInteger

@Nullable
public Integer getNullableInteger(String keyword)

Retrieve argument keyword, if and only if it was supplied as a Integer. Unlike requireInteger(String), will accept a supplied value of PyNone and return null.

Returns:

the Integer value of keyword, or null.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a Integer

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireInteger(String)

getLong

public Optional<Long> getLong(String keyword)

Gets keyword, if and only if it was supplied as a long.

Returns:

the long value of keyword, if supplied, or an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a long.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireLong(String)

requireLong

public long requireLong(String keyword)

Retrieve required argument keyword, if and only if it was supplied as a long.

Returns:

the long value of keyword

Throws:

org.python.core.PyException - TypeError if the supplied value was not a long, or was not specified.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• getLong(String)

getNullableLong

@Nullable
public Long getNullableLong(String keyword)

Retrieve argument keyword, if and only if it was supplied as a Long. Unlike requireLong(String), will accept a supplied value of PyNone and return null.

Returns:

the Long value of keyword, or null.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a Long

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireLong(String)

getFloat

public Optional<Float> getFloat(String keyword)

Gets keyword, if and only if it was supplied as a float.

Returns:

the float value of keyword, if supplied, or an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a float.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireFloat(String)

requireFloat

public float requireFloat(String keyword)

Retrieve required argument keyword, if and only if it was supplied as a float.

Returns:

the float value of keyword

Throws:

org.python.core.PyException - TypeError if the supplied value was not a float, or was not specified.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• getFloat(String)

getNullableFloat

@Nullable
public Float getNullableFloat(String keyword)

Retrieve argument keyword, if and only if it was supplied as a Float. Unlike requireFloat(String), will accept a supplied value of PyNone and return null.

Returns:

the Float value of keyword, or null.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a Float

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireFloat(String)

getDouble

public Optional<Double> getDouble(String keyword)

Gets keyword, if and only if it was supplied as a double.

Returns:

the double value of keyword, if supplied, or an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a double.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireDouble(String)

requireDouble

public double requireDouble(String keyword)

Retrieve required argument keyword, if and only if it was supplied as a double.

Returns:

the double value of keyword

Throws:

org.python.core.PyException - TypeError if the supplied value was not a double, or was not specified.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• getDouble(String)

getNullableDouble

@Nullable
public Double getNullableDouble(String keyword)

Retrieve argument keyword, if and only if it was supplied as a Double. Unlike requireDouble(String), will accept a supplied value of PyNone and return null.

Returns:

the Double value of keyword, or null.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a Double

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireDouble(String)

getDate

public Optional<Date> getDate(String keyword)

Gets keyword, if and only if it was supplied as a Date.

Returns:

the Date value of keyword, if supplied, or an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a Date.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireDate(String)

requireDate

public Date requireDate(String keyword)

Retrieve required argument keyword, if and only if it was supplied as a Date.

Returns:

the Date value of keyword

Throws:

org.python.core.PyException - TypeError if the supplied value was not a Date, or was not specified.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• getDate(String)

getNullableDate

@Nullable
public Date getNullableDate(String keyword)

Retrieve argument keyword, if and only if it was supplied as a Date. Unlike requireDate(String), will accept a supplied value of PyNone and return null.

Returns:

the Date value of keyword, or null.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a Date

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireDate(String)

getString

public Optional<String> getString(String keyword)

Gets keyword, if and only if it was supplied as a String.

Returns:

the String value of keyword, if supplied, or an empty optional.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a String.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireString(String)

requireString

@Nonnull
public String requireString(String keyword)

Retrieve required argument keyword, if and only if it was supplied as a String.

Returns:

the String value of keyword

Throws:

org.python.core.PyException - TypeError if the supplied value was not a String, or was not specified.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• getString(String)

getNullableString

@Nullable
public String getNullableString(String keyword)

Retrieve argument keyword, if and only if it was supplied as a String. Unlike requireString(String), will accept a supplied value of PyNone and return null.

Returns:

the String value of keyword, or null.

Throws:

org.python.core.PyException - TypeError if the supplied value was not a String

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requireString(String)

getPyObject

public Optional<org.python.core.PyObject> getPyObject(int index)

Gets positional argument at index, directly as a PyObject; i.e., without doing any casting.

Returns:

the PyObject value at index

Throws:

IllegalArgumentException - if the provided index is negative

getPyObject

public Optional<org.python.core.PyObject> getPyObject(String keyword)

Gets keyword, directly as a PyObject; i.e., without doing any casting.

Returns:

the PyObject value of keyword, if supplied, or an empty optional. Can be Py.None if None was supplied.

Throws:

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• requirePyObject(String)

requirePyObject

public org.python.core.PyObject requirePyObject(String keyword)

Retrieve keyword, directly as a PyObject; i.e., without doing any casting.

Returns:

the PyObject value of keyword

Throws:

org.python.core.PyException - TypeError if the supplied value was not provided.

IllegalArgumentException - if the provided keyword is not an expected argument for the function

See Also:

• getPyObject(String)

containsKey

public boolean containsKey(String keyword)

getIndexedAsList

public <T> Optional<List<T>> getIndexedAsList(int index,
 Class<T> clazz)

Retrieve the positional argument at index as a typed list of clazz. Will be a shallow copy.

Throws:

org.python.core.PyException -

TypeError if any elements of the PyList supplied as an argument can't be coerced to clazz

TypeError if the supplied PyObject is not iterable

getAsList

public <T> Optional<List<T>> getAsList(String keyword,
 Class<T> clazz)

Retrieve the argument specified by keyword as a typed list of clazz. Will be a shallow copy.

Throws:

org.python.core.PyException -

TypeError if any elements of the PyList supplied as an argument can't be coerced to clazz

TypeError if the supplied PyObject is not iterable

requireList

public <T> List<T> requireList(String keyword,
 Class<T> clazz)

Retrieve required argument keyword if and only if it was supplied as a list of clazz. Will be a shallow copy.

Throws:

org.python.core.PyException -

• TypeError if any elements of the PyList supplied as an argument can't be coerced to clazz
• TypeError if the supplied PyObject is not iterable

IllegalArgumentException - if the provided keyword is not an expected argument for the function

getAsList

public Optional<List<Object>> getAsList(String keyword)

Retrieve the argument specified by keyword as a plain list. Will be a shallow copy.

Throws:

org.python.core.PyException -

TypeError if the supplied PyObject is not iterable

requireList

public List<Object> requireList(String keyword)

Retrieve required argument keyword if and only if it was supplied as a list. Will be a shallow copy.

Throws:

org.python.core.PyException -

• TypeError if the supplied PyObject is not iterable

IllegalArgumentException - if the provided keyword is not an expected argument for the function

getAsMap

public <K,
V> Optional<Map<K,V>> getAsMap(String keyword,
 Class<K> keyType,
 Class<V> valueType)

Retrieve the argument specified by keyword as a typed map. Will be a shallow copy.

Throws:

org.python.core.PyException -

TypeError if any elements of the PyDictionary supplied as an argument can't be coerced to the right class

TypeError if the supplied PyObject is not iterable

getAsMap

public Optional<Map<Object,Object>> getAsMap(String keyword)

Retrieve the argument specified by keyword as an untyped map. Will be a shallow copy.

Throws:

org.python.core.PyException -

TypeError if the supplied PyObject is not iterable