asyncutils.tools#

Utilities related to the command-line interface and getting metadata for package configuration.

Functions#

`argstr_to_json`(→ None)	Parses the shell-escaped string representing the command-line arguments for this module and writes it into a .json path.
`argv_to_json`(→ None)
`find_help_url`(→ str)	Get the URL of the `asyncutils` documentation page for `obj`. See the supported calling patterns here.
`get_cfg_json_format`(→ str)	Get the format of .json configs this module takes as a string. `print_cfg_json_format()` is perhaps more useful.
`get_cmd_help`(→ str)	Return the command line help as a string containing ANSI color escape sequences.
`json_to_argstr`(→ str)	Essentially the output of `json_to_argv()`, but joined into a shell-escaped string with `join`.
`json_to_argv`(→ list[str])
`loadf`(→ dict[str, Any])	Load the file at `path`, with the specified file extension if indeducible from the file name, into a dictionary using the correct library.
`open_help`(→ bool)	Open the URL to the documentation of the specified symbol defined in `asyncutils` via the default browser, returning success.
`print_cfg_json_format`(→ None)	Print the above format into the specified file and flush it (default `stdout`).
`print_cmd_help`(→ None)	Print the above help into the specified file (default `stdout`) and flush it.

asyncutils.tools.argstr_to_json(argstr: str, path: asyncutils._internal.types.Openable, /, *, dump: asyncutils._internal.types.DumpType = ..., split: _collections_abc.Callable[[str], _collections_abc.Sequence[str]] = ...) → None[source]#: Parses the shell-escaped string representing the command-line arguments for this module and writes it into a .json path.

asyncutils.tools.argv_to_json(argv: _collections_abc.Sequence[str], path: asyncutils._internal.types.Openable, /, *, dump: asyncutils._internal.types.DumpType = ...) → None[source]#: Writes the sequence of strings, parsed as command-line arguments for this module, into path in JSON format.

Since this function is ‘environment-agnostic’, it may have unintended behaviour if the arguments passed rely on current configuration, which is not captured.

asyncutils.tools.find_help_url(obj: Any = ..., /) → str[source]#: Get the URL of the asyncutils documentation page for obj. See the supported calling patterns here.

Caution

The URL returned is not guaranteed to work with strings representing non-existent, undocumented or internal symbols.

asyncutils.tools.get_cfg_json_format() → str[source]#: Get the format of .json configs this module takes as a string. print_cfg_json_format() is perhaps more useful.

asyncutils.tools.get_cmd_help() → str#: Return the command line help as a string containing ANSI color escape sequences.

Implementation detail

This actually a bound method of the library’s argument parser at runtime.

asyncutils.tools.json_to_argstr(path: asyncutils._internal.types.Openable, /, *, join: _collections_abc.Callable[[list[str]], str] = ...) → str[source]#: Essentially the output of json_to_argv(), but joined into a shell-escaped string with join.

asyncutils.tools.json_to_argv(path: asyncutils._internal.types.Openable, /) → list[str][source]#: Return a list of strings representing the command-line arguments for this module from path to the corresponding json file, with as little items as possible.

For integer file descriptors as path, the format is assumed to be plain JSON.

The module, should have a load() function that takes path and returns a dict of its contents.

Perfect round-trip conversion with argv_to_json() is guaranteed only with no other configuration file active.

asyncutils.tools.loadf(path: asyncutils._internal.types.Openable, ext: str = ..., /) → dict[str, Any][source]#: Load the file at path, with the specified file extension if indeducible from the file name, into a dictionary using the correct library.

asyncutils.tools.open_help(obj: Any = ..., /) → bool[source]#: Open the URL to the documentation of the specified symbol defined in asyncutils via the default browser, returning success.

asyncutils.tools.print_cfg_json_format(file: asyncutils._internal.types.CanWriteAndFlush[str] = ..., *, flush: bool = ...) → None[source]#: Print the above format into the specified file and flush it (default stdout).

asyncutils.tools.print_cmd_help(file: asyncutils._internal.types.CanWriteAndFlush[str] = ..., *, flush: bool = ...) → None[source]#: Print the above help into the specified file (default stdout) and flush it.