API Reference

Complete API documentation for argclass.

Quick Reference

Most users only need these:

What you want

What to use

Create a CLI parser

class MyApp(argclass.Parser)

Group related arguments

class MyGroup(argclass.Group)

Customize an argument

argclass.Argument(...)

Handle sensitive values

argclass.Secret(...) or argclass.Argument(..., secret=True)

Load config file argument

argclass.Config(...)

Set log level argument

argclass.LogLevel

Primary API

These are the main classes and functions you’ll use in most applications.

Parser

The base class for creating CLI parsers. Define arguments as class attributes with type hints.

import argclass

class MyApp(argclass.Parser):
    name: str                    # Required argument
    count: int = 1               # Optional with default
    verbose: bool = False        # Boolean flag

app = MyApp()
app.parse_args(["--name", "test"])
assert app.name == "test"
assert app.count == 1
assert app.verbose is False
class argclass.Parser(config_files=(), auto_env_var_prefix=None, strict_config=False, config_parser_class=<class 'argclass.defaults.INIDefaultsParser'>, **kwargs)[source]

Bases: AbstractParser, Base

Main parser class for command-line argument parsing.

Parameters:
HELP_APPENDIX_PREAMBLE = ' Default values will based on following configuration files {configs}. '
HELP_APPENDIX_CURRENT = 'Now {num_existent} files has been applied {existent}. '
HELP_APPENDIX_END = 'The configuration files is INI-formatted files where configuration groups is INI sections. See more https://docs.argclass.com/config-files.html'
static get_cli_name(name)[source]
Parameters:

name (str)

Return type:

str

get_env_var(name, argument)[source]
Parameters:
Return type:

Optional[str]

__init__(config_files=(), auto_env_var_prefix=None, strict_config=False, config_parser_class=<class 'argclass.defaults.INIDefaultsParser'>, **kwargs)[source]
Parameters:
property current_subparser: AbstractParser | None
create_parser()[source]

Create an ArgumentParser instance without parsing arguments. Can be used to inspect the parser structure in external integrations. NOT AN ALTERNATIVE TO parse_args, because it does not back populates the parser attributes.

Return type:

ArgumentParser

parse_args(args=None, sanitize_secrets=False)[source]
Parameters:
Return type:

TypeVar(ParserType, bound= Parser)

print_help()[source]
Return type:

None

sanitize_env(only_secrets=False)[source]
Parameters:

only_secrets (bool)

Return type:

None

Group

Bundle related arguments under a common prefix. Groups can be reused across multiple parsers.

import argclass

class DatabaseGroup(argclass.Group):
    host: str = "localhost"
    port: int = 5432

class MyApp(argclass.Parser):
    db = DatabaseGroup()  # Arguments: --db-host, --db-port

app = MyApp()
app.parse_args(["--db-host", "prod.example.com"])
assert app.db.host == "prod.example.com"
assert app.db.port == 5432
class argclass.Group(title=None, description=None, prefix=None, defaults=None)[source]

Bases: AbstractGroup, Base

Argument group for organizing related arguments.

Parameters:
__init__(title=None, description=None, prefix=None, defaults=None)[source]
Parameters:

Argument

Customize argument behavior: add help text, aliases, choices, and more.

import argclass

class MyApp(argclass.Parser):
    name: str = argclass.Argument(
        "-n", "--name",
        help="User name",
    )
    level: str = argclass.Argument(
        default="info",
        choices=["debug", "info", "warning", "error"],
    )

app = MyApp()
app.parse_args(["-n", "Alice", "--level", "debug"])
assert app.name == "Alice"
assert app.level == "debug"
argclass.Argument(*aliases, action=Actions.STORE, choices=None, const=None, converter=None, default=None, env_var=None, help=None, metavar=None, nargs=None, required=None, secret=False, type=None, **extra_kwargs)[source]
Overloads:

  • aliases (str), type (ConverterType), nargs (NargsType), converter (Callable[…, R]), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), default (Optional[Any]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), required (Optional[bool]), secret (bool), extra_kwargs (Any) → R

  • aliases (str), type (Type[T]), nargs (Literal[‘?’]), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), converter (None), default (Optional[Any]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), required (Optional[bool]), secret (bool), extra_kwargs (Any) → T

  • aliases (str), type (Callable[[str], T]), nargs (Literal[‘?’]), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), converter (None), default (Optional[Any]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), required (Optional[bool]), secret (bool), extra_kwargs (Any) → T

  • aliases (str), type (Type[T]), nargs (Union[Literal[‘*’, ‘+’], int, Nargs]), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), converter (None), default (Optional[Any]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), required (Optional[bool]), secret (bool), extra_kwargs (Any) → List[T]

  • aliases (str), type (Callable[[str], T]), nargs (Union[Literal[‘*’, ‘+’], int, Nargs]), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), converter (None), default (Optional[Any]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), required (Optional[bool]), secret (bool), extra_kwargs (Any) → List[T]

  • aliases (str), type (Type[T]), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), converter (None), default (Optional[T]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), nargs (None), required (Optional[bool]), secret (bool), extra_kwargs (Any) → T

  • aliases (str), type (Callable[[str], T]), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), converter (None), default (Optional[T]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), nargs (None), required (Optional[bool]), secret (bool), extra_kwargs (Any) → T

  • aliases (str), converter (Callable[…, T]), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), default (Optional[Any]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), nargs (Optional[NargsType]), required (Optional[bool]), secret (bool), type (Optional[ConverterType]), extra_kwargs (Any) → T

  • aliases (str), action (Union[Actions, Type[Action]]), choices (Optional[Iterable[str]]), const (Optional[Any]), converter (Optional[ConverterType]), default (Optional[Any]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[MetavarType]), nargs (Optional[NargsType]), required (Optional[bool]), secret (bool), type (Optional[ConverterType]), extra_kwargs (Any) → Any

