asyncutils.tools#

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

Functions#

`argstr_to_json`(→ None)	Parse 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_cmd_help`(→ str)	Return the command line help as a string containing ANSI colour 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 undeducible 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 format, as gotten by `get_cfg_json_format()`, into the specified file and flush it (default `stdout`).
`print_cmd_help`(→ None)	Print the help, as returned by `get_cmd_help()`, into the specified file (default `stdout`) and flush it.

asyncutils.tools.argstr_to_json( argstr: str, path: asyncutils._internal.prots.Openable, /, *, dump: asyncutils._internal.prots.DumpType = ..., split: collections.abc.Callable[[str], collections.abc.Sequence[str]] = ..., ) → None[source]#: Parse 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.prots.Openable, /, *, dump: asyncutils._internal.prots.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: object = ..., /) → 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.

If you would like a format schema for other languages, a programmatic approach would likely be unnecessary; you can just use an online tool implementing a browser-based converter.

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

Implementation detail

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

asyncutils.tools.json_to_argstr( path: asyncutils._internal.prots.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.prots.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.prots.Openable, ext: str = ..., /) → dict[str, Any][source]#: Load the file at path, with the specified file extension if undeducible from the file name, into a dictionary using the correct library.

asyncutils.tools.open_help(obj: object = ..., /) → 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.prots.CanWriteAndFlush[str] = ..., *, flush: bool = ...) → None[source]#: Print the format, as gotten by get_cfg_json_format(), into the specified file and flush it (default stdout).

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