Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.


ScenarioExample
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.