Parameters:
Return type:

Any

Create a typed argument for a Parser or Group class.

Dispatches to ArgumentSingle or ArgumentSequence based on nargs.

Args:

aliases: Command-line aliases (e.g., “-n”, “–name”). action: How to handle the argument (store, store_true, etc.). choices: Restrict values to these options. const: Constant value for store_const/append_const actions. converter: Post-parse transform function. With nargs, receives the list. default: Default value if argument not provided. env_var: Environment variable to read default from. help: Help text for –help output. metavar: Placeholder name in help text. nargs: Number of values (int, “?”, “*”, “+”, or Nargs enum). required: Whether the argument must be provided. secret: If True, hide value from help and wrap str in SecretString. type: Per-value converter for argparse. With nargs, called per value.

Returns:

TypedArgument instance.

Example:

# type: converts each CLI value individually
numbers = Argument(nargs="+", type=int)
# Parsing ["1", "2"] -> calls int("1"), int("2") -> [1, 2]

# converter: transforms the final result after type conversion
unique = Argument(nargs="+", type=int, converter=set)
# Parsing ["1", "2", "1"] -> [1, 2, 1] -> set([1, 2, 1]) -> {1, 2}

# Combining type and converter for set[int]:
class Parser(argclass.Parser):
    numbers: set[int] = Argument(
        type=int,       # Convert each "1", "2" to int
        converter=set,  # Convert [1, 2, 1] to {1, 2}
        nargs="+",
    )

# Alternative: single converter function for set[int]:
class Parser(argclass.Parser):
    numbers: set[int] = Argument(
        converter=lambda vals: set(map(int, vals)),
        nargs="+",
    )
Parameters:
Return type:

Any

Secret

Handle sensitive values that should be masked in logs and removed from environment after parsing.

import os
import argclass

os.environ["TEST_API_KEY"] = "secret123"

class MyApp(argclass.Parser):
    api_key: str = argclass.Secret(env_var="TEST_API_KEY")

app = MyApp()
# Use sanitize_secrets=True to auto-remove secret env vars during parsing
app.parse_args([], sanitize_secrets=True)
assert repr(app.api_key) == "'******'"  # Masked in repr / logs
assert app.api_key == "secret123"        # But actual value is accessible
assert "TEST_API_KEY" not in os.environ  # Already removed

Alternatively, call sanitize_env() manually after parsing:

import os
import argclass

os.environ["TEST_API_KEY"] = "secret123"

class MyApp(argclass.Parser):
    api_key: str = argclass.Secret(env_var="TEST_API_KEY")

app = MyApp()
app.parse_args([])
app.sanitize_env()                   # Remove all used env vars
assert "TEST_API_KEY" not in os.environ

# Or use: app.sanitize_env(only_secrets=True) to keep non-secret env vars
argclass.Secret(*aliases, action=Actions.STORE, choices=None, const=None, converter=None, default=None, env_var=None, help=None, metavar=None, nargs=None, required=None, type=None)[source]

Create a secret argument that masks sensitive values.

Secret arguments are wrapped in SecretString, which:

  • Returns '******' for repr() to prevent accidental logging

  • Supports equality comparison without exposing the value

  • Use str() to access the actual value when needed

Use parser.sanitize_env() after parsing to remove secret environment variables before spawning subprocesses.

Args:

aliases: Command-line aliases (e.g., “-p”, “–password”). env_var: Environment variable to read the secret from. default: Default value if not provided. help: Help text (the actual value is never shown).

Returns:

TypedArgument with secret=True.

Example:

class Parser(argclass.Parser):
    api_key: str = argclass.Secret(env_var="API_KEY")
    password: str = argclass.Secret()

parser = Parser()
parser.parse_args()
parser.sanitize_env()  # Remove secrets from environment

# Safe: shows '******'
print(f"API key: {parser.api_key!r}")

# Access actual value
connect(api_key=str(parser.api_key))
Parameters:
Return type:

Any

SecretString

The type returned for Secret arguments. Masks value in str() and repr().

class argclass.SecretString[source]

Bases: str

The class mimics the string, with one important difference. Attempting to call __str__ of this instance will result in the output of placeholer (the default is “**”) if the call stack contains of logging module. In other words, this is an attempt to keep secrets out of the log.

However, if you try to do an f-string or str() at the moment the parameter is passed to the log, the value will be received, because there is nothing about logging in the stack.

The repr will always give placeholder, so it is better to always add !r for any f-string, for example f’{value!r}’.

Examples:

