sqltrack.args module

sqltrack.args.convert_argument(name: str, value: str) → object

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

Apply convert_argument() to all argument values in the given dictionary. Returns a new docopt.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

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() or docopt_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 None

• kwargs – extra arguments passed to docopt.docopt()

sqltrack.args.docopt_arguments(f=None, main=False, main_guard=True, **kwargs)

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 args

• main_guard – if True, guard execution of f with if __name__ == "__main__"

• kwargs –

  extra arguments passed to docopt.docopt()

sqltrack.args.docopt_main(f=None, main_guard=True, **kwargs)

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

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 details

• kwargs –

  extra arguments passed to docopt.docopt()

sqltrack.args.make_conversion(pattern: str, func: Callable)

Create a function that applies the given conversion function to arguments whose names match the given pattern.

Parameters:

• pattern – A fnmatch.fnmatch() pattern

• func – A function that accepts one string argument and returns the converted result

sqltrack.args.register_conversion(name: str, func: Callable)

Register a function for automatic argument conversion.