Options and subsystems
How to add options to your plugin.
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:
- Define a subclass of
Subsystem
frompants.subsystem.subsystem
.- 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
.
- This value will be prepended to all options in the subsystem, e.g.
- Set the class property
help
, which is used by./pants help
.
- Set the class property
- Add new options through
pants.options.option_types
class attributes. - Register the
Subsystem
withSubsystemRule
andregister.py
.- You don't need
SubsystemRule
if theSubsystem
is used in an@rule
becausecollect_rules()
will recognize it. It doesn't hurt to keep this around, though.
- You don't need
from pants.engine.rules import SubsystemRule
from pants.option.option_types import BoolOption
from pants.option.subsystem import Subsystem
class ShellcheckSubsystem(Subsystem):
options_scope = "shellcheck"
help = "The Shellcheck linter."
config_discovery = BoolOption(
"--config-discovery",
default=True,
advanced=True,
help="Whether Pants should...",
)
def rules():
return [SubsystemRule(ShellcheckSubsystem)]
from example import shellcheck
def rules():
return [*shellcheck.rules()]
The subsystem should now show up when you run ./pants help shellcheck
.
GoalSubsystem
As explained in Goal rules, goals use a subclass of
Subsystem
:GoalSubsystem
frompants.engine.goal
.
GoalSubsystem
behaves the same way as a normal subsystem, except that you set the class propertyname
rather thanoptions_scope
. Thename
will auto-populate theoptions_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 name | Notes |
---|---|
| Must set |
| Must set Reminder when choosing a flag name: Pants will recognize the command line argument |
| Must set |
| Must set |
| This is like To use, define an
You must either set |
List options:
| Default is For |
| Default is Currently, Pants does not offer any validation of the dictionary entries, e.g. |
| Adds an You must set the keyword argument You can optionally set |
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.
from pants.engine.rules import rule
...
@rule
async def demo(shellcheck: Shellcheck) -> LintResults:
if shellcheck.skip:
return LintResults()
config_discovery = shellcheck.config_discovery
...
Updated 2 months ago