>>> import logging
>>> import sys
>>> from argclass import SecretString
>>> logging.basicConfig(level=logging.INFO, stream=sys.stdout, force=True)
>>> s = SecretString("my-secret-password")
>>> logging.info(s)          # __str__ will be called from logging
INFO:root:******
>>> logging.info(f"s=%s", s) # __str__ will be called from logging too
INFO:root:s=******
>>> logging.info(f"{s!r}")   # repr is safe
INFO:root:'******'
>>> logging.info(f"{s}")     # the password will be compromised
INFO:root:my-secret-password
PLACEHOLDER = '******'
MODULES_SKIPLIST = ('logging', 'log.py')
__str__()[source]

Return str(self).

Return type:

str

__repr__()[source]

Return repr(self).

Return type:

str

Configuration Files

Load defaults from INI, JSON, or TOML configuration files.

Config

Add a --config argument that loads structured data from a file. Access values via dict-like interface (parser.config["key"]).

import argclass
from pathlib import Path
from tempfile import NamedTemporaryFile

class MyApp(argclass.Parser):
    config = argclass.Config(config_class=argclass.JSONConfig)
    verbose: bool = False

# Create a temporary config file
with NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
    f.write('{"database": {"host": "example.com", "port": 9000}}')
    config_path = f.name

app = MyApp()
app.parse_args(["--config", config_path])

# Access config data via dict-like interface
assert app.config["database"]["host"] == "example.com"
assert app.config["database"]["port"] == 9000

Path(config_path).unlink()

Tip

For loading defaults into parser attributes, use config_files parameter instead. See Config File Parsers.

argclass.Config(*aliases, search_paths=None, choices=None, converter=None, const=None, default=None, env_var=None, help=None, metavar=None, nargs=None, required=None, config_class=<class 'argclass.store.INIConfig'>)[source]

Create a configuration file argument.

This creates a --config argument that loads structured data from a file. The loaded data is accessible as a dict-like object.

Note:

This is different from config_files parameter on Parser, which presets CLI argument defaults. This argument loads arbitrary configuration data for your application.

Args:

aliases: Command-line aliases (default: “–config”). search_paths: Default paths to search for config files. config_class: Parser class (INIConfig, JSONConfig, TOMLConfig). env_var: Environment variable for config file path. help: Help text for –help output.

Returns:

ConfigArgument instance.

Example:

class Parser(argclass.Parser):
    config = argclass.Config(config_class=argclass.JSONConfig)

parser = Parser()
parser.parse_args(["--config", "settings.json"])

# Access loaded configuration
db_host = parser.config["database"]["host"]
Parameters:
Return type:

Any

Config Argument Classes

Class

Format

Usage

INIConfig

INI files

config_class=argclass.INIConfig

JSONConfig

JSON files

config_class=argclass.JSONConfig

TOMLConfig

TOML files

config_class=argclass.TOMLConfig
class argclass.INIConfig(**kwargs)[source]

Bases: ConfigArgument

Parse INI file and set results as a value.

Parameters:

kwargs (Any)

action

alias of INIConfigAction

class argclass.JSONConfig(**kwargs)[source]

Bases: ConfigArgument

Parse JSON file and set results as a value.

Parameters:

kwargs (Any)

action

alias of JSONConfigAction

Note

TOML requires tomllib (Python 3.11+) or tomli package (Python 3.10).

class argclass.TOMLConfig(**kwargs)[source]

Bases: ConfigArgument

Parse TOML file and set results as a value.

Uses stdlib tomllib (Python 3.11+) or tomli package as fallback.

Parameters:

kwargs (Any)

action

alias of TOMLConfigAction

Config File Parsers

Used with config_parser_class parameter in Parser() to load defaults from config files at parser initialization.

import argclass
from pathlib import Path
from tempfile import NamedTemporaryFile

class MyApp(argclass.Parser):
    host: str = "localhost"
    port: int = 8080

# Create a temporary config file
with NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
    f.write('{"host": "db.example.com", "port": 5432}')
    config_path = f.name

app = MyApp(
    config_files=[config_path],
    config_parser_class=argclass.JSONDefaultsParser,
)
app.parse_args([])
assert app.host == "db.example.com"
assert app.port == 5432

Path(config_path).unlink()

Class

Format

INIDefaultsParser

INI files (default)

JSONDefaultsParser

JSON files

TOMLDefaultsParser

TOML files
class argclass.INIDefaultsParser(paths, strict=False)[source]

Bases: AbstractDefaultsParser

Parse INI configuration files for default values.

This is the default parser used by argclass. It uses Python’s configparser module to read INI files.

INI sections map to argument groups, and the [DEFAULT] section contains top-level argument defaults.

Values that look like Python literals (lists, bools) are converted when requested via get_value() with appropriate ValueKind.

Parameters:
BOOL_TRUE_VALUES = frozenset({'1', 'enable', 'enabled', 'on', 't', 'true', 'y', 'yes'})
parse()[source]

Parse configuration files and return defaults mapping.

Return type:

Mapping[str, Any]

Returns:

A mapping where keys are argument names or group names, and values are either default values (str) or nested mappings for groups.

class argclass.JSONDefaultsParser(paths, strict=False)[source]

Bases: AbstractDefaultsParser

Parse JSON configuration files for default values.

The JSON structure should be a flat or nested object where: - Top-level keys are argument names or group names - Group values are objects with argument names as keys

