Syntax Cheat Sheet¶
The syntax can be challenging at first, but once you master it, it’s pretty powerful. We’ll give the bellow cheat sheet, and some examples too!
{
"args": [
{
"name": "arg1",
"type": TYPE_REF,
"values": VALUE_REF
}
],
"kwargs": {
"kwarg1": {
"type": TYPE_REF,
"values": VALUE_REF
}
}
}
Let’s take a look at the keys step-by-step.
TYPE_REF¶
Type refs are formatted strings or types in python. Here’s the potential values, and what they do:
Native type: "int"
or int
This is a native type. This works for all non-nested native types.
{
"type": "int",
"values": VALUE_REF for int
}
NoneType: "NoneType"
This is a native type of None
, or type(None)
.
{
"type": "NoneType",
"values": null # always null for NoneType
}
Note
This may seem useless, as an argument that has to be None cannot pass any usable input, but this is not the case when nested.
{
"type": "one([int, float, NoneType])",
"values": {
"int": VALUE_REF for int,
"float": VALUE_REF for float,
"NoneType": null
}
}
This argument can be an integer, a float, or None.
Native type, iterable, unstructured: "list"
or list
This is a list native type. It has no required structure.
{
"type": "list",
"values": null # we cannot assign a value to an unstructured type
}
Native type, iterable, structured: "list([int, str])"
or list([int, str])
This is a list native type. It requires one integer, and one string, in that order.
{
"type": "list([int, str])"
"values": [
VALUE_REF for position 0, int
VALUE_REF for position 1, str
]
}
Native type, keyed, unstructured: "dict"
or dict
This is a dict native type. It has no required structure or keys.
{
"type": "dict",
"values": null
}
Native type, keyed, structured: {"a": {"type": int, "values": None}
This is a nested dict type. It indicates that the arg must be of type dict, and must contain the key "a"
corresponding to an integer value.
{
"type": dict
"values": {
"subkey1": {
"type": TYPE_REF for key subkey1,
"values": VALUE_REF for key subkey1,
"required": true (default)/false
},
...
}
}
Native type, choice: "one([int, float])"
or canonical_args.check.ChoiceOfOne([int, float])
This is a “ChoiceOfOne” type. It indicates the arg can be one of either int
or float
types.
{
"type": "one([int, float])",
"values": {
"int": VALUE_REF for arg if arg is int,
"float": VALUE_REF for arg if arg is float
}
}
Note
The "values"
key is of type dict
, and contains an entry for each possible type in the "type": "one([int, float])"
type ref.
Class type: "cls('import.string.to.ClassObject')"
This is a Class type. It indicates that the argument will instance or subinstance the class located at 'import.string.to.ClassObject'
. Imports will be made automatically.
{
"type": "cls('mymodule.MyClass')",
"values": null # cannot value check objects at this time
}
Type type: "TypeType"
This is used to ensure the value of an argument itself is a type. So, for instance, passing int
would pass the <type 'type'>
check, but passing 1
would raise an AssertionError
.
{
"type": "TypeType",
"values": [int, float]
}
The value of the argument would have to be either int
or float
to pass the check.
VALUE_REF¶
Value refs are str
, list
or dict
in type, and detail the permissable values for the argument to which they correspond.
Comparison: ">{}"
, "<{}"
, ">={}"
, "<={}"
, "!={}"
This value ref compares a number to the number replacing the "{}"
. Obviously enough, only use these for TYPE_REF float
or int
.
{
"type": "int",
"values": ">0"
}
Note
Chaining comparison value refs is acceptable, and done as follows:
"((<10||>10)&&!=5)||(<=0&&!=-3)"
The number must be:
- less than 10 or greater than 10, but not equal to 5, or
- less than or equal to 0, but not equal to -3
Range: "range({}, {})"
This value ref ensures a numerical argument input falls between two numbers. Note that the range is inclusive, as in {}<=arg<={}
.
{
"type": "float",
"values": "range(-5.5, 10.6)"
}
Preset list: ["SAMME", "SAMME.R"]
Ensure a argument input is in this list. Good for control arguments, asking for algorithm names, for example.
{
"type": "str",
"values": ["A", "B", "C"]
}
Note
For details on nesting Type refs and value refs, see Arg Specs.