Flag Variants
Count Flags
A count flag increments a counter every time it appears. This is a common pattern for verbosity levels.
command.add_argument(
Argument("verbose", help="Increase verbosity (-v, -vv, -vvv)")
.long["verbose"]().short["v"]().count()
)
myapp -v # verbose = 1
myapp -vv # verbose = 2
myapp -vvv # verbose = 3
myapp --verbose # verbose = 1
myapp -v --verbose # verbose = 2 (short + long both increment)
myapp # verbose = 0 (default)
Retrieving: (Count)
var level = result.get_count("verbose") # Int
if level >= 2:
print("Debug-level output enabled")
Count flags are a special kind of boolean flag — calling .count()
automatically sets .flag() as well, so they don’t expect a value.
Merged short flags work seamlessly: -vvv is three occurrences of -v.
Count Ceiling (.max[N]())
You can cap a count flag at a maximum value with .max[n](). The ceiling value
n is a compile-time parameter (must be ≥ 1); invalid values are caught at
build time. Any occurrences beyond the ceiling are clamped to the maximum and a
warning is printed to stderr informing the user of the adjustment.
command.add_argument(
Argument("verbose", help="Increase verbosity (capped at 3)")
.long["verbose"]().short["v"]().count().max[3]()
)
myapp -vvv # verbose = 3
myapp -vvvvv # verbose = 3 (capped, warning printed)
myapp -vvvvvvvvvv # verbose = 3 (capped, warning printed)
myapp -vv # verbose = 2 (below ceiling, not affected)
The warning looks like:
warning: '--verbose' count 5 exceeds maximum 3, capped to 3
This is useful when verbosity levels above a certain threshold have no additional effect, or to prevent accidental over-counting. From users’ perspective, they get a clear warning rather than a hard error, which is friendlier than using the count option without a ceiling and silently ignoring extra occurrences.
Negatable Flags
A negatable flag automatically creates a --no-X counterpart. When the user
passes --X, the flag is set to True; when they pass --no-X, it is
explicitly set to False.
This replaces the manual pattern of defining two separate flags (--color and
--no-color) and a mutually exclusive group.
Defining a negatable flag
command.add_argument(
Argument("color", help="Enable colored output")
.long["color"]().flag().negatable()
)
myapp --color # color = True, has("color") = True
myapp --no-color # color = False, has("color") = True
myapp # color = False, has("color") = False (default)
Use result.has("color") to distinguish between “user explicitly disabled
colour” (--no-color) and “user didn’t mention colour at all”.
Help output
Negatable flags are displayed as a paired form:
--color / --no-color Enable colored output
Comparison with manual approach
Before (two flags + mutually exclusive):
command.add_argument(Argument("color", help="Force colored output").long["color"]().flag())
command.add_argument(Argument("no-color", help="Disable colored output").long["no-color"]().flag())
var group: List[String] = ["color", "no-color"]
command.mutually_exclusive(group^)
After (single negatable flag):
command.add_argument(
Argument("color", help="Enable colored output")
.long["color"]().flag().negatable()
)
The negatable approach is simpler and uses only one entry in ParseResult.
| Scenario | Example |
|---|---|
| Colour control | --color / --no-color |
| Feature toggle | --cache / --no-cache |
| Header inclusion | --headers / --no-headers |
| Interactive prompt | --interactive / --no-interactive |
Note: Only flags (
.flag()) can be made negatable. Calling.negatable()on a non-flag argument has no effect on parsing.