JSON natively supports lists and booleans, so no conversion needed.

Parameters:
parse()[source]

Parse configuration files and return defaults mapping.

Return type:

Mapping[str, Any]

Returns:

A mapping where keys are argument names or group names, and values are either default values (str) or nested mappings for groups.

class argclass.TOMLDefaultsParser(paths, strict=False)[source]

Bases: AbstractDefaultsParser

Parse TOML configuration files for default values.

Uses stdlib tomllib (Python 3.11+) or tomli package as fallback.

The TOML structure should be: - Top-level keys are argument names - Tables (sections) map to argument groups

TOML natively supports lists and booleans, so no conversion needed.

Parameters:
parse()[source]

Parse configuration files and return defaults mapping.

Return type:

Mapping[str, Any]

Returns:

A mapping where keys are argument names or group names, and values are either default values (str) or nested mappings for groups.

Pre-built Arguments

LogLevel

A pre-configured argument for log levels. Accepts level names and returns the corresponding logging module constant.

import argclass
import logging

class MyApp(argclass.Parser):
    log_level: int = argclass.LogLevel

app = MyApp()
app.parse_args(["--log-level", "debug"])
assert app.log_level == logging.DEBUG

app.parse_args(["--log-level", "warning"])
assert app.log_level == logging.WARNING

Accepts the lowercase enum member names: debug, info, warning, error, critical, notset.

class argclass.LogLevelEnum(*values)[source]

Bases: IntEnum

Standard logging levels.

CRITICAL = 50
FATAL = 50
ERROR = 40
WARNING = 30
WARN = 30
INFO = 20
DEBUG = 10
NOTSET = 0

Enums and Constants

Actions

Argument actions (mirrors argparse actions).

Action

Description

STORE

Store the value (default)

STORE_TRUE

Store True when flag is present

STORE_FALSE

Store False when flag is present

APPEND

Append value to a list

COUNT

Count occurrences
class argclass.Actions(*values)[source]

Bases: str, Enum

Argparse action types.

STORE = 'store'
STORE_CONST = 'store_const'
STORE_TRUE = 'store_true'
STORE_FALSE = 'store_false'
APPEND = 'append'
APPEND_CONST = 'append_const'
COUNT = 'count'
HELP = 'help'
VERSION = 'version'
classmethod default()[source]
Return type:

Actions

Nargs

Number of arguments constants.

Value

Meaning

ZERO_OR_ONE (?)

Zero or one argument

ZERO_OR_MORE (*)

Zero or more arguments

ONE_OR_MORE (+)

One or more arguments
class argclass.Nargs(*values)[source]

Bases: Enum

Argparse nargs values.

ZERO_OR_ONE = '?'
ZERO_OR_MORE = '*'
ONE_OR_MORE = '+'

Utility Functions

parse_bool

Parse boolean strings from environment variables or config files.

from argclass import parse_bool

assert parse_bool("true") is True
assert parse_bool("yes") is True
assert parse_bool("1") is True
assert parse_bool("on") is True

assert parse_bool("false") is False
assert parse_bool("no") is False
assert parse_bool("0") is False
assert parse_bool("off") is False
argclass.parse_bool(value)[source]

Parse a string to boolean.

Parameters:

value (str)

Return type:

bool

read_configs

Read and merge multiple configuration files.

argclass.read_configs(*paths, **kwargs)

Read configuration from INI files.

Parameters:
Return type:

Tuple[Mapping[str, Any], Tuple[Path, ...]]

Exceptions

argclass provides a hierarchy of typed exceptions for debugging configuration and parsing errors. All exceptions include structured context attributes.

ArgclassError

Base exception for all argclass errors. Provides field_name and hint attributes for debugging context.

class argclass.ArgclassError(message, *, field_name=None, hint=None)[source]

Bases: Exception

Base exception for all argclass errors.

Provides structured context for debugging configuration issues. All argclass exceptions inherit from this class.

Attributes:

message: The error message describing what went wrong. field_name: The name of the field that caused the error, if applicable. hint: A suggestion for how to fix the error, if available.

Example:

try:
    # ... argclass operation that may fail
    pass
except ArgclassError as e:
    print(f"Error: {e}")
    if e.field_name:
        print(f"Field: {e.field_name}")
    if e.hint:
        print(f"Hint: {e.hint}")
Parameters:
__init__(message, *, field_name=None, hint=None)[source]
Parameters:

ArgumentDefinitionError

Raised when an argument cannot be added to the parser due to invalid configuration, such as conflicting option strings or invalid argparse kwargs.

class argclass.ArgumentDefinitionError(message, *, field_name=None, aliases=None, kwargs=None, hint=None)[source]

Bases: ArgclassError

Error in argument definition or registration with argparse.

Raised when an argument cannot be added to the parser due to invalid configuration (conflicting options, invalid types, etc.).

Attributes:

aliases: The conflicting aliases, e.g., ("-v", "--verbose"). kwargs: The kwargs passed to argparse when the error occurred.

Example:

# This exception is typically raised during parser construction
# when argument definitions conflict:
try:
    class Parser(argclass.Parser):
        verbose: bool = argclass.Argument("-h")  # conflicts with --help
except ArgumentDefinitionError as e:
    print(f"Conflict: {e.aliases}")
