Options¶

Reference

Learn more about the options module in the technical reference.

Use options to capture parameters (i.e.: configurations) for the run. You may use the load function to build an input from a source. If options are correctly configured in the app.yaml manifest, then you can retrieve the options from the input.

Consider the following app.yaml manifest that defines a json application with some sample options:

app.yaml

# This manifest holds the information the app needs to run on Nextmv.

# Type and runtime specify the language and environment of the app.
type: python
runtime: ghcr.io/nextmv-io/runtime/python:3.11

# Python-specific configurations.
python:
  # All listed packages will get bundled with the app.
  pip-requirements: pyproject.toml # Can be a requirements.txt

# List all files/directories that should be included in the app. Globbing
# (e.g.: configs/*.json) is supported.
files:
  - main.py

# Application configurations.
configuration:
  # Define the content format of the app, one of: json, multi-file.
  content:
    format: json # Read JSON from stdin and write JSON to stdout.
  # Options (parameters) that the app can receive at runtime.
  options:
    strict: false # If `true`, only the listed options will be allowed.
    items: # Add as many options as needed.
      - name: string_option
        option_type: string
        default: "An optional, default value."
        description: "An example of a string option."
        required: false # Normally false when a default is provided.
        # OPTIONAL: Use the following fields for a customized Nextmv Console experience.
        ui:
          display_name: "String Option"
          # hidden_from: viewer # Uncomment to hide for a role.
          control_type: select # Can be one of: input, select, multiselect.
        additional_attributes:
          values: # Required for select and multiselect control types.
            - one_value
            - another_value
          # max_length: 42 # Optional, for input control type.
          # min_length: 3 # Optional, for input control type.
      - name: integer_option
        option_type: int
        # default: 42 # Normally, when a default is not provided, it is required.
        description: "An example of an integer option."
        required: true
        # OPTIONAL: Use the following fields for a customized Nextmv Console experience.
        ui:
          display_name: "Integer Option"
          # hidden_from: viewer # Uncomment to hide for a role.
          control_type: slider # Can be one of: input, slider, select.
        additional_attributes:
          min: 0 # Required for slider control type.
          max: 100 # Required for slider control type.
          step: 1 # Required for slider control type.
          # values: [0, 10, 42, 100] # Required for select control type.
      - name: float_option
        option_type: float
        # default: 3.14 # Normally, when a default is not provided, it is required.
        description: "An example of a float option."
        required: true
        # OPTIONAL: Use the following fields for a customized Nextmv Console experience.
        ui:
          display_name: "Float Option"
          # hidden_from: viewer # Uncomment to hide for a role.
          control_type: slider # Can be one of: input, slider, select.
        additional_attributes:
          min: 0.0 # Required for slider control type.
          max: 1.0 # Required for slider control type.
          step: 0.01 # Required for slider control type.
          # values: [0.0, 0.25, 0.5, 1.0] # Required for select control type.
      - name: boolean_option
        option_type: bool
        default: true
        description: "An example of a boolean option."
        required: false
        # OPTIONAL: Use the following fields for a customized Nextmv Console experience.
        ui:
          display_name: "Boolean Option"
          # hidden_from: viewer # Uncomment to hide for a role.
          control_type: toggle # Optional.

If you run the following python script:

main.py

import nextmv

loaded_input = nextmv.load()
options = loaded_input.options
print(options.to_dict())

You can pass the options as command-line arguments or environment variables, for example:

BashOutput

echo '{}' | uv run main.py --string_option foo --integer_option 123 --float_option 1.23 --boolean_option false

{'string_option': 'foo', 'integer_option': 123, 'float_option': 1.23, 'boolean_option': False}

Instead of defining options in the app.yaml manifest, you can also define them directly in the Python code using the Options class.

Consider the following script:

main.py

import nextmv

options = nextmv.Options(
    nextmv.Option("str_option", str, "default value", "A string option", required=True),
    nextmv.Option("int_option", int, 1, "An int option", required=False),
    nextmv.Option("float_option", float, 1.0, "A float option", required=False),
    nextmv.Option("bool_option", bool, True, "A bool option", required=True),
)

# Options can be accessed as attributes.
print(options.str_option)
print(options.int_option)
print(options.float_option)
print(options.bool_option)
print(options.to_dict())

