sqltrack.args module#
- sqltrack.args.convert_argument(name: str, value: str) object [source]#
If the given value is type
str()
, try to apply all registered argument conversions in order. If no conversion works the original string is returned.- By default conversions are attempted as follows:
name
matches*int
→int
name
matches*float
→float
name
matches*complex
→complex
name
matches*path
→pathlib.Path
name
matches*json
→json.loads()
name
matches*str
→str
try
int
try
float
try
complex
try
json.loads()
You can register new conversions (or replace existing ones) with
register_conversion()
. The final trial and error stage is fixed.
- sqltrack.args.convert_arguments(args: dict, simplify_names=True) ParsedOptions | None [source]#
Apply
convert_argument()
to all argument values in the given dictionary. Returns a newdocopt.ParsedOptions
dictionary with converted arguments, or None if input was None.If
simplify_names
is True argument names are simplified. Leading dashes are stripped, any remaining dashes are replaced with underscores, and angle brackets are removed.
- sqltrack.args.detect_args(path: Path | str | None = None, **kwargs) ParsedOptions | None [source]#
Try to detect command line arguments using docopt. Docstrings are extracted from the file at the given path.
sys.argv[0]
is used if no path is given.First, docstrings of functions decorated with
docopt_arguments()
ordocopt_main()
are parsed in the order that they appear, and finally the module docstring. The first set of arguments that is successfully parsed is returned.- Parameters:
path – Use docstrings from this file, or
sys.argv[0]
if Nonekwargs – extra arguments passed to docopt.docopt()
- sqltrack.args.docopt_arguments(f=None, main=False, main_guard=True, **kwargs)[source]#
Decorator to parse command line arguments using docopt. The decorated function must accept one positional argument, e.g.:
@docopt_arguments def main(args): ...
The function docstring is parsed first, then the module docstring. The first set of successfully parsed arguments is passed to the function. ValueError is raised if parsing fails for all docstrings.
You can provide additional arguments, or override command line arguments by passing a dictionary to the wrapped function:
main({"good": True})
. An empty dictionary (main({})
) has no effect.- Parameters:
f – the decorated function, filled in by the Python
main – if True, immediately run
f
with parsed argsmain_guard – if True, guard execution of
f
withif __name__ == "__main__"
kwargs –
extra arguments passed to docopt.docopt()
- sqltrack.args.docopt_main(f=None, main_guard=True, **kwargs)[source]#
Decorator to parse command line arguments using docopt <https://github.com/jazzband/docopt-ng>. This is an alias for:
@docopt_arguments(main=True) def main(args): ...
Functions decorated like this are immediately executed, so they need to be located at the end of the file after any other definitons. If this is not what you want, use
docopt_arguments()
instead:@docopt_arguments def main(args): ... if __name__ == "__main__": main({})
- sqltrack.args.docopt_parse_docstrings(docstrings: Iterable[str], simplify_names=True, **kwargs) ParsedOptions [source]#
Use the
docopt()
package to parse arguments based on the POSIX definition of calling syntax in the given docstrings. Arguments of the first successful parsing are returned. Raises ValueError if parsing all given docstrings fails.Arguments are converted from strings using
convert_arguments()
.- Parameters:
docstrings – docstrings to parse, None values are ignored
simplify_names – if True, simplify argument names; See
convert_arguments()
for detailskwargs –
extra arguments passed to docopt.docopt()
- sqltrack.args.make_conversion(pattern: str, func: Callable)[source]#
Create a function that applies the given conversion function to arguments whose names match the given pattern.
- Parameters:
pattern – A
fnmatch.fnmatch()
patternfunc – A function that accepts one string argument and returns the converted result