From af0fb50014641c4558c1eda0e2a4220c05770659 Mon Sep 17 00:00:00 2001 From: Brett Smith Date: Thu, 29 Apr 2021 11:49:46 -0400 Subject: [PATCH] cliutil: Add docstrings throughout. --- conservancy_beancount/cliutil.py | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/conservancy_beancount/cliutil.py b/conservancy_beancount/cliutil.py index ee9ce7f..ba06e53 100644 --- a/conservancy_beancount/cliutil.py +++ b/conservancy_beancount/cliutil.py @@ -1,4 +1,13 @@ -"""cliutil - Utilities for CLI tools""" +"""cliutil - Utilities for CLI tools + +This module provides common functionality for + +* command line argument parsing +* exception handling +* exit status reporting +* file opening that deals with the ``-`` convention +* logging +""" PKGNAME = 'conservancy_beancount' LICENSE = """ Copyright © 2020, 2021 Brett Smith and other contributors @@ -127,6 +136,13 @@ class EnumArgument(Generic[ET]): class ExceptHook: + """Common ExceptHook + + Interactive tools can install an instance of this class as + ``sys.excepthook``. It knows how to generate more user-friendly error + messages and exit codes for common exception types, and reports those to + the given logger (or the root logger if none was given). + """ def __init__(self, logger: Optional[logging.Logger]=None) -> None: if logger is None: logger = logging.getLogger() @@ -233,6 +249,13 @@ class ExtendAction(argparse.Action): class InfoAction(argparse.Action): + """argparse action to print information and exit + + Use this for options like ``--version`` and ``--license``. + The argument ``const`` can either be a 2-tuple (str, int) with the + message to print and exit code to use; or just a string message, and it + will default to using the OK exit code 0. + """ def __call__(self, parser: argparse.ArgumentParser, namespace: argparse.Namespace,