CLI Usage#
This is the output of asyncutils --help, as of asyncutils v1.2.4:
usage: asyncutils [-l [FILE] | -n] [-e ETYP | -c ETYP | --thread | --process |
--interpreter | --loky | --loky-no-reuse | --dask |
--ipython | --elib-flux-cluster | --elib-flux-job |
--elib-slurm-cluster | --elib-slurm-job |
--elib-single-node | --pebble-thread | --pebble-process |
--deadpool] [-Q] [-V] [-q] [-b] [-m M] [-p] [-s SEED] [-d]
[-P] [-v] [-?]
{bug} ...
Copyright (c) 2026 Jonathan Dung. All rights reserved.
A versatile, feature-rich library of async tools integrated into the asyncio framework, aiming to make asynchronous programming easier for everyone.
Has CLI and coloured REPL support for quick development.
On both conda and pip as py-asyncutils.
options:
-l, --log-to [FILE] This module uses a logger, so that post-mortem debugging can be done by inspecting the log file created.
When FILE, interpreted as a file descriptor if an integer, is passed, the logging output goes to a file with that name.
Passing 'NULL' for FILE is equivalent to specifying the --no-log option.
If FILE is 'MEMORY', logs are stored in memory and returned and voided whenever get_past_logs is called.
If FILE is 'MAKE' or no filename is passed but the option specified, an attempt is made to create a file of format 'asyncutils_log<n>.log' in the
current working directory for logging, for integer n from 1 to 4096 inclusive. You are advised to clean up old log files periodically.
Log file rotation is not currently supported, and the program is unlikely to produce a large enough volume of logs to warrant it anyway.
If FILE is 'STDOUT', log to standard output.
If FILE is 'STDERR', log to standard error. This is also the default behaviour and fallback if the above steps fail.
-n, --no-log Disable logging completely.
A disabled logger is still created to make subsequent logging.getLogger calls return it.
Thus, this option cannot avoid the cost of importing logging and instantiating the logger early on.
-e, --executor ETYP Choose an executor class to use when necessary depending on the value of ETYP as follows:
thread: Use concurrent.futures.thread.ThreadPoolExecutor. This is the default and will be used if the third-party options are passed but not installed.
process: Use concurrent.futures.process.ProcessPoolExecutor. Use with care, since this depends on CPU architecture.
interpreter: Use concurrent.futures.interpreter.InterpreterPoolExecutor. May throw various errors relating to unshareable objects.
The below options are third-party.
loky_no_reuse: Use a new loky.process_executor.ProcessPoolExecutor every time.
loky: Reuse a loky.process_executor.ProcessPoolExecutor if possible.
dask: Use dask.distributed.Client, the API of which just so happens to be a superset of that of the concurrent.futures executors.
ipython: Use ipyparallel.ViewExecutor.
elib_flux_cluster: Use executorlib.executor.flux.FluxClusterExecutor.
elib_flux_job: Use executorlib.executor.flux.FluxJobExecutor.
elib_slurm_cluster: Use executorlib.executor.slurm.SlurmClusterExecutor.
elib_slurm_job: Use executorlib.executor.slurm.SlurmJobExecutor.
elib_single_node: Use executorlib.executor.single.SingleNodeExecutor.
pebble_thread: Use pebble.pool.thread.ThreadPool.
pebble_process: Use pebble.pool.process.ProcessPool.
deadpool: Use deadpool.Deadpool.
-c, --custom-executor ETYP
Use a custom executor not included in the above options by specifying the name of an implementation.
Passing "package.submodule.Implementation", for example, will execute "from package.submodule import Implementation as Executor".
--thread Equivalent to "-e thread".
--process Equivalent to "-e process".
--interpreter Equivalent to "-e interpreter".
--loky Equivalent to "-e loky".
--loky-no-reuse Equivalent to "-e loky_no_reuse".
--dask Equivalent to "-e dask".
--ipython Equivalent to "-e ipython".
--elib-flux-cluster Equivalent to "-e elib_flux_cluster".
--elib-flux-job Equivalent to "-e elib_flux_job".
--elib-slurm-cluster Equivalent to "-e elib_slurm_cluster".
--elib-slurm-job Equivalent to "-e elib_slurm_job".
--elib-single-node Equivalent to "-e elib_single_node".
--pebble-thread Equivalent to "-e pebble_thread".
--pebble-process Equivalent to "-e pebble_process".
--deadpool Equivalent to "-e deadpool".
verbosity:
Adjust the amount of output of this program.
-Q Produce less logging output. Additive.
-V Produce more logging output. Additive.
repl:
Configure the behaviour of the Read-Eval-Print Loop of this module.
-q, --quiet Do not display the banner and exit message in the REPL; the -q flag can be passed to the python command directly to achieve the same effect.
-b, --basic-repl Do not use the console with colours and enhanced functionality from _pyrepl. Use only if you have experienced a bug with the coloured console.
-m, --max-memory_errors M
The REPL will exit on the (M+1)-th MemoryError to prevent consuming too many computer resources.
M defaults to 3.
Set to a negative value to disable the threshold completely.
testing:
Options to more conveniently test this module.
-p, --load-all Preload all submodules of this module. Useful for testing, but incurs noticeable performance penalty.
-s, --seed SEED Seed the random instance used internally by this module with SEED, which will be interpreted as an integer if possible.
-d, --debug Enable debug mode to produce more logging output by entering the global debug context manager. Different from -VV, since
the verbosity flags take effect again when the context manager is manually exited.
-P, --pdb Intended for developers of this library only; open the pdb debugger interface when the exit code of the console is greater than zero,
or an uncaught error occurs in the console execution logic itself.
metadata:
Get basic information about this installation of asyncutils.
-v, --version Print the current version number of asyncutils, in the form as specified by __version__.representation, and exit.
Useful for checking if the installation succeeded.
-?, -h, --help Print this help message and exit.
subcommands:
{bug}
bug Streamline the process of opening a bug report on GitHub.
Use @<filename> to insert command-line arguments from the file of that name at the exact position of this parameter.
The file should have one argument per line; this format differs from that described below.
Use the AUTILSCFGPATH environment variable to specify a path to a file of a supported type containing the default configuration.
See the possible keys in format.json5, which can be accessed using tools.get_cfg_json_format().
Note that the inner workings of this library is tightly coupled with the ever-evolving asyncio framework.
As such, it is probably incompatible with full-fledged third-party async frameworks such as curio, anyio, trio, and tornado.
Note
Preview generated by scripts/generate.sh at 2026-09-06 14:24:58 UTC. DO NOT COMMIT.