Parameters:
__init__(message, *, field_name=None, aliases=None, kwargs=None, hint=None)[source]
Parameters:

TypeConversionError

Raised when a value cannot be converted to the expected type. Includes the original value and target_type for debugging.

class argclass.TypeConversionError(message, *, field_name=None, value=None, target_type=None, hint=None)[source]

Bases: ArgclassError

Error during type conversion of argument values.

Raised when a value cannot be converted to the expected type, either by the type function or a custom converter.

Attributes:

value: The original value that failed conversion. target_type: The type that the value was being converted to.

Example:

try:
    # When a custom converter fails:
    def strict_port(value: str) -> int:
        port = int(value)
        if not (1 <= port <= 65535):
            raise TypeConversionError(
                "Port must be between 1 and 65535",
                field_name="port",
                value=value,
                target_type=int,
                hint="Use a valid port number (1-65535)",
            )
        return port
except TypeConversionError as e:
    print(f"Invalid value: {e.value!r} for type {e.target_type}")
Parameters:
__init__(message, *, field_name=None, value=None, target_type=None, hint=None)[source]
Parameters:

ConfigurationError

Raised when a configuration file cannot be parsed or contains values that don’t match expected types. Includes file_path and section attributes.

class argclass.ConfigurationError(message, *, field_name=None, file_path=None, section=None, hint=None)[source]

Bases: ArgclassError

Error loading or parsing configuration files.

Raised when a configuration file cannot be parsed or contains invalid values for the expected argument types.

Attributes:

file_path: Path to the configuration file that caused the error. section: The config section (e.g., INI section) where error occurred.

Example:

try:
    parser = Parser(
        config_files=["config.ini"],
        config_parser_class=argclass.INIDefaultsParser,
    )
except ConfigurationError as e:
    print(f"Config error in {e.file_path}")
    if e.section:
        print(f"Section: [{e.section}]")
Parameters:
__init__(message, *, field_name=None, file_path=None, section=None, hint=None)[source]
Parameters:

EnumValueError

Raised when an enum default or parsed value is not a valid member of the specified enum class. Includes enum_class and valid_values for diagnostics.

class argclass.EnumValueError(message, *, field_name=None, enum_class=None, valid_values=None, hint=None)[source]

Bases: ArgclassError

Error with enum argument value or default.

Raised when an enum default or value is not a valid member of the specified enum class.

Attributes:

enum_class: The enum class that was expected. valid_values: Tuple of valid enum member names.

Example:

from enum import Enum

class Color(Enum):
    RED = "red"
    GREEN = "green"

try:
    class Parser(argclass.Parser):
        # "YELLOW" is not a valid Color member
        color: Color = argclass.EnumArgument(Color, default="YELLOW")
except EnumValueError as e:
    print(f"Invalid value for {e.enum_class.__name__}")
    print(f"Valid options: {', '.join(e.valid_values)}")
Parameters:
__init__(message, *, field_name=None, enum_class=None, valid_values=None, hint=None)[source]
Parameters:

ComplexTypeError

Raised when a type annotation is too complex to be automatically handled (e.g., Union[str, int]) and requires an explicit converter.

class argclass.ComplexTypeError(message, *, field_name=None, typespec=None, hint=None)[source]

Bases: ArgclassError

Error with complex type annotations.

Raised when a type annotation is too complex to be automatically handled and requires explicit converter specification.

Attributes:

typespec: The type annotation that could not be handled.

Example:

try:
    class Parser(argclass.Parser):
        # Union types (other than T | None) are not supported
        value: str | int  # Raises ComplexTypeError
except ComplexTypeError as e:
    print(f"Cannot handle type: {e.typespec}")
    print("Provide an explicit converter with type=...")
Parameters:
__init__(message, *, field_name=None, typespec=None, hint=None)[source]
Parameters:

Advanced / Internal

These classes are primarily for advanced use cases or extending argclass.

Base

Abstract base class for both Parser and Group.

class argclass.Base[source]

Bases: object

Base class for Parser and Group.

AbstractDefaultsParser

Base class for implementing custom config file parsers.

class argclass.AbstractDefaultsParser(paths, strict=False)[source]

Bases: ABC

Abstract base class for parsing configuration files into defaults.

Subclass this to implement custom configuration file formats for the config_files parameter of Parser.

Parameters:
__init__(paths, strict=False)[source]
Parameters:
property loaded_files: Tuple[Path, ...]

Return tuple of successfully loaded file paths.

abstractmethod parse()[source]

Parse configuration files and return defaults mapping.

Return type:

Mapping[str, Any]

Returns:

A mapping where keys are argument names or group names, and values are either default values (str) or nested mappings for groups.

get_value(key, kind=ValueKind.STRING, section=None)[source]

Get value with type validation.

The section argument may contain dots to address nested groups (e.g. "endpoint.credentials"). Resolution tries a literal key match first (so INI section names with dots work), then falls back to splitting on . and descending through nested dicts (JSON/TOML).

Args:

key: The config key name. kind: Expected value type for validation. section: Optional section/group name for nested values.

Returns:

The value, converted if necessary (e.g., INI literal_eval).

Raises:

UnexpectedConfigValue: If value doesn’t match expected kind.

Parameters:
Return type:

Any

