Skip to main content

This is a template repository for Python projects that use Poetry for their dependency management.

Project description

tomlparse

Release Build status example workflow codecov License code style

toml-argparse is a Python library and command-line tool that allows you to use TOML configuration files in conjunction with the argparse module. It provides a simple and convenient way to handle your python projects, leveraging the strengths of both TOML and argparse.

Table of Contents

  1. Installation
  2. Usage
    1. Basic Example
    2. Extended Example
  3. Contributing

Installation

You can install the library using pip

pip install toml-argparse

Usage

Using toml-argparse is straightforward and requires only a few extra steps compared to using argparse alone.

Basic Example

You first define your configuration options in a TOML file. TOML files are highly flexible and include a lot of native types. Have look here for an extensive list. TOML files usually come in the following form:

# This is a very basic TOML file
foo = 10
bar = "hello"

At the core of this module is the TOML ArgumentParser, a simple wrapper of the original argparse module. To use the TOML arguments for our project, we we would create an ArgumentParser as usual:

from toml_argparse import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--foo", type-int, default=0)
parser.add_argumetn("--bar", type=str, default="")
parser.parse_args()

This is just a simple example with two arguments. But for larger projects with many hyperparameters, the number of arguments can quickly grow, and the TOML file provides an easy way to collect and store different hyperparameter configurations. Every TOML ArgumentParser has a config argument defined that we can pass using the following command-line syntax:

python experiment.py --config "example.toml"

This will replace the default values from the ArgumentParser with the TOML values.

Extended Example

TOML files have the ability to separate arguments into different sections (called tables), which are represented by nested dictionaries:

# This is a TOML File

# Parameters without a prededing [] are not part of a table (called root-table)
foo = 10
bar = "hello"

# These arguments are part of the table [general]
[general]
foo = 20

# These arguments are part of the table [root]
[root]
bar = "hey"

If we would load this TOML file as usual this would return a dict {"foo": 10, "bar": "hello", "general": {"foo": 20}, "root" : {"bar": "hey"}}. Note that foo and bar are overloaded and defined twice. To specify the values we wish to take each TOML ArgumentParser has two arguments defined:

  1. table
  2. root-table

We can use these directly from the command-line:

python experiment.py --config "example.toml" --table "general"

In this case the root-table is not defined. In this case the arguments at the top of the file without a table are taken and parsing would return the following dict {"foo": 20, "bar": "hello"}. Note that table arguments override arguments from the root-table.

We can also specify the root-table:

python experiment.py --config "example.toml" --table "general" --root-table "root"

which would return the following dict {"foo: 20", "bar": "hey"} and override the arguments from the top of the TOML file.

In general, we have the following hierarchy of arguments:

  1. Arguments passed through the command line are selected over TOML arguments, even if both are passed
  2. Arguments from the TOML file are preferred over the default arguments
  3. Arguments from the TOML with a section override the arguments without a section

This means that we can also override arguments in the TOML file from the command-line:

python experiment.py --config "example.toml" --table "general" --foo 100

Contributing

Please have a look at the contribution guidlines in Contributing.rst.


Repository initiated with fpgmaas/cookiecutter-poetry.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

toml_argparse-1.0.0.tar.gz (6.0 kB view details)

Uploaded Source

Built Distribution

toml_argparse-1.0.0-py3-none-any.whl (6.2 kB view details)

Uploaded Python 3

File details

Details for the file toml_argparse-1.0.0.tar.gz.

File metadata

  • Download URL: toml_argparse-1.0.0.tar.gz
  • Upload date:
  • Size: 6.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.11.4 Linux/5.15.0-1041-azure

File hashes

Hashes for toml_argparse-1.0.0.tar.gz
Algorithm Hash digest
SHA256 d417475c69620f778667381e105342cb4202c80d4dc487007332ca5dc42ca02f
MD5 3ba085dda637a31446ebca075afc9ac1
BLAKE2b-256 417616aa2147912847d191cf33868359a3270897fca508f9b3f5f2bc44c994f6

See more details on using hashes here.

File details

Details for the file toml_argparse-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: toml_argparse-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 6.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.11.4 Linux/5.15.0-1041-azure

File hashes

Hashes for toml_argparse-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a0a3d2d10180f8065c26623eb60ad59a62939ed38b80078489b1fa3a27e97069
MD5 ab861ba0641855f05f7f41d89f0b6ec2
BLAKE2b-256 b1391e9cd365cd3859ea883dc8c5f5107584d256aa9fd5b4c54927c3ca314e7a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page