Class PyArgParser
- java.lang.Object
-
- com.inductiveautomation.ignition.common.script.PyArgParser
-
public class PyArgParser extends java.lang.Object
Roughly equivalent to the olderPyArgumentMap
, but with stricter validation of types and some more "modern" conveniences.
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
containsKey(java.lang.String keyword)
java.util.Optional<java.util.List<java.lang.Object>>
getAsList(java.lang.String keyword)
Retrieve the argument specified bykeyword
as a plain list.<T> java.util.Optional<java.util.List<T>>
getAsList(java.lang.String keyword, java.lang.Class<T> clazz)
Retrieve the argument specified bykeyword
as a typed list ofclazz
.java.util.Optional<java.util.Map<java.lang.Object,java.lang.Object>>
getAsMap(java.lang.String keyword)
Retrieve the argument specified bykeyword
as an untyped map.<K,V>
java.util.Optional<java.util.Map<K,V>>getAsMap(java.lang.String keyword, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
Retrieve the argument specified bykeyword
as a typed map.java.util.Optional<java.lang.Boolean>
getBoolean(java.lang.String keyword)
Getskeyword
, if and only if it was supplied as a boolean.java.util.Optional<java.util.Date>
getDate(java.lang.String keyword)
Getskeyword
, if and only if it was supplied as a Date.java.util.Optional<java.lang.Double>
getDouble(java.lang.String keyword)
Getskeyword
, if and only if it was supplied as a double.java.util.Optional<java.lang.Float>
getFloat(java.lang.String keyword)
Getskeyword
, if and only if it was supplied as a float.java.util.Optional<java.lang.Integer>
getInteger(java.lang.String keyword)
Getskeyword
, if and only if it was supplied as an integer.java.util.Optional<java.lang.Long>
getLong(java.lang.String keyword)
Getskeyword
, if and only if it was supplied as a long.java.lang.Boolean
getNullableBoolean(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Boolean.java.util.Date
getNullableDate(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Date.java.lang.Double
getNullableDouble(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Double.java.lang.Float
getNullableFloat(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Float.java.lang.Integer
getNullableInteger(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Integer.java.lang.Long
getNullableLong(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Long.java.lang.String
getNullableString(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a String.<T> T
getNullSafe(java.lang.String keyword, java.lang.Class<T> clazz)
java.util.Optional<org.python.core.PyObject>
getPyObject(java.lang.String keyword)
Getskeyword
, directly as a PyObject; i.e., without doing any casting.java.util.Optional<java.lang.String>
getString(java.lang.String keyword)
Getskeyword
, if and only if it was supplied as a String.<T> java.util.Optional<T>
getTyped(java.lang.String keyword, java.lang.Class<T> clazz)
Ifkeyword
was supplied, return it (type-safe) or throw a TypeError.static PyArgParser
parseArgs(org.python.core.PyObject[] args, java.lang.String[] keywords, java.lang.Class<?> callingClass, java.lang.String methodName)
Similar toPyArgumentMap.interpretPyArgs(PyObject[], String[], Class, String)
, but with more explicit type-checking behavior.static PyArgParser
parseArgs(org.python.core.PyObject[] args, java.lang.String[] keywords, java.lang.String[] expectedKeywords, java.lang.Class<?>[] expectedTypes, java.lang.String functionName)
Similar toPyArgumentMap.interpretPyArgs(PyObject[], String[], String[], Class[])
, but with more explicit type-checking behavior.boolean
requireBoolean(java.lang.String keyword)
Retrieve required argumentkeyword
, if and only if it was supplied as a boolean.java.util.Date
requireDate(java.lang.String keyword)
Retrieve required argumentkeyword
, if and only if it was supplied as a Date.double
requireDouble(java.lang.String keyword)
Retrieve required argumentkeyword
, if and only if it was supplied as a double.float
requireFloat(java.lang.String keyword)
Retrieve required argumentkeyword
, if and only if it was supplied as a float.int
requireInteger(java.lang.String keyword)
Retrieve required argumentkeyword
, if and only if it was supplied as an integer.long
requireLong(java.lang.String keyword)
Retrieve required argumentkeyword
, if and only if it was supplied as a long.org.python.core.PyObject
requirePyObject(java.lang.String keyword)
Retrievekeyword
, directly as a PyObject; i.e., without doing any casting.java.lang.String
requireString(java.lang.String keyword)
Retrieve required argumentkeyword
, if and only if it was supplied as a String.
-
-
-
Method Detail
-
parseArgs
public static PyArgParser parseArgs(org.python.core.PyObject[] args, java.lang.String[] keywords, java.lang.String[] expectedKeywords, java.lang.Class<?>[] expectedTypes, java.lang.String functionName)
Similar toPyArgumentMap.interpretPyArgs(PyObject[], String[], String[], Class[])
, but with more explicit type-checking behavior.- Parameters:
args
- args from a function callkeywords
- keyword names from a function callexpectedKeywords
- expected keyword argumentsexpectedTypes
- expected argument typesfunctionName
- the name of the function; used for better contextual error messages- Returns:
- a PyArgParser instance
- Throws:
java.lang.IllegalArgumentException
- if the provided method cannot be found, or is missing the KeywordArgs annotation.java.lang.AssertionError
- ifkeywords
is shorter thanargs
, or the list of expected keywords doesn't match the list of expected types.
-
parseArgs
public static PyArgParser parseArgs(org.python.core.PyObject[] args, java.lang.String[] keywords, java.lang.Class<?> callingClass, java.lang.String methodName)
Similar toPyArgumentMap.interpretPyArgs(PyObject[], String[], Class, String)
, but with more explicit type-checking behavior.- Parameters:
args
- args from a function callkeywords
- keyword names from a function callcallingClass
- the class the method is contained in. Will be checked reflectively for theKeywordArgs
annotation.methodName
- the name of the method. Used to look up annotations reflectively, and for thrown errors.- Returns:
- a PyArgParser instance
- Throws:
java.lang.IllegalArgumentException
- if the provided method cannot be found, or is missing the KeywordArgs annotation.java.lang.AssertionError
- ifkeywords
is shorter thanargs
, 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
-
getTyped
public <T> java.util.Optional<T> getTyped(java.lang.String keyword, java.lang.Class<T> clazz)
Ifkeyword
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 toclazz
.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function
-
getNullSafe
@Nullable public <T> T getNullSafe(java.lang.String keyword, java.lang.Class<T> clazz)
-
getBoolean
public java.util.Optional<java.lang.Boolean> getBoolean(java.lang.String keyword)
Getskeyword
, if and only if it was supplied as a boolean.- 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireBoolean(String)
-
requireBoolean
public boolean requireBoolean(java.lang.String keyword)
Retrieve required argumentkeyword
, if and only if it was supplied as a boolean.- Returns:
- the boolean value of
keyword
- Throws:
org.python.core.PyException
- TypeError if the supplied value was not a boolean, or was not specified.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
getBoolean(String)
-
getNullableBoolean
@Nullable public java.lang.Boolean getNullableBoolean(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Boolean. UnlikerequireBoolean(String)
, will accept a supplied value ofPyNone
and return null.- Returns:
- the Boolean value of
keyword
, or null. - Throws:
org.python.core.PyException
- TypeError if the supplied value was not a Booleanjava.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireBoolean(String)
-
getInteger
public java.util.Optional<java.lang.Integer> getInteger(java.lang.String keyword)
Getskeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireInteger(String)
-
requireInteger
public int requireInteger(java.lang.String keyword)
Retrieve required argumentkeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
getInteger(String)
-
getNullableInteger
@Nullable public java.lang.Integer getNullableInteger(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Integer. UnlikerequireInteger(String)
, will accept a supplied value ofPyNone
and return null.- Returns:
- the Integer value of
keyword
, or null. - Throws:
org.python.core.PyException
- TypeError if the supplied value was not a Integerjava.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireInteger(String)
-
getLong
public java.util.Optional<java.lang.Long> getLong(java.lang.String keyword)
Getskeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireLong(String)
-
requireLong
public long requireLong(java.lang.String keyword)
Retrieve required argumentkeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
getLong(String)
-
getNullableLong
@Nullable public java.lang.Long getNullableLong(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Long. UnlikerequireLong(String)
, will accept a supplied value ofPyNone
and return null.- Returns:
- the Long value of
keyword
, or null. - Throws:
org.python.core.PyException
- TypeError if the supplied value was not a Longjava.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireLong(String)
-
getFloat
public java.util.Optional<java.lang.Float> getFloat(java.lang.String keyword)
Getskeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireFloat(String)
-
requireFloat
public float requireFloat(java.lang.String keyword)
Retrieve required argumentkeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
getFloat(String)
-
getNullableFloat
@Nullable public java.lang.Float getNullableFloat(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Float. UnlikerequireFloat(String)
, will accept a supplied value ofPyNone
and return null.- Returns:
- the Float value of
keyword
, or null. - Throws:
org.python.core.PyException
- TypeError if the supplied value was not a Floatjava.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireFloat(String)
-
getDouble
public java.util.Optional<java.lang.Double> getDouble(java.lang.String keyword)
Getskeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireDouble(String)
-
requireDouble
public double requireDouble(java.lang.String keyword)
Retrieve required argumentkeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
getDouble(String)
-
getNullableDouble
@Nullable public java.lang.Double getNullableDouble(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Double. UnlikerequireDouble(String)
, will accept a supplied value ofPyNone
and return null.- Returns:
- the Double value of
keyword
, or null. - Throws:
org.python.core.PyException
- TypeError if the supplied value was not a Doublejava.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireDouble(String)
-
getDate
public java.util.Optional<java.util.Date> getDate(java.lang.String keyword)
Getskeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireDate(String)
-
requireDate
public java.util.Date requireDate(java.lang.String keyword)
Retrieve required argumentkeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
getDate(String)
-
getNullableDate
@Nullable public java.util.Date getNullableDate(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a Date. UnlikerequireDate(String)
, will accept a supplied value ofPyNone
and return null.- Returns:
- the Date value of
keyword
, or null. - Throws:
org.python.core.PyException
- TypeError if the supplied value was not a Datejava.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireDate(String)
-
getString
public java.util.Optional<java.lang.String> getString(java.lang.String keyword)
Getskeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireString(String)
-
requireString
@Nonnull public java.lang.String requireString(java.lang.String keyword)
Retrieve required argumentkeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
getString(String)
-
getNullableString
@Nullable public java.lang.String getNullableString(java.lang.String keyword)
Retrieve argumentkeyword
, if and only if it was supplied as a String. UnlikerequireString(String)
, will accept a supplied value ofPyNone
and return null.- Returns:
- the String value of
keyword
, or null. - Throws:
org.python.core.PyException
- TypeError if the supplied value was not a Stringjava.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requireString(String)
-
getPyObject
public java.util.Optional<org.python.core.PyObject> getPyObject(java.lang.String keyword)
Getskeyword
, directly as a PyObject; i.e., without doing any casting.- Returns:
- the PyObject value of
keyword
, if supplied, or an empty optional. Can bePy.None
if None was supplied. - Throws:
java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
requirePyObject(String)
-
requirePyObject
public org.python.core.PyObject requirePyObject(java.lang.String keyword)
Retrievekeyword
, 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.java.lang.IllegalArgumentException
- if the provided keyword is not an expected argument for the function- See Also:
getPyObject(String)
-
containsKey
public boolean containsKey(java.lang.String keyword)
-
getAsList
public <T> java.util.Optional<java.util.List<T>> getAsList(java.lang.String keyword, java.lang.Class<T> clazz)
Retrieve the argument specified bykeyword
as a typed list ofclazz
. 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
- TypeError if any elements of the PyList supplied as an argument can't be coerced to
-
getAsList
public java.util.Optional<java.util.List<java.lang.Object>> getAsList(java.lang.String keyword)
Retrieve the argument specified bykeyword
as a plain list. Will be a shallow copy.- Throws:
org.python.core.PyException
-- TypeError if the supplied PyObject is not iterable
-
getAsMap
public <K,V> java.util.Optional<java.util.Map<K,V>> getAsMap(java.lang.String keyword, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
Retrieve the argument specified bykeyword
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 java.util.Optional<java.util.Map<java.lang.Object,java.lang.Object>> getAsMap(java.lang.String keyword)
Retrieve the argument specified bykeyword
as an untyped map. Will be a shallow copy.- Throws:
org.python.core.PyException
-- TypeError if the supplied PyObject is not iterable
-
-