ValueKind

Enum specifying expected value types for config file loading.

Value

Description

STRING

Default, no conversion

SEQUENCE

Lists/tuples or any iterable container

BOOL

Boolean values
class argclass.ValueKind(*values)[source]

Bases: IntEnum

Expected value type for config loading.

STRING = 0
SEQUENCE = 1
BOOL = 2

UnexpectedConfigValue

Exception raised when a config value doesn’t match the expected type.

class argclass.UnexpectedConfigValue(key, expected, value)[source]

Bases: ConfigurationError

Config value doesn’t match expected type.

Parameters:
__init__(key, expected, value)[source]
Parameters:

ConfigArgument

Base class for config file argument types.

class argclass.ConfigArgument(**kwargs)[source]

Bases: TypedArgument

Argument for configuration file loading.

Parameters:

kwargs (Any)

search_paths: Iterable[str | Path] | None = None

ConfigAction

Action class for config file arguments.

class argclass.ConfigAction(option_strings, dest, search_paths=(), type=mappingproxy({}), help='', required=False, default=None)[source]

Bases: Action

Base action for loading configuration files.

Parameters:
__init__(option_strings, dest, search_paths=(), type=mappingproxy({}), help='', required=False, default=None)[source]
Parameters:
parse(*files)[source]
Parameters:

files (Path)

Return type:

Any

parse_file(file)[source]
Parameters:

file (Path)

Return type:

Any

TypedArgument

Internal class representing a typed argument.

class argclass.TypedArgument(**kwargs)[source]

Bases: ArgumentBase

Argument with type information.

Parameters:

kwargs (Any)

action: Actions | Type[Action] = 'store'
aliases: Iterable[str] = frozenset({})
choices: Iterable[str] | None = None
const: Any | None = None
converter: Callable[[Any], Any] | None = None
default: Any | None = None
secret: bool = False
env_var: str | None = None
extra_kwargs: Mapping[str, Any] = mappingproxy({})
help: str | None = None
metavar: str | None = None
nargs: int | Nargs | None = None
required: bool | None = None
type: Any = None
property is_nargs: bool
property has_default: bool

Check if the argument has a meaningful default value.

Returns False if default is None or Ellipsis (the “no default” sentinel).

Store

Internal storage for argument metadata.

class argclass.Store(**kwargs)[source]

Bases: object

Base class for typed storage with field validation.

Parameters:

kwargs (Any)

Return type:

Store

copy(**overrides)[source]
Parameters:

overrides (Any)

Return type:

Any

as_dict()[source]
Return type:

Dict[str, Any]

Specialized Argument Functions

argclass.ArgumentSingle(*aliases, type, action=Actions.STORE, choices=None, const=None, converter=None, default=None, env_var=None, help=None, metavar=None, required=None, secret=False, **extra_kwargs)[source]

Create a single-value argument with precise typing.

Use this when you need exact type inference for a single value. The type parameter is required and determines the return type.

Any extra keyword arguments are passed through to argparse.ArgumentParser.add_argument (e.g., version='1.0' for action=Actions.VERSION).

Example:
class Parser(argclass.Parser):

count: int = argclass.ArgumentSingle(type=int, default=10) name: str = argclass.ArgumentSingle(type=str)

Parameters:
Return type:

TypeVar(T)

argclass.ArgumentSequence(*aliases, type, nargs=Nargs.ONE_OR_MORE, action=Actions.STORE, choices=None, const=None, converter=None, default=None, env_var=None, help=None, metavar=None, required=None, secret=False, **extra_kwargs)[source]

Create a multi-value argument with precise typing.

Use this when you need exact type inference for a list of values. The type parameter is required and determines the element type.

Any extra keyword arguments are passed through to argparse.ArgumentParser.add_argument.

Args:
nargs: Number of values. Defaults to “+” (one or more).

Use “*” for zero or more, or an int for exact count.

Example:

class Parser(argclass.Parser):
    files: list[str] = argclass.ArgumentSequence(type=str)
    numbers: list[int] = argclass.ArgumentSequence(
        type=int, nargs="*", default=[]
    )
Parameters:
Return type:

List[TypeVar(T)]

EnumArgument

Create arguments from Enum classes with automatic choice validation.

import argclass
from enum import IntEnum

class Priority(IntEnum):
    LOW = 1
    MEDIUM = 2
    HIGH = 3

class MyApp(argclass.Parser):
    # Default can be enum member or string name
    priority: Priority = argclass.EnumArgument(
        Priority, default="MEDIUM"
    )

app = MyApp()
app.parse_args([])
assert app.priority == Priority.MEDIUM

app.parse_args(["--priority", "HIGH"])
assert app.priority == Priority.HIGH

Use lowercase=True for case-insensitive input:

import argclass
from enum import IntEnum

class Level(IntEnum):
    DEBUG = 10
    INFO = 20
    WARNING = 30

class MyApp(argclass.Parser):
    level: Level = argclass.EnumArgument(
        Level, default="info", lowercase=True
    )

app = MyApp()
app.parse_args([])
assert app.level == Level.INFO

