cargparse 0.0.9

Configuration file parsing with argparse.

Parse configuration files with argparse.

Supported file types

	type	reader	third-party	note
✅	cfg/ini	configparser	no	Supports custom ConfigParser reader
✅	json	json	no
✅	toml	tomli/tomllib	yes/no	tomllib is built-in from Python 3.11 and was based on tomli
✅	yaml	pyyaml	yes

Installation

pip install cargparse

Basic usage

Given config.yaml:

text: hello world
number: 42

Use argparse as you normally would for command line arguments!

import argparse
import cargparse
import sys

parser = argparse.ArgumentParser()
parser.add_argument('--text', type=str, required=True)
parser.add_argument('--number', type=int, required=True)
parser.add_argument('--decimal', type=float)
config = cargparse.Cargparse(parser).parse_file(sys.argv[1])

python test.py config.yaml
>> config
{'text': 'hello world', 'number': 42)
>> config.text
'hello world'
>> type(config.number)
<class 'int'>

⚠️ Read the documentation for more information about type validation.

Advanced usage

You are not restricted to a flat hierarchy.

model:
  lstm:
    input_size: 100
    hidden_size:
      - 128
      - 64
  summary: True

Define a helper function to parse each nested section args, which is interpreted as a dictionary str.

from __future__ import annotations

def parse_config(filename: Path | str) -> cargparse.Namespace:

    def model_namespace(args: str) -> cargparse.Namespace:
        parser = argparse.ArgumentParser()
        parser.add_argument('--cnn', type=cnn_namespace)
        parser.add_argument('--lstm', type=lstm_namespace)
        parser.add_argument('--summary', type=cargparse.boolean)
        return cargparse.Cargparse(parser).parse_dict(args)

    def cnn_namespace(args: str) -> cargparse.Namespace:
        parser = argparse.ArgumentParser()
        parser.add_argument('--in_channels', type=int, required=True)
        parser.add_argument('--out_channels', type=int, required=True)
        parser.add_argument('--kernel_width', type=int, required=True)
        return cargparse.Cargparse(parser).parse_dict(args)

    def lstm_namespace(args: str) -> cargparse.Namespace:
        parser = argparse.ArgumentParser()
        parser.add_argument('--input_size', type=int, required=True)
        parser.add_argument('--hidden_size', type=cargparse.list_int, required=True)
        return cargparse.Cargparse(parser).parse_dict(args)

    parser = argparse.ArgumentParser()
    parser.add_argument('--model', type=model_namespace, required=True)
    return cargparse.Cargparse(parser).parse_file(filename)

if __name__ == '__main__':
    config = parse_config(filename=sys.argv[1])

>> config.model.cnn
>> config.model.lstm.hidden_units
*** AttributeError: hidden_units not in namespace: ['hidden_size', 'input_size']
>> config.model.lstm.hidden_size
[128, 64]

⚠️ Read the documentation for more information about type validation.