aboutsummaryrefslogtreecommitdiff
path: root/programming/python/creating_nice_python_cli_tools.md
diff options
context:
space:
mode:
authoralex <alex@pdp7.net>2026-03-01 20:03:15 +0100
committeralex <alex@pdp7.net>2026-03-01 20:03:15 +0100
commitd2ebc40be0d31b66a3a9f90f7a6bd0ed0dccbe7c (patch)
tree9f3e1a00c15254861444a96e52f02f2065dee9d4 /programming/python/creating_nice_python_cli_tools.md
parentaf4ff4abd127145ccd4d58d060c982456ba7a334 (diff)
Condense most Python articles to single article in blog website
Diffstat (limited to 'programming/python/creating_nice_python_cli_tools.md')
-rw-r--r--programming/python/creating_nice_python_cli_tools.md40
1 files changed, 0 insertions, 40 deletions
diff --git a/programming/python/creating_nice_python_cli_tools.md b/programming/python/creating_nice_python_cli_tools.md
deleted file mode 100644
index b192da1a..00000000
--- a/programming/python/creating_nice_python_cli_tools.md
+++ /dev/null
@@ -1,40 +0,0 @@
-Following this advice can make your tools easy to install by others, pleasant to use, robust, cross-platform, and powerful.
-
-* Use [my suggestions for setting up Python projects](project_setup.md), particularly:
- * Provide instructions for installing your tool using [pipx](https://github.com/pypa/pipx).
- Using pipx, people can install and upgrade your script using a simple command that requires no administrative privileges (but it requires having Python and pipx installed).
- * As you are using [uv](https://docs.astral.sh/uv/), following the indications above:
- * Use [entry points](https://docs.astral.sh/uv/concepts/projects/config/#entry-points), so when installing your tool via pipx or other means, your scripts are added to the user's path.
- * Dependencies you define will be installed automatically along with your application.
- This reduces the effort users need to use your application if you need third-party libraries.
- However, I would still advise to avoid unnecessary dependencies (for simple HTTP requests you can use the base library. If you do complex requests, then using a third-party library might be much simpler).
- As you are using pipx, those dependencies will be installed to a isolated virtualenv, so they will not interfere with anything on your system.
- * As your application is properly packaged, you can split your code into different Python files and use imports without issues.
-* If your application requires secrets, such as credentials or others, consider using:
- * The standard [getpass](https://docs.python.org/3/library/getpass.html) module.
- This prompts for a string on the command line, hiding what the user types.
- * The [keyring](https://pypi.org/project/keyring/) library.
- This stores secrets using your operating system facilities.
-* Use the [appdirs](https://pypi.org/project/appdirs/) library to obtain "user paths", such as the users directory for configuration, cache, or data.
- appdirs knows the proper paths for Linux, macOS and Windows.
- So for example, if your tool caches files and uses appdirs to find the cache directory, you might gain benefits such as cache files being excluded from backups.
-* If your tool requires significant time to complete a process:
- * Use the [tqdm](https://tqdm.github.io/) library to add a progress bar.
- * But also consider using the standard [concurrent.futures](https://docs.python.org/3/library/concurrent.futures.html) module to add parallelism if you can.
- The [map](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Executor.map) function is particularly easy to use.
- Use it with a [ThreadPoolExecutor](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor) if the parallel tasks are IO-bound or invoke other programs, or with [ProcessPoolExecutor](https://docs.python.org/3/library/concurrent.futures.html#processpoolexecutor) if they perform significant CPU work in Python (to avoid the [GIL](https://wiki.python.org/moin/GlobalInterpreterLock)).
- * Consider using the standard [logging](https://docs.python.org/3/library/logging.html) module with a format that uses a timestamp, so users can inspect how much time is spent in different parts of the program.
- You can also use logging module to implement flags such as `--debug` and `--verbose`.
-* Although fancier tools exist, the standard [argparse](https://docs.python.org/3/library/argparse.html) module is good enough for most argument parsing.
- It has decent support for [sub-commands](https://docs.python.org/3/library/argparse.html#sub-commands), and the linked document describes a very nice pattern to define functions for sub-commands, under "One particularly effective way of handling sub-commands..."
- Provide help text for non-obvious parameters.
- argparse supports a lot of different argument types with a lot of functionality out of the box, such as enumerated options, integers, and file names.
- The main reason for using a fancier argument parsing is that argparse does not have autocomplete support, but you can add [argcomplete](https://github.com/kislyuk/argcomplete) to an argparse program with minimal modifications to retrofit autocomplete.
-* Remember that the standard [json](https://docs.python.org/3/library/json.html) module is built-in.
- You can use it to add a mode to your tool that generates JSON output instead of human-readable output, for easy automation of your tool, maybe using [jq](https://stedolan.github.io/jq/) or [fx](https://github.com/antonmedv/fx).
-* Use the standard [subprocess](https://docs.python.org/3/library/subprocess.html) module to execute other commands.
- * Remember never to use `shell=True`, so among other things, your tool will work correctly with files using spaces in their names.
- * Use `check=True` so if the subprocess fails, an exception will be raised.
- This is likely the best default behavior, although the error is a bit ugly, this normally prevents ugly problems and it's a safe option.
-
-You can find examples for many of those techniques in my [repos](https://github.com/alexpdp7?tab=repositories&q=&type=&language=python&sort=).