diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ca27ad4..dda16d2 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -27,7 +27,7 @@ jobs: python-version: 3.13 - name: Install linters - run: python -m pip install --upgrade pip black zizmor + run: python -m pip install --upgrade pip black zizmor pydoctor - name: Black run: black . --check @@ -35,6 +35,9 @@ jobs: - name: Zizmor run: find .github/workflows -name '*.yml' | xargs zizmor --config .github/zizmor.yml + - name: Pydoctor + run: pydoctor ./configargparse.py --intersphinx=https://docs.python.org/3/objects.inv --docformat=google -W + test: name: ${{ matrix.os }} py${{ matrix.python-version }} ${{ matrix.use-docker && '(docker)' || '' }} runs-on: ${{ matrix.os }} diff --git a/apidocs.sh b/apidocs.sh index 0463dc7..a3a2c67 100755 --- a/apidocs.sh +++ b/apidocs.sh @@ -14,11 +14,8 @@ project_version="$(python3 setup.py -V)" # Figure commit ref git_sha="$(git rev-parse HEAD)" -if ! git describe --exact-match --tags > /dev/null 2>&1 ; then - is_tag=false -else +if git describe --exact-match --tags > /dev/null 2>&1 ; then git_sha="$(git describe --exact-match --tags)" - is_tag=true fi # Init output folder @@ -44,6 +41,6 @@ pydoctor \ --project-base-dir=.\ --docformat=google \ --html-output="${docs_folder}" \ - ./argparse.py ./configargparse.py || true + ./argparse.py ./configargparse.py || true -echo "API docs generated in ${docs_folder}" \ No newline at end of file +echo "API docs generated in ${docs_folder}" diff --git a/configargparse.py b/configargparse.py index a3b11dd..db92aa6 100644 --- a/configargparse.py +++ b/configargparse.py @@ -107,7 +107,7 @@ def parse(self, stream): one of: "yes", "no", "on", "off", "true", "false". Otherwise an error will be raised. Args: - stream (IO): A config file input stream (such as an open file object). + stream (io.IOBase): A config file input stream (such as an open file object). Returns: OrderedDict: Items where the keys are strings and the @@ -421,7 +421,7 @@ def unquote_str(text, triple=True): It supports all kinds of python quotes: ``\"\"\"``, ``'''``, ``"`` and ``'``. :param triple: Also unquote tripple quoted strings. - @raises ValueError: If the string is detected as beeing quoted but literal_eval() fails to evaluate it as string. + :raises ValueError: If the string is detected as beeing quoted but literal_eval() fails to evaluate it as string. This would be a bug in the regex. """ if is_quoted(text, triple=triple): @@ -458,7 +458,7 @@ def parse_toml_section_name(section_name): def get_toml_section(data, section): """ - Given some TOML data (as loaded with `toml.load()`), returns the requested section of the data. + Given some TOML data (as loaded with toml.load()), returns the requested section of the data. Returns ``None`` if the section is not found. """ sections = parse_toml_section_name(section) if isinstance(section, str) else section @@ -479,6 +479,7 @@ class TomlConfigParser(ConfigFileParser): Create a TOML parser bounded to the list of provided sections. Example:: + # this is a comment [tool.my-software] # TOML section table. # how to specify a key-value pair @@ -489,7 +490,7 @@ class TomlConfigParser(ConfigFileParser): verbosity = 1 # how to specify a list arg (eg. arg which has action="append") repeatable-option = ["https://docs.python.org/3/objects.inv", - "https://twistedmatrix.com/documents/current/api/objects.inv"] + "https://twistedmatrix.com/documents/current/api/objects.inv"] # how to specify a multiline text: multi-line-text = ''' Lorem ipsum dolor sit amet, consectetur adipiscing elit. @@ -500,7 +501,7 @@ class TomlConfigParser(ConfigFileParser): Note that the config file fragment above is also valid for the `IniConfigParser` class and would be parsed the same manner. Thought, any valid TOML config file will not be necessarly parsable with `IniConfigParser` (INI files must be rigorously indented whereas TOML files). - See the `TOML specification <>`_ for details. + See the `TOML specification `_ for details. """ def __init__(self, sections): @@ -597,7 +598,7 @@ class IniConfigParser(ConfigFileParser): def __init__(self, sections, split_ml_text_to_list): """ :param sections: The section names bounded to the new parser. - :split_ml_text_to_list: Wether to convert multiline strings to list + :param split_ml_text_to_list: Wether to convert multiline strings to list """ super().__init__() self.sections = sections @@ -673,10 +674,10 @@ def get_syntax_description(self): class CompositeConfigParser(ConfigFileParser): """ - Createa a config parser composed by others `ConfigFileParser`s. + Create a config parser composed by other ConfigFileParser instances. The composite parser will successively try to parse the file with each parser, - until it succeeds, else raise execption with all encountered errors. + until it succeeds, else raise exception with all encountered errors. """ def __init__(self, config_parser_types): @@ -731,7 +732,7 @@ def __init__(self, *args, **kwargs): r"""Supports args of the `argparse.ArgumentParser` constructor as \*\*kwargs, as well as the following additional args. - Arguments: + Keyword Arguments: add_config_file_help: Whether to add a description of config file syntax to the help message. add_env_var_help: Whether to add something to the help message for @@ -1339,7 +1340,7 @@ def _open_config_files(self, command_line_args): command_line_args: List of all args Returns: - list[IO]: open config files + list[io.IOBase]: open config files """ # open any default config files config_files = [] @@ -1525,7 +1526,7 @@ def add_argument(self, *args, **kwargs): This method supports the same args as ArgumentParser.add_argument(..) as well as the additional args below. - Arguments: + Keyword Arguments: env_var: If set, the value of this environment variable will override any config file or default values for this arg (but can itself be overridden on the commandline). Also, if auto_env_var_prefix is