asyncutils.tools#

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

Functions#

`argstr_to_cfg`(→ None)	Parse the shell-escaped string representing the command-line arguments for this module and writes it into a .json path.
`argv_to_cfg`(→ None)
`cfg_to_argstr`(→ str)	Essentially the output of `cfg_to_argv()`, but joined into a shell-escaped string with `join`.
`cfg_to_argv`(→ list[str])
`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.
`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_cfg( argstr: str, path: _typeshed.FileDescriptorOrPath, /, *, 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_cfg( argv: collections.abc.Sequence[str], path: _typeshed.FileDescriptorOrPath, /, *, 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 by default, or the format chosen by the dump parameter if passed.

Since this function is environment-agnostic, it may behave unexpectedly if the arguments passed rely on current configuration, which is not captured.

asyncutils.tools.cfg_to_argstr(path: _typeshed.FileDescriptorOrPath, /, *, join: collections.abc.Callable[[list[str]], str] = ...) → str[source]#: Essentially the output of cfg_to_argv(), but joined into a shell-escaped string with join.

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

When an integer is passed to path, it is assumed to be a file descriptor for a JSON file. An alternate file extension cannot be specified.

The module should have a loads() function that takes a string of the file contents and returns a dict deserialized from it.

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

asyncutils.tools.find_help_url(obj: object = ..., /, *, ver: Literal['latest', 'stable'] = ...) → 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.loadf(path: _typeshed.FileDescriptorOrPath, 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 = ..., /, *, ver: Literal['latest', 'stable'] = ...) → 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.