Jython type usage

When you define a Python function that will be used by RiskScape, the inputs (i.e. argument-types) and output (i.e. return-type) must be compatible with the RiskScape type system.

Warning

This page describes an old way of declaring types for a Jython function, and the content is only included for historic reference. We recommend following the Python functions examples to define function types within your INI file.

These function input and output types can either be built-in RiskScape types (e.g. Types.TEXT), or more complex types you have defined in an INI file.

Within the Python function itself, you can simply use the native Python types and classes as local variables like normal. You only need to specify RiskScape-compatible types so that RiskScape will know what type of arguments the function expects, and what type of value will be returned.

Simple cases

To use a built-in RiskScape simple type as an argument or return-type for a Python function, you would use something like:

from nz.org.riskscape.engine.types import Types

ARGUMENT_TYPES = [ Types.TEXT, Types.INTEGER, Types.BOOLEAN, Types.GEOMETRY ]
RETURN_TYPE = Types.FLOATING

When a function uses a user-defined type from an INI file, you can simply refer to that type by name. For example:

ARGUMENT_TYPES = ['my-custom-type']

RETURN_TYPE = 'some-other-type'

Complex types

In most cases, you should be able to write versatile Python functions by just using the simple RiskScape types. When your functions use more complex types, it’s generally easiest to define them in an INI file (i.e. types.ini).

However, any complex types you can define in an INI file can also be defined in Python code. This approach might be useful if you wanted to share your function with other people, without them having to modify their INI files in order to use it.

Structs

Defining a new Struct within your Python code will look something like:

from nz.org.riskscape.engine.types import Types, Struct

MY_STRUCT_TYPE = Struct.of('key1', Types.TEXT) \
                 .and('key2', Types.INTEGER) \
                 .and('key3', Types.FLOATING)

Enumerations

An example of declaring a new enumeration type within your Python code:

from nz.org.riskscape.engine.types import Types, Enumeration

MY_ENUM_TYPE = Enumeration.oneBased("wood", "steel", "concrete")

Lists

To declare a list of geometry items, use:

from nz.org.riskscape.engine.types import Types, RSList

MY_TEXT_TYPE = RSList(Types.GEOMETRY)

Nullable

To declare a type as nullable, you need to get the underlying type that’s being wrapped. You can use typeset.getLinkedType() to lookup a user-defined type. If the underlying type is a built-in RiskScape simple type, then the lookup is unnecessary.

from nz.org.riskscape.engine.types import Types, Nullable

MY_NULLABLE_TYPE = Nullable.of(typeset.getLinkedType('other-type'))
SIMPLE_NULLABLE_TYPE = Nullable.of(Types.FLOATING)

Within range

Use the below example to specify that a number must be within a given range. This is the equivalent of using range() in an INI file.

from nz.org.riskscape.engine.types import Types, WithinRange

MY_RANGED_TYPE = WithinRange(Types.INTEGER, 0, 10)

Within set

Use the below example to specify that a type must fall within a given set of values. This is the equivalent of using set() in an INI file.

from nz.org.riskscape.engine.types import Types, WithinSet

MY_SET_TYPE = WithinSet(Types.TEXT, {'option-1', 'option-2', 'option-n'})