From 6eae92baa73143aeb21069adab2c1a73e26604d4 Mon Sep 17 00:00:00 2001
From: joncrall <jon.crall@kitware.com>
Date: Thu, 17 Oct 2024 14:29:57 -0400
Subject: [PATCH] Update __init__ docs
---
scriptconfig/__init__.py | 40 +++++++++++++++++-----------------------
1 file changed, 17 insertions(+), 23 deletions(-)
diff --git a/scriptconfig/__init__.py b/scriptconfig/__init__.py
index 54d6685..9d81130 100644
--- a/scriptconfig/__init__.py
+++ b/scriptconfig/__init__.py
@@ -18,13 +18,11 @@ update from CLI, kwargs, and/or json.
The pattern is simple:
- 1. Create a class that inherits from :class:`scriptconfig.Config`
+ 1. Create a class that inherits from :class:`scriptconfig.DataConfig`
- 2. Create a class variable dictionary named ``default``
+ 2. Create a class variable for each argument, the values are the defaults.
- 3. The keys are the names of your arguments, and the values are the defaults.
-
- 4. Create an instance of your config object. If you pass ``cmdline=True`` as an argument, it will autopopulate itself from the command line.
+ 3. Create an instance of your config object with `.cli` classmethod. If you pass ``argv=True`` as an argument, it will autopopulate itself from the command line.
Here is an example for a simple calculator program:
@@ -33,17 +31,15 @@ Here is an example for a simple calculator program:
import scriptconfig as scfg
- class MyConfig(scfg.Config):
+ class MyConfig(scfg.DataConfig):
'The docstring becomes the CLI description!'
- default = {
- 'num1': 0,
- 'num2': 1,
- 'outfile': './result.txt',
- }
+ num1 = 1
+ num2 = 2
+ outfile = './result.txt'
def main():
- config = MyConfig(cmdline=True)
+ config = MyConfig.cli(argv=True, verbose='auto')
result = config['num1'] + config['num2']
with open(config['outfile'], 'w') as file:
file.write(str(result))
@@ -64,7 +60,7 @@ message, the expected variable type, if it is a positional variable, alias
parameters for the command line, and more.
The important thing that gives scriptconfig an edge over things like
-:mod:`argparse` is that it is trivial to disable the ``cmdline`` flag and pass
+:mod:`argparse` is that it is trivial to disable the ``argv`` flag and pass
explicit arguments into your function as a dictionary. Thus you can write you
scripts in such a way that they are callable from Python or from a CLI via with
an API that corresponds 1-to-1!
@@ -76,28 +72,26 @@ A more complex example version of the above code might look like this
import scriptconfig as scfg
- class MyConfig(scfg.Config):
+ class MyConfig(scfg.DataConfig):
'''
The docstring becomes the CLI description!
'''
- default = {
- 'num1': scfg.Value(0, type=float, help='first number to add', position=1),
- 'num2': scfg.Value(1, type=float, help='second number to add', position=2),
- 'outfile': scfg.Value('./result.txt', help='where to store the result', position=3),
- }
+ num1 = scfg.Value(3, type=float, help='first number to add', position=1)
+ num2 = scfg.Value(5, type=float, help='second number to add', position=2)
+ outfile = scfg.Value('./result.txt', help='where to store the result', position=3)
- def main(cmdline=1, **kwargs):
+ def main(argv=1, **kwargs):
'''
Example:
>>> # This is much easier to test than argparse code
>>> kwargs = {'num1': 42, 'num2': 23, 'outfile': 'foo.out'}
- >>> cmdline = 0
- >>> main(cmdline=cmdline, **kwargs)
+ >>> argv = 0
+ >>> main(argv=argv, **kwargs)
>>> with open('foo.out') as file:
>>> assert file.read() == '65'
'''
- config = MyConfig(cmdline=True, data=kwargs)
+ config = MyConfig.cli(argv=argv, data=kwargs, verbose='auto')
result = config['num1'] + config['num2']
with open(config['outfile'], 'w') as file:
file.write(str(result))
--
GitLab