From 1c1d2e2f50cdac418d46be231acaa6b5cf349484 Mon Sep 17 00:00:00 2001 From: "Jason M. Gates" Date: Wed, 14 Jun 2023 16:44:42 -0600 Subject: [PATCH] docs: Address pydocstyle issues --- .pre-commit-config.yaml | 8 +-- __init__.py | 6 +++ reverse_argparse/reverse_argparse.py | 79 ++++++++++++++++++++-------- setup.py | 5 ++ test/__init__.py | 7 +++ 5 files changed, 79 insertions(+), 26 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index fba543c..fb63567 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -63,10 +63,10 @@ repos: hooks: - id: prospector - # - repo: https://github.com/PyCQA/pydocstyle - # rev: 6.3.0 - # hooks: - # - id: pydocstyle + - repo: https://github.com/PyCQA/pydocstyle + rev: 6.3.0 + hooks: + - id: pydocstyle # - repo: https://github.com/regebro/pyroma # rev: "4.2" diff --git a/__init__.py b/__init__.py index 580397b..7a2ed64 100644 --- a/__init__.py +++ b/__init__.py @@ -1,3 +1,9 @@ +""" +The ``reverse_argparse`` package. + +Provide the :class:`ReverseArgumentParser` class and +:func:`quote_arg_if_necessary` helper function. +""" from .reverse_argparse.reverse_argparse import ( ReverseArgumentParser, quote_arg_if_necessary, diff --git a/reverse_argparse/reverse_argparse.py b/reverse_argparse/reverse_argparse.py index 7acf92b..21aabf3 100644 --- a/reverse_argparse/reverse_argparse.py +++ b/reverse_argparse/reverse_argparse.py @@ -1,4 +1,18 @@ #!/usr/bin/env python3 +""" +The ``reverse_argparse`` module. + +Defines the :class:`ReverseArgumentParser` class for unparsing arguments +that were already parsed via ``argparse``, and the +:func:`quote_arg_if_necessary` helper function to surround any args with +spaces in them with quotes. + +Raises: + NotImplementedError: If a particular :class:`Action` does not yet + have an associated unparser. + RuntimeError: If a subparser action is somehow missing its + dictionary of choices. +""" import re from argparse import SUPPRESS, Action, ArgumentParser, Namespace @@ -7,6 +21,8 @@ class ReverseArgumentParser: """ + Argument parsing in reverse. + Whereas :class:`argparse.ArgumentParser` is concerned with taking a bunch of command line arguments and parsing them into a :class:`argparse.Namespace`, this class is intended to do the @@ -39,6 +55,16 @@ class ReverseArgumentParser: def __init__( self, parser: ArgumentParser, namespace: Namespace, indent: int = 4 ): + """ + Initialize the object. + + Args: + parser: The :class:`ArgumentParser` used to construct the + given :arg:`namespace`. + namespace: The parsed arguments. + indent: How many spaces to use for each indentation level. + (See :func:`get_pretty_command_line_invocation`.) + """ self._unparsed = [False] self.args = [parser.prog] self.indent = indent @@ -47,6 +73,8 @@ def __init__( def _unparse_args(self) -> None: """ + Unparse all the arguments. + Loop over the positional and then optional actions, generating the command line arguments associated with each, and appending them to the list of arguments. @@ -102,6 +130,8 @@ def _unparse_args(self) -> None: def _arg_is_default_and_help_is_suppressed(self, action: Action) -> bool: """ + See if the argument should be skipped. + Determine whether the argument matches the default value and the corresponding help text has been suppressed. Such cases indicate that a parser author has hidden an argument from users, @@ -121,8 +151,9 @@ def _arg_is_default_and_help_is_suppressed(self, action: Action) -> bool: def get_effective_command_line_invocation(self) -> str: """ - Get the effective command line invocation of a script. This - takes into account what was passed into the script on the + Get the effective command line invocation of a script. + + This takes into account what was passed into the script on the command line, along with any default values, etc., such that there is no ambiguity in what exactly was run. @@ -135,6 +166,8 @@ def get_effective_command_line_invocation(self) -> str: def get_pretty_command_line_invocation(self) -> str: """ + Get a "pretty" version of the command that was run. + Similar to :func:`get_effective_command_line_invocation`, but generate a string ready for "pretty-printing", with escaped newlines between each of the arguments. @@ -192,6 +225,8 @@ def _get_option_string( self, action: Action, prefer_short: bool = False ) -> str: """ + Get the option string for the :arg:`action`. + Get the first of the long options corresponding to a given :class:`Action`. If no long options are available, get the first of the short options. If :arg:`prefer_short` is ``True``, @@ -223,6 +258,8 @@ def _get_option_string( def _append_list_of_list_of_args(self, args: list[list[str]]) -> None: """ + Append to the list of unparsed arguments. + Given a list of lists of command line arguments corresponding to a particular action, append them to the list of arguments, taking into account indentation and the sub-parser nesting @@ -236,6 +273,8 @@ def _append_list_of_list_of_args(self, args: list[list[str]]) -> None: def _append_list_of_args(self, args: list[str]) -> None: """ + Append to the list of unparsed arguments. + Given a list of command line arguments corresponding to a particular action, append them to the list of arguments, taking into account indentation and the sub-parser nesting level. @@ -247,6 +286,8 @@ def _append_list_of_args(self, args: list[str]) -> None: def _append_arg(self, arg: str) -> None: """ + Append to the list of unparsed arguments. + Given a command line argument corresponding to a particular action, append it to the list of arguments, taking into account indentation and the sub-parser nesting level. @@ -268,8 +309,7 @@ def indent_str(self) -> str: def _unparse_store_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action="store"``. + Generate the list of arguments for a ``store`` action. Args: action: The :class:`_StoreAction` in question. @@ -293,8 +333,7 @@ def _unparse_store_action(self, action: Action) -> None: def _unparse_store_const_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action="store_const"``. + Generate the argument for a ``store_const`` action. Args: action: The :class:`_StoreConstAction` in question. @@ -305,8 +344,7 @@ def _unparse_store_const_action(self, action: Action) -> None: def _unparse_store_true_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action="store_true"``. + Generate the argument for a ``store_true`` action. Args: action: The :class:`_StoreTrueAction` in question. @@ -317,8 +355,7 @@ def _unparse_store_true_action(self, action: Action) -> None: def _unparse_store_false_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action="store_false"``. + Generate the argument for a ``store_false`` action. Args: action: The :class:`_StoreFalseAction` in question. @@ -329,8 +366,7 @@ def _unparse_store_false_action(self, action: Action) -> None: def _unparse_append_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action="append"``. + Generate the list of arguments for an ``append`` action. Args: action: The :class:`_AppendAction` in question. @@ -357,8 +393,7 @@ def _unparse_append_action(self, action: Action) -> None: def _unparse_append_const_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action="append_const"``. + Generate the argument for an ``append_const`` action. Args: action: The :class:`_AppendConstAction` in question. @@ -369,8 +404,7 @@ def _unparse_append_const_action(self, action: Action) -> None: def _unparse_count_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action="count"``. + Generate the list of arguments for a ``count`` action. Args: action: The :class:`_CountAction` in question. @@ -385,8 +419,9 @@ def _unparse_count_action(self, action: Action) -> None: def _unparse_sub_parsers_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to a subparser - action. This is done by: + Generate the list of arguments for a subparser action. + + This is done by: * looping over the commands and corresponding parsers in the given subparser action, @@ -418,8 +453,7 @@ def _unparse_sub_parsers_action(self, action: Action) -> None: def _unparse_extend_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action="extend"``. + Generate the list of arguments for an ``extend`` action. Args: action: The :class:`_ExtendAction` in question. @@ -432,8 +466,7 @@ def _unparse_extend_action(self, action: Action) -> None: def _unparse_boolean_optional_action(self, action: Action) -> None: """ - Generate the list of arguments that correspond to - ``action=BooleanOptionalAction``. + Generate the list of arguments for a ``BooleanOptionalAction``. Args: action: The :class:`BooleanOptionalAction` in question. @@ -446,6 +479,8 @@ def _unparse_boolean_optional_action(self, action: Action) -> None: def quote_arg_if_necessary(arg: str) -> str: """ + Quote an argument, if necessary. + If a command line argument has any spaces in it, surround it in single quotes. If no quotes are necessary, don't change the argument. diff --git a/setup.py b/setup.py index 687a493..1f7222c 100644 --- a/setup.py +++ b/setup.py @@ -1,4 +1,9 @@ #!/usr/bin/env python3 +""" +Setup file for the ``reverse_argparse`` package. + +To install, simply ``python3 -m pip install .`` in the repository root. +""" import setuptools if __name__ == "__main__": diff --git a/test/__init__.py b/test/__init__.py index e69de29..ddbbce6 100644 --- a/test/__init__.py +++ b/test/__init__.py @@ -0,0 +1,7 @@ +""" +Create the ``test`` package. + +This ``__init__.py`` file creates the ``test`` package, such that tests +can relative-import from modules in the sibling ``reverse_argparse`` +directory. +"""