Flag

Flag is an entity describing a command flag. Its main purpose is to define flag parameters, including its name, prefix, and validation rules.

See also

Documentation for PossibleValues — an enumeration defining types of allowed values.

Documentation for InputFlag — an object representing a processed flag entered by the user.

General information about flags and their usage in Argenta

---

Initialization

__init__(
    self, name: str, *,
    prefix: Literal["-", "--", "---"] = "--",
    possible_values: list[str] | Pattern[str] | PossibleValues = PossibleValues.ALL,
) -> None

Creates a new flag for registration in a command.

• name: Flag name (required parameter).

• prefix: Flag prefix (-, --, ---). Defaults to --.

• possible_values: Value validation rules. Can be a list of strings, a regular expression, or a value from PossibleValues. Defaults to PossibleValues.ALL, meaning any value is allowed.

Attributes:

name

Flag name as a string.

prefix

Flag prefix. One of: "-", "--", "---".

possible_values

Allowed values for the flag.

Usage example:

import re
from argenta.command import Flag, PossibleValues

# Simple flag with any values
verbose_flag = Flag(name="verbose")

# Flag with short prefix
short_flag = Flag(name="v", prefix="-")

# Flag that does not take a value
help_flag = Flag(name="help", possible_values=PossibleValues.NEITHER)

# Flag with list of possible values
format_flag = Flag(name="format", possible_values=["json", "xml", "csv"])

# Flag with regexp for validation input value
email_flag = Flag(
    name="email",
    possible_values=re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"),
)

---

Properties

string_entity

@property
string_entity(self) -> str

Returns the string representation of the flag in the format prefix + name.

return:

String representation of the flag

This property combines the prefix and name into a single string that represents the flag as it would appear on the command line.

---

Magic Methods

__str__

__str__(self) -> str

Returns the string representation of the flag (similar to string_entity).

return:

String representation of the flag

Usage example:

from argenta.command import Flag

help_flag = Flag(name="help")
version_flag = Flag(name="V", prefix="-")

print(help_flag)  # --help

message = f"Use {help_flag} to see help"
print(message)  # Use --help to see help

---

__repr__

__repr__(self) -> str

Returns the debug representation of the object.

return:

String in the format Flag<prefix=..., name=...>.

Usage example:

from argenta.command import Flag

verbose_flag = Flag(name="verbose", prefix="--")
short_flag = Flag(name="v", prefix="-")

# Debug presentation
print(repr(verbose_flag))  # Flag<prefix=--, name=verbose>
print(repr(short_flag))  # Flag<prefix=-, name=v>

# In an interactive console or debugger
# >>> verbose_flag
# Flag<prefix=--, name=verbose>

---

__eq__

__eq__(self, other: object) -> bool

Compares two flags for equality based on their string representation (string_entity).

param other:

Object to compare

return:

True if flags are equal, otherwise False

Two flags are considered equal if their string_entity are identical.

Usage example:

from argenta.command import Flag, PossibleValues

# Creating two flags with the same name and prefix
flag1 = Flag(name="verbose", prefix="--")
flag2 = Flag(name="verbose", prefix="--")

# Flag comparison
print(flag1 == flag2)  # True

# Flags with different prefixes are not equal
flag3 = Flag(name="verbose", prefix="-")
print(flag1 == flag3)  # False

# Flags with different names are not equal
flag4 = Flag(name="help", prefix="--")
print(flag1 == flag4)  # False

# Different possible_values do not affect equality
flag5 = Flag(name="verbose", prefix="--", possible_values=PossibleValues.NEITHER)
flag6 = Flag(name="verbose", prefix="--", possible_values=["value1", "value2"])
print(flag5 == flag6)

---

PredefinedFlags

argenta.command.PredefinedFlags

The PredefinedFlags class provides a set of ready-made flags for use in applications without manual creation. These flags cover common scenarios.

All predefined flags are class attributes and represent ready-made Flag instances.

---

Informational Flags

PredefinedFlags.HELP

Flag for displaying help: --help

• name: "help"

• prefix: "--" (default)

• possible_values: PossibleValues.NEITHER

PredefinedFlags.SHORT_HELP

Short version of the help flag: -H

• name: "H"

• prefix: "-"

• possible_values: PossibleValues.NEITHER

PredefinedFlags.INFO

Flag for displaying information: --info

• name: "info"

• prefix: "--" (default)

• possible_values: PossibleValues.NEITHER

PredefinedFlags.SHORT_INFO

Short version of the info flag: -I

• name: "I"

• prefix: "-"

• possible_values: PossibleValues.NEITHER

---

Selection Flags

PredefinedFlags.ALL

Flag for selecting all items: --all

• name: "all"

• prefix: "--"

• possible_values: PossibleValues.NEITHER

PredefinedFlags.SHORT_ALL

Short version of the select all flag: -A

• name: "A"

• prefix: "-"

• possible_values: PossibleValues.NEITHER

---

Network Flags

PredefinedFlags.HOST

Flag for specifying host IP address: --host

• name: "host"

• prefix: "--" (default)

• possible_values: Regular expression for IPv4 validation: r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"

PredefinedFlags.SHORT_HOST

Short version of the host flag: -H

• name: "H"

• prefix: "-"

• possible_values: Regular expression for IPv4 validation: r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"

PredefinedFlags.PORT

Flag for specifying port: --port

• name: "port"

• prefix: "--" (default)

• possible_values: Regular expression for port validation: r"^\d{1,5}$"

PredefinedFlags.SHORT_PORT

Short version of the port flag: -P

• name: "P"

• prefix: "-"

• possible_values: Regular expression for port validation: r"^\d{1,5}$"

---

Usage example:

from argenta.command import Flags, PredefinedFlags

# Using predefined flags when creating a command
command_flags = Flags(
    [
        PredefinedFlags.HELP,
        PredefinedFlags.SHORT_HELP,
        PredefinedFlags.INFO,
    ]
)

# Using Network Flags
network_flags = Flags(
    [
        PredefinedFlags.HOST,
        PredefinedFlags.PORT,
    ]
)

# Validating the values of predefined flags
print(PredefinedFlags.HOST.validate_input_flag_value("192.168.1.1"))  # True
print(PredefinedFlags.HOST.validate_input_flag_value("invalid"))  # False

print(PredefinedFlags.PORT.validate_input_flag_value("8080"))  # True
print(PredefinedFlags.PORT.validate_input_flag_value("99999"))  # True
print(PredefinedFlags.PORT.validate_input_flag_value("abc"))  # False

# Flags without values
print(PredefinedFlags.HELP.validate_input_flag_value(None))  # True
print(PredefinedFlags.HELP.validate_input_flag_value("something"))  # False

# Checking string representations
print(PredefinedFlags.HELP.string_entity)  # --help
print(PredefinedFlags.SHORT_HELP.string_entity)  # -H
print(PredefinedFlags.HOST.string_entity)  # --host
print(PredefinedFlags.SHORT_PORT.string_entity)  # -P