Skip to content

Commit

Permalink
Update general README
Browse files Browse the repository at this point in the history
  • Loading branch information
florianmahner committed Feb 12, 2023
1 parent 769a969 commit eba82f7
Showing 1 changed file with 43 additions and 15 deletions.
58 changes: 43 additions & 15 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@



toml-argparse is a python library and command-line-tool that allows you to use TOML configuration files with the argparse module. It provides a simple and convenient way to handle configuration for your python scripts, leveraging the strengths of both TOML and argparse.
toml-argparse is a python library and command-line-tool that allows you to use [TOML](https://toml.io/en/) configuration files with the [argparse](https://docs.python.org/3/library/argparse.html) module. It provides a simple and convenient way to handle configuration for your python scripts, leveraging the strengths of both TOML and argparse.

## Installation

Expand All @@ -20,28 +20,22 @@ pip install toml-argparse
```



## Usage

Using toml-argparse is straightforward and requires only a few extra steps compared to using argparse alone. You first define your configuration options in a TOML file, then use the [toml_argparse.ArgumentParser](https://github.com/florianmahner/toml-argparse/blob/main/toml_argparse/argparse.py) to add those options to your argparse argument parser.

Using toml-argparse is straightforward and requires only a few extra steps compared to using argparse alone. You first define your configuration options in a TOML file, then use the [TOML ArgumentParser](https://github.com/florianmahner/toml-argparse/blob/main/toml_argparse/argparse.py).

### Basic Example

[TOML](https://toml.io/en/) files usually come in the following form:

```toml
# This is a TOML File

# These are parameters not part of a section
# This is a very basic TOML file without a section
foo = 10
bar = "hello"

# This is a parameter that belongs to a section
[general]
foo = 42
```

Say we want to use the fields from the TOML file also for our python project. To do this we would create an `ArgumentParser` as usual:

The [TOML ArgumentParser](https://github.com/florianmahner/toml-argparse/blob/main/toml_argparse/argparse.py) is a simple wrapper of the original argparse module. It therefore provides the exact same fumctionality. To use the TOML arguments for our project, we we would create an `ArgumentParser` as usual:

```python
from toml_argparse import argparse
Expand All @@ -51,13 +45,47 @@ parser.add_argumetn("--bar", type=str, default="")
parser.parse_args()
```

This is just a very simple example with two arguments. For large projects with a lot of hyperparameters the number of arguments usually increases quickly. In this case, we can now easily parse parameters through the TOML file from the command-line:

This is just a very simple example with two arguments. However, for large projects with a lot of hyperparameters the number of arguments usually increases quickly and the TOML file provides an easy way to collect and store different hyperparameter configurations. We can do this by parsing parameters from the TOML file from the command-line:

```bash
python experiment.py --config "example.toml"
```
This will replace our argparse defaults with the ones specified in the toml file.

### Extended Example

TOML files have the power to separate arguments into different sections that are represented by nested dictionaries:

```toml
# This is a TOML File

# These are parameters not part of a section
foo = 10
bar = "hello"

[general]
foo = 20
```

If we would load this TOML file as usual this would return a dict {"foo": 10, "bar": "hello", "general": {"foo": 20}. Note that foo is overloaded and defined twice. We can also load arguments from a specific section through the corresponding keyword `section`:

```bash
python experiment.py --config "example.toml" --section "general"
```

This would return the following dict {"foo": 20, "bar": "hello"}. Note that section arguments override arguments without a section.

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:


```bash
python experiment.py --config "example.toml" --section "general" --foo 100
```


## Contributing
Expand Down

0 comments on commit eba82f7

Please sign in to comment.