From 3ada81b389c29d8c180f2f1e4b7bafca3f55b27b Mon Sep 17 00:00:00 2001
From: Rogier van der Geer <rogier@vander-geer.nl>
Date: Mon, 25 Mar 2024 10:38:04 +0100
Subject: [PATCH] Improve the README introduction (#60)

---
 README.md      | 81 ++++++++++++++++++++++++++++++++++++++++----------
 pyproject.toml |  2 +-
 2 files changed, 67 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index a798f1e..939ad0c 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,11 @@
 # pydargs
 
-Pydargs allows configuring a (Pydantic) dataclass through command line arguments.
-
-## Installation
-
-Pydargs can be installed with your favourite package manager. For example:
-
-```
-pip install pydargs
-```
+Easily configure a CLI application using a (Pydantic) dataclass.
 
 ## Usage
 
-A minimal usage example would be:
+Pydargs instantiates a dataclass that is used as (configuration) input of your entrypoint from command line arguments.
+For example, in `example.py`:
 
 ```python
 from dataclasses import dataclass
@@ -24,18 +17,76 @@ class Config:
     number: int
     some_string: str = "abc"
 
+
+def main(config: Config) -> None:
+    """Your main functionality"""
+    print(f"> Hello {config.number} + {config.some_string}")
+
+
 if __name__ == "__main__":
     config = parse(Config)
+    main(config)
 ```
 
-After which this entrypoint can be called with
+Here the `Config` dataclass serves as input (configuration) of the `main` function. Pydargs facilitates
+instantiating the `config` instance, allowing the user to use command line arguments to set or override the
+values of its fields:
+
 
 ```shell
-entrypoint --number 42
+$ python example.py --number 1
+> Hello 1 abc
+$ python example.py --number 2 --some-string def
+> Hello 2 def
+$ python example.py --help
+usage: example.py [-h] --number NUMBER [--some-string SOME_STRING]
+
+options:
+  -h, --help            show this help message and exit
+  --number NUMBER
+  --some-string SOME_STRING
+                        (default: abc)
 ```
-or
-```shell
-entrypoint --number 42 --some-string abcd
+
+This saves you from having to maintain boilerplate code such as
+
+```python
+from argparse import ArgumentParser
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    number: int
+    some_string: str = "abc"
+
+
+def main(config: Config) -> None:
+    """Your main functionality"""
+    print(f"> Hello {config.number} + {config.some_string}")
+
+
+if __name__ == "__main__":
+    parser = ArgumentParser()
+    parser.add_argument("--number", type=int)
+    parser.add_argument("--some-string", dest="some_string", default="abc")
+    namespace = parser.parse_args()
+    config = Config(number=namespace["number"], some_string=namespace["some_string"])
+    main(config)
+```
+
+Aside from that, pydargs supports:
+- [a wide variety of field types](#supported-field-types),
+- [nested dataclasses](#nested-dataclasses),
+- [subparsers / commands](#subparsers),
+- [pydantic dataclasses](https://docs.pydantic.dev/latest/concepts/dataclasses/) to help you with validation.
+
+## Installation
+
+Pydargs can be installed with your favourite package manager. For example:
+
+```
+pip install pydargs
 ```
 
 ## ArgumentParser arguments
diff --git a/pyproject.toml b/pyproject.toml
index 804c2a8..d5f5c86 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -8,7 +8,7 @@ authors = [
     {name = "Guus Verstegen", email = "gjaverstegen@gmail.com"},
     {name = "Rogier van der Geer", email = "rogier@vander-geer.nl"},
 ]
-description = "Pydargs allows configuring a dataclass through command line arguments."
+description = "Easily configure a CLI application using a (Pydantic) dataclass."
 readme = "README.md"
 requires-python = ">=3.9"
 license = {text = "BSD"}