# Accepts lowercase input
app.parse_args(["--level", "debug"])
assert app.level == Level.DEBUG
argclass.EnumArgument(enum_class, *aliases, action=Actions.STORE, default=None, env_var=None, help=None, metavar=None, nargs=None, required=None, use_value=False, lowercase=False)[source]
Overloads:

  • enum_class (Type[E]), aliases (str), default (Union[E, str]), action (Union[Actions, Type[Action]]), env_var (Optional[str]), help (Optional[str]), metavar (Optional[str]), nargs (Optional[NargsType]), required (Optional[bool]), use_value (bool), lowercase (bool) → E

  • enum_class (Type[E]), aliases (str), action (Union[Actions, Type[Action]]), default (None), env_var (Optional[str]), help (Optional[str]), metavar (Optional[str]), nargs (Optional[NargsType]), required (Optional[bool]), use_value (bool), lowercase (bool) → Optional[E]

Parameters:
Return type:

Any

Create an argument from an Enum class.

Args:

enum_class: The Enum class to use for choices and conversion. aliases: Command-line aliases (e.g., “-l”, “–level”). action: How to handle the argument. default: Default value as enum member or string name. env_var: Environment variable to read default from. help: Help text for –help output. metavar: Placeholder name in help text. nargs: Number of values. required: Whether the argument must be provided. use_value: If True, return enum.value instead of enum member. lowercase: If True, use lowercase choices and accept lowercase input.

Returns:

TypedArgument instance.

Parameters:
Return type:

Any

Config Generation

Classes for writing config files from a parser (the inverse of config_files= reading). See Generating Config Files for the user guide.

ConfigGenerator

class argclass.ConfigGenerator(*, mask_secrets=False)[source]

Bases: object

Walks an argclass Parser and renders its state to a config string.

Subclasses override render(). The base dump_to_string() and dump() methods take care of walking the parser and writing to disk / stdout / a file object.

Parameters

mask_secrets:

When true, fields declared via argclass.Secret() (or otherwise carrying secret=True) have their values replaced with SecretString.PLACEHOLDER. Use this to emit a credential-free template config; the resulting file is safe to commit / share. Default is False — the generator reproduces real credential values exactly so the file round-trips back into a working parser.

type mask_secrets:

bool

param mask_secrets:

extension: str = ''

File extension hint. Subclasses set this.

__init__(*, mask_secrets=False)[source]
Parameters:

mask_secrets (bool)

Return type:

None

render(fields)[source]

Render a sequence of ConfigField records to text.

Override this for a new format. fields is a materialised sequence — implementations may iterate it more than once (e.g. to split into header / sections) without burning through an exhausted iterator.

Default implementation just raises — every format has to decide how to lay out fields.

Parameters:

fields (Sequence[ConfigField])

Return type:

str

dump_to_string(parser, *, namespace=None)[source]

Walk parser and return the rendered config as a string.

Parameters:
Return type:

str

dump(parser, dest, *, namespace=None)[source]

Write the rendered config to dest.

dest may be a filesystem path (as str or pathlib.Path), a file-like object, or the string "-" for stdout.

Parameters:
Return type:

None

Parameters:

mask_secrets (bool)

ConfigField

The record type that custom render implementations consume. One ConfigField is yielded per leaf argument in the parser tree, carrying everything a renderer needs (path, dest, value, env var, help) so subclasses never have to walk the tree themselves.

class argclass.ConfigField(attr_path, cli_path, dest, argument, target, value, env_var, help)[source]

Bases: object

A single leaf argument from the parser tree, ready to emit.

A generator iterates these and writes them in the target format. Sections are derived from attr_path[:-1]; the field key is attr_path[-1].

Attributes

attr_path:

Tuple of attribute names from the parser root down to the leaf (("endpoint", "credentials", "username")). The last element is the field name; everything before it forms the section path used by INI / TOML.

cli_path:

Same shape as attr_path but respecting per-group prefix= overrides — useful when reconstructing CLI flag names.

dest:

argparse dest for the field ("endpoint_credentials_username"). Joins cli_path with underscores.

argument:

The owning TypedArgument. Carries declared type, help, env_var, etc.

target:

The Parser or Group instance that owns this attribute. Lets renderers reach back into the source if needed.

value:

The resolved value, already normalize_value()-d so it round-trips through every supported format.

env_var:

Env var name argclass would read (explicit env_var= or derived from auto_env_var_prefix=). None when no env var is configured.

help:

Help text declared on the argument, or None.

type attr_path:

Tuple[str, ...]

param attr_path:

type cli_path:

Tuple[str, ...]

param cli_path:

type dest:

str

param dest:

type argument:

TypedArgument

param argument:

type target:

Any

param target:

type value:

Any

param value:

type env_var:

Optional[str]

param env_var:

type help:

Optional[str]

param help:

attr_path: Tuple[str, ...]
cli_path: Tuple[str, ...]
dest: str
argument: TypedArgument
target: Any
value: Any
env_var: str | None
help: str | None
property section_path: Tuple[str, ...]

Path to the enclosing section, derived from attr_path.

property key: str

Bare leaf attribute name.

__init__(attr_path, cli_path, dest, argument, target, value, env_var, help)
Parameters:
Return type:

None

Parameters:

INIConfigGenerator

class argclass.INIConfigGenerator(*, mask_secrets=False)[source]

Bases: ConfigGenerator

Render a parser to INI.

Top-level arguments go under [DEFAULT] (read by argclass.INIDefaultsParser); nested groups become dotted sections ([endpoint.credentials]). Help text is emitted as ; <text> comments above each key.

Note: configparser’s [DEFAULT] section would normally cascade into every other section, but argclass.INIDefaultsParser strips that cascade on read so a top-level host cannot leak into a group’s host attribute.

Parameters:

mask_secrets (bool)

extension: str = '.ini'

File extension hint. Subclasses set this.

render(fields)[source]

Render a sequence of ConfigField records to text.

Override this for a new format. fields is a materialised sequence — implementations may iterate it more than once (e.g. to split into header / sections) without burning through an exhausted iterator.

Default implementation just raises — every format has to decide how to lay out fields.

Parameters:

fields (Sequence[ConfigField])

Return type:

str

static render_scalar(value)[source]
Parameters:

value (Any)

Return type:

str

JSONConfigGenerator

class argclass.JSONConfigGenerator(*, mask_secrets=False)[source]

Bases: ConfigGenerator

Render a parser to JSON.

Comments are not supported by JSON, so help text is dropped. Nested groups become nested objects.

Parameters:

mask_secrets (bool)

extension: str = '.json'

File extension hint. Subclasses set this.

render(fields)[source]

Render a sequence of ConfigField records to text.

Override this for a new format. fields is a materialised sequence — implementations may iterate it more than once (e.g. to split into header / sections) without burning through an exhausted iterator.

Default implementation just raises — every format has to decide how to lay out fields.

Parameters:

fields (Sequence[ConfigField])

Return type:

str

coerce_value(value)[source]

Convert non-JSON-native types to serialisable equivalents.

Parameters:

value (Any)

Return type:

Any

TOMLConfigGenerator

class argclass.TOMLConfigGenerator(*, mask_secrets=False)[source]

Bases: ConfigGenerator

Render a parser to TOML.

Help text is emitted as # <text> comments above each key. Nested groups use dotted table headers ([parent.child]).

Minimal hand-rolled emitter — covers str/int/float/ bool/list/None. Other types are coerced via str().

Parameters:

mask_secrets (bool)

extension: str = '.toml'

File extension hint. Subclasses set this.

render(fields)[source]

Render a sequence of ConfigField records to text.

Override this for a new format. fields is a materialised sequence — implementations may iterate it more than once (e.g. to split into header / sections) without burning through an exhausted iterator.

Default implementation just raises — every format has to decide how to lay out fields.

Parameters:

fields (Sequence[ConfigField])

Return type:

str

render_value(value)[source]
Parameters:

value (Any)

Return type:

str

static render_string(value)[source]
Parameters:

value (Any)

Return type:

str

EnvConfigGenerator

class argclass.EnvConfigGenerator(*, mask_secrets=False)[source]

Bases: ConfigGenerator

Render a parser to a .env-style listing.

Emits one KEY=value line per argument that has a resolvable env var (explicit env_var= on the argument or computed from the parser’s auto_env_var_prefix=). Arguments without an env var are skipped.

Help text appears as # <text> comments above each key. None values are dropped. Lists serialise to Python literal syntax so argclass can ast.literal_eval them on read.

Strings are quoted only when they contain whitespace, =, #, or other characters that would confuse a typical .env parser.

Parameters:

mask_secrets (bool)

extension: str = '.env'

File extension hint. Subclasses set this.

QUOTE_CHARS = frozenset({'\t', '\n', '\r', ' ', '"', '#', '=', '\\'})
render(fields)[source]

Render a sequence of ConfigField records to text.

Override this for a new format. fields is a materialised sequence — implementations may iterate it more than once (e.g. to split into header / sections) without burning through an exhausted iterator.

Default implementation just raises — every format has to decide how to lay out fields.

Parameters:

fields (Sequence[ConfigField])

Return type:

str

render_value(value)[source]
Parameters:

value (Any)

Return type:

str

quote_string(value)[source]
Parameters:

value (str)

Return type:

str

GenerateConfigAction

class argclass.GenerateConfigAction(option_strings, dest, generator, **kwargs)[source]

Bases: NonConfigAction

Argparse Action that writes a parser’s state as a config file.

Declare an attribute on your Parser and let argclass derive the flag from its name:

class CLI(argclass.Parser):
    generate_config = argclass.Argument(
        action=GenerateConfigAction,
        generator=INIConfigGenerator,
        metavar="FILE",
    )

End users then run myapp --generate-config /etc/myapp.ini (or - for stdout). The action walks the parser, renders the config via the supplied generator= (class or instance), writes to the destination, and exits with status 0.

Parameters:
__init__(option_strings, dest, generator, **kwargs)[source]
Parameters:
generator: ConfigGenerator

NonConfigAction

class argclass.NonConfigAction(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Bases: Action

Base class for argparse Actions that should NOT appear in config dumps produced by ConfigGenerator subclasses.

Use this as a base for any “fire and exit” style action — like --version, --check-updates, or --generate-config itself. ConfigGenerator checks __emit_config__ on the action class; when it is False, the argument is skipped.

Stateful custom actions don’t need to inherit anything — they’re included by default. Only inherit from NonConfigAction (or set __emit_config__ = False manually) for actions whose presence in a dumped config makes no sense.