InputFlags

InputFlags is a collection of flags entered by the user. Its main purpose is to group and manage the set of flags passed with a command. InputFlags serves as a container that allows convenient retrieval, iteration, and checking of flag presence, as well as working with their values and validation statuses.

See also

Documentation for individual flags (Flag, InputFlag)

Documentation for InputFlags — a collection of processed flags entered by the user.

Documentation for Response — response object containing InputFlags

General information about flags and their usage in the Argenta application

---

Initialization

__init__(self, flags: list[InputFlag] | None = None) -> None

Creates a new collection of entered flags.

• flags: Optional list of flags of type InputFlag for initializing the collection. If not specified, an empty collection is created.

Warning

Instances of this class are usually not created directly. They are automatically formed by the system when processing user input and are accessible through the input_flags attribute of the Response object.

Attributes:

flags

List of all entered flags of type InputFlag. Empty if flags were not passed during initialization or the user did not enter them with the command.

Usage example:

from argenta import Command, Response, Router
from argenta.command import Flag, Flags


router = Router(title="Example")

@router.command(
    Command(
        "example",
        description="Example command with flags",
        flags=Flags([Flag("name"), Flag("age")]),
    )
)
def example_handler(response: Response):
    input_flags = response.input_flags

    if input_flags:
        print(f"Received {len(input_flags)} flag(s)")
    else:
        print("No flags provided")

---

Methods

get_flag_by_name

get_flag_by_name(self, name: str) -> InputFlag | None

Returns a flag by name.

param name:

Name of the flag to search for (without prefix).

return:

InputFlag object or None if the flag is not found.

The method returns the first flag with the corresponding name (ignoring the prefix).

Usage example:

from argenta import Command, Response, Router
from argenta.command import Flag, Flags

router = Router(title="Get Flag Example")


@router.command(
    Command(
        "config",
        description="Configure settings",
        flags=Flags([Flag("host"), Flag("port"), Flag("debug")]),
    )
)
def config_handler(response: Response):
    input_flags = response.input_flags

    host_flag = input_flags.get_flag_by_name("host")
    port_flag = input_flags.get_flag_by_name("port")
    debug_flag = input_flags.get_flag_by_name("debug")

    if host_flag:
        print(f"Host: {host_flag.input_value}")

    if port_flag:
        print(f"Port: {port_flag.input_value}")

    if debug_flag:
        print("Debug mode enabled")

    missing_flag = input_flags.get_flag_by_name("nonexistent")
    if missing_flag is None:
        print("Flag 'nonexistent' not found")

---

add_flag

add_flag(self, flag: InputFlag) -> None

Adds an entered flag to the collection.

param flag:

Flag of type InputFlag to add.

return:

None.

The method adds a flag to the end of the flags list. Used for dynamically extending the collection.

Note

This method is rarely used, as InputFlags is usually created automatically. However, it can be useful for testing or manual collection creation.

Usage example:

from argenta import Command, Response, Router
from argenta.command.flag import InputFlag, ValidationStatus
from argenta.command import InputFlags

router = Router(title="Add Flag Example")


@router.command(Command("test", description="Test command"))
def test_handler(response: Response):
    # Create new InputFlags collection
    new_flags = InputFlags()

    # Add one flag
    test_flag = InputFlag(
        name="test", prefix="--", input_value="value", status=ValidationStatus.VALID
    )
    new_flags.add_flag(test_flag)

    print(f"Flags count: {len(new_flags.flags)}")
    print(f"First flag: {new_flags.flags[0].name}")

---

add_flags

add_flags(self, flags: list[InputFlag]) -> None

Adds a list of entered flags to the collection.

param flags:

List of flags of type InputFlag to add.

return:

None.

The method extends the collection by adding all flags from the provided list. Efficient for batch addition.

Usage example:

from argenta.command.flag import InputFlag, ValidationStatus
from argenta.command import InputFlags

# Create InputFlags collection
flags = InputFlags()

# Create several flags
flag1 = InputFlag(name="option1", prefix="--", input_value="value1", status=ValidationStatus.VALID)

flag2 = InputFlag(name="option2", prefix="--", input_value="value2", status=ValidationStatus.VALID)

flag3 = InputFlag(name="option3", prefix="---", input_value="value3", status=ValidationStatus.VALID)

# Add all flags in one call
flags.add_flags([flag1, flag2, flag3])

print(f"Total flags: {len(flags.flags)}")
for flag in flags:
    print(f"  - {flag.string_entity}: {flag.input_value}")

---

Practical Examples

Processing All Flags with Status Checking

Usage example:

from argenta import Command, Response, Router
from argenta.command import Flag, Flags, InputFlag
from argenta.command.flag import ValidationStatus

router = Router(title="Comprehensive Example")


@router.command(
    Command(
        "validate",
        description="Validate all flags",
        flags=Flags(
            [
                Flag("format", possible_values=["json", "xml"]),
                Flag("output"),
                Flag("force"),
            ]
        ),
    )
)
def validate_handler(response: Response):
    input_flags = response.input_flags

    print("Flag validation results:")

    valid_flags: list[InputFlag] = []
    invalid_flags: list[InputFlag] = []
    undefined_flags: list[InputFlag] = []

    for flag in input_flags:
        if flag.status == ValidationStatus.VALID:
            valid_flags.append(flag)
            print(f"  ✓ {flag.string_entity}: {flag.input_value} (VALID)")
        elif flag.status == ValidationStatus.INVALID:
            invalid_flags.append(flag)
            print(f"  ✗ {flag.string_entity}: {flag.input_value} (INVALID)")
        elif flag.status == ValidationStatus.UNDEFINED:
            undefined_flags.append(flag)
            print(f"  ? {flag.string_entity}: {flag.input_value} (UNDEFINED)")

    print("\nSummary:")
    print(f"  Valid flags: {len(valid_flags)}")
    print(f"  Invalid flags: {len(invalid_flags)}")
    print(f"  Undefined flags: {len(undefined_flags)}")

    if valid_flags:
        print("\nProcessing valid flags:")
        for flag in valid_flags:
            print(f"  Processing {flag.name} = {flag.input_value}")