By using options, you are able to pass in the values with CLI arguments or environment variables. Run the script, providing the required arguments.

BashOutput

uv run main.py --str_option foo --bool_option false

foo
1
1.0
False
{'str_option': 'foo', 'int_option': 1, 'float_option': 1.0, 'bool_option': False}

At any moment, you may summon the help message to see the available options.

BashOutput

uv run main.py --help

usage: main.py [options]

Options for main.py. Use command-line arguments (highest precedence) or environment variables.

options:
  -h, --help            show this help message and exit
  -str_option, --str_option STR_OPTION
                        [env var: STR_OPTION] (required) (default: default value) (type: str): A string option
  -int_option, --int_option INT_OPTION
                        [env var: INT_OPTION] (default: 1) (type: int): An int option
  -float_option, --float_option FLOAT_OPTION
                        [env var: FLOAT_OPTION] (default: 1.0) (type: float): A float option
  -bool_option, --bool_option BOOL_OPTION
                        [env var: BOOL_OPTION] (required) (default: True) (type: bool): A bool option

You can merge options together to create a new set of options.

main.py

import nextmv

options1 = nextmv.Options(
    nextmv.Option("str_option1", str, "default value", "A string option", required=True),
    nextmv.Option("int_option1", int, 1, "An int option", required=False),
    nextmv.Option("float_option1", float, 1.0, "A float option", required=False),
    nextmv.Option("bool_option1", bool, True, "A bool option", required=True),
)

options2 = nextmv.Options(
    nextmv.Option("str_option2", str, "default value", "A string option", required=True),
    nextmv.Option("int_option2", int, 1, "An int option", required=False),
)

options3 = nextmv.Options(
    nextmv.Option("float_option2", float, 1.0, "A float option", required=False),
    nextmv.Option("bool_option2", bool, True, "A bool option", required=True),
)

options = options1.merge(options2, options3)

print(options.str_option1)
print(options.int_option1)
print(options.float_option1)
print(options.bool_option1)
print(options.str_option2)
print(options.int_option2)
print(options.float_option2)
print(options.bool_option2)
print(options.to_dict())

BashOutput

uv run main.py --str_option1 foo --bool_option1 false --str_option2 bar --bool_option2 true

foo
1
1.0
False
bar
1
1.0
True
{'str_option1': 'foo', 'int_option1': 1, 'float_option1': 1.0, 'bool_option1': False, 'str_option2': 'bar', 'int_option2': 1, 'float_option2': 1.0, 'bool_option2': True}

You can summon the help and notice that the options from all three sets are available.

BashOutput

uv run main.py --help

usage: main.py [options]

Options for main2.py. Use command-line arguments (highest precedence) or environment variables.

options:
  -h, --help            show this help message and exit
  -str_option1 STR_OPTION1, --str_option1 STR_OPTION1
                        [env var: STR_OPTION1] (required) (default: default value) (type: str): A string option
  -int_option1 INT_OPTION1, --int_option1 INT_OPTION1
                        [env var: INT_OPTION1] (default: 1) (type: int): An int option
  -float_option1 FLOAT_OPTION1, --float_option1 FLOAT_OPTION1
                        [env var: FLOAT_OPTION1] (default: 1.0) (type: float): A float option
  -bool_option1 BOOL_OPTION1, --bool_option1 BOOL_OPTION1
                        [env var: BOOL_OPTION1] (required) (default: True) (type: bool): A bool option
  -str_option2 STR_OPTION2, --str_option2 STR_OPTION2
                        [env var: STR_OPTION2] (required) (default: default value) (type: str): A string option
  -int_option2 INT_OPTION2, --int_option2 INT_OPTION2
                        [env var: INT_OPTION2] (default: 1) (type: int): An int option
  -float_option2 FLOAT_OPTION2, --float_option2 FLOAT_OPTION2
                        [env var: FLOAT_OPTION2] (default: 1.0) (type: float): A float option
  -bool_option2 BOOL_OPTION2, --bool_option2 BOOL_OPTION2
                        [env var: BOOL_OPTION2] (required) (default: True) (type: bool): A bool option

Please note that merging the options will also parse them. Once options have been parsed, they cannot be merged with other options. You may also parse the options manually using the .parse() method.