Hey! These docs are for version 2.12, which is no longer officially supported. Click here for the latest version, 2.18!

## Defining options

As explained in [Options](🔗), options are partitioned into named scopes, like `[test]` and `[isort]`. Each of these scopes corresponds to a _subsystem_.

To add new options:

  1. Define a subclass of `Subsystem` from `pants.subsystem.subsystem`.

    1. Set the class property `options_scope` with the name of the subsystem.

      • This value will be prepended to all options in the subsystem, e.g. `--skip` will become `--shellcheck-skip`.

    2. Set the class property `help`, which is used by `./pants help`.

  2. Add new options through `pants.options.option_types` class attributes.

  3. Register the `Subsystem` with `SubsystemRule` and `register.py`.

    • You don't need `SubsystemRule` if the `Subsystem` is used in an `@rule` because `collect_rules()` will recognize it. It doesn't hurt to keep this around, though.

The subsystem should now show up when you run `./pants help shellcheck`.


As explained in [Goal rules](🔗), goals use a subclass of `Subsystem`: `GoalSubsystem` from `pants.engine.goal`.

`GoalSubsystem` behaves the same way as a normal subsystem, except that you set the class property `name` rather than `options_scope`. The `name` will auto-populate the `options_scope`.

### Option types

These classes correspond to the option types at [Options](🔗).

Every option type requires that you set the flag name (e.g. `-l` or `--level`) and the keyword argument `help`. Most types require that you set `default`. You can optionally set `advanced=True` with every option for it to only show up with `help-advanced`.

Class nameNotes
`StrOption`Must set `default` to a `str` or `None`.
`BoolOption`Must set `default` to a `bool` or `None`. TODO Reminder when choosing a flag name: Pants will recognize the command line argument `--no-my-flag-name` as equivalent to `--my-flag-name=false`.
`IntOption`Must set `default` to an `int` or `None`.
`FloatOption`Must set `default` to a `float` or `None`.
`EnumOption`This is like `StrOption`, but with the valid choices constrained to your enum. To use, define an `enum.Enum`. The values of your enum will be what users can type, e.g. `'kale'` and `'spinach'` below: `python class LeafyGreens(Enum): KALE = "kale" SPINACH = "spinach" `You must either set `default` to a value from your enum or `None`. If you set `default=None`, you must set `enum_type`.
List options: - `StrListOption` - `BoolListOption` - `IntListOption` - `FloatListOption` - `EnumListOption`Default is `[]` if `default` is not set. For `EnumListOption`, you must set the keyword argument `enum_type`.
`DictOption`Default is `{}` if `default` is not set. Currently, Pants does not offer any validation of the dictionary entries, e.g. `dict[str, str]` vs `dict[str, list[str]]`. (Although per TOML specs, the key should always be `str`.) You may want to add eager validation that users are inputting options the correct way.
`ArgsListOption`Adds an `--args` option, e.g. `--isort-args`. This type is extra useful because it uses a special `shell_str` that lets users type the arguments as a single string with spaces, which Pants will _shlex_ for them. That is, `--args='arg1 arg2'` gets converted to `['arg1', 'arg2']`. You must set the keyword argument `example`, e.g. `'--arg1 arg2'`. You must also set `tool_name: str`, e.g. `'Black'`. You can optionally set `passthrough=True` if the user should be able to use the style `./pants my-goal :: -- --arg1`, i.e. arguments after `--`.

## Using options in rules

To use a `Subsystem` or `GoalSubsystem` in your rule, request it as a parameter. Then, use the class attributes to access the option value.