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

.. autoclass:: argclass.Parser
   :members:
   :show-inheritance:

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

.. autoclass:: argclass.Group
   :members:
   :show-inheritance:

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"

.. autofunction:: argclass.Argument

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

.. autofunction:: argclass.Secret

SecretString

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

.. autoclass:: argclass.SecretString
   :members:
   :special-members: __str__, __repr__, __eq__

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 the config_files parameter (developer-chosen paths) or config_argument="--config" (end-user-chosen path) instead. See Config Files and Config File Parsers. :::

.. autofunction:: argclass.Config

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`

.. autoclass:: argclass.INIConfig
   :members:
   :show-inheritance:

.. autoclass:: argclass.JSONConfig
   :members:
   :show-inheritance:

:::{note} TOML requires tomllib (Python 3.11+) or tomli package (Python 3.10). :::

.. autoclass:: argclass.TOMLConfig
   :members:
   :show-inheritance:

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

.. autoclass:: argclass.INIDefaultsParser
   :members:
   :show-inheritance:

.. autoclass:: argclass.JSONDefaultsParser
   :members:
   :show-inheritance:

.. autoclass:: argclass.TOMLDefaultsParser
   :members:
   :show-inheritance:

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.

.. autoclass:: argclass.LogLevelEnum
   :members:
   :undoc-members:

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

.. autoclass:: argclass.Actions
   :members:
   :undoc-members:

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

.. autoclass:: argclass.Nargs
   :members:
   :undoc-members:

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

.. autofunction:: argclass.parse_bool

read_configs

Read and merge multiple configuration files.

.. autofunction:: argclass.read_configs

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.

.. autoclass:: argclass.ArgclassError
   :members:
   :show-inheritance:

ArgumentDefinitionError

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

.. autoclass:: argclass.ArgumentDefinitionError
   :members:
   :show-inheritance:

TypeConversionError

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

.. autoclass:: argclass.TypeConversionError
   :members:
   :show-inheritance:

ConfigurationError

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

.. autoclass:: argclass.ConfigurationError
   :members:
   :show-inheritance:

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.

.. autoclass:: argclass.EnumValueError
   :members:
   :show-inheritance:

ComplexTypeError

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

.. autoclass:: argclass.ComplexTypeError
   :members:
   :show-inheritance:

Advanced / Internal

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

Base

Abstract base class for both Parser and Group.

.. autoclass:: argclass.Base
   :members:
   :show-inheritance:

AbstractDefaultsParser

Base class for implementing custom config file parsers.

.. autoclass:: argclass.AbstractDefaultsParser
   :members:
   :show-inheritance:

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

.. autoclass:: argclass.ValueKind
   :members:
   :undoc-members:

UnexpectedConfigValue

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

.. autoclass:: argclass.UnexpectedConfigValue
   :members:
   :show-inheritance:

ConfigArgument

Base class for config file argument types.

.. autoclass:: argclass.ConfigArgument
   :members:
   :show-inheritance:

ConfigAction

Action class for config file arguments.

.. autoclass:: argclass.ConfigAction
   :members:

TypedArgument

Internal class representing a typed argument.

.. autoclass:: argclass.TypedArgument
   :members:
   :show-inheritance:

Store

Internal storage for argument metadata.

.. autoclass:: argclass.Store
   :members:

Specialized Argument Functions

.. autofunction:: argclass.ArgumentSingle

.. autofunction:: argclass.ArgumentSequence

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

.. autofunction:: argclass.EnumArgument

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

.. autoclass:: argclass.ConfigGenerator
   :members:

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.

.. autoclass:: argclass.ConfigField
   :members:

INIConfigGenerator

.. autoclass:: argclass.INIConfigGenerator
   :members:

JSONConfigGenerator

.. autoclass:: argclass.JSONConfigGenerator
   :members:

TOMLConfigGenerator

.. autoclass:: argclass.TOMLConfigGenerator
   :members:

EnvConfigGenerator

.. autoclass:: argclass.EnvConfigGenerator
   :members:

GenerateConfigAction

.. autoclass:: argclass.GenerateConfigAction

NonConfigAction

.. autoclass:: argclass.NonConfigAction

FilesExpand file tree

api.md

Latest commit

History