From 41c454ee493362c63f9525fd40dc8cb780d99a03 Mon Sep 17 00:00:00 2001 From: Javier Buzzi Date: Thu, 3 Jul 2025 12:52:05 +0200 Subject: [PATCH 01/17] Removes tox --- tox.ini | 48 ------------------------------------------------ 1 file changed, 48 deletions(-) delete mode 100644 tox.ini diff --git a/tox.ini b/tox.ini deleted file mode 100644 index 6ee0cc1e..00000000 --- a/tox.ini +++ /dev/null @@ -1,48 +0,0 @@ -[tox] -envlist = py35, py36, py37, py38, py39, py310, py311, pypy, pypy3 - -[testenv] -#setenv = PYTHONPATH = {toxinidir}:{toxinidir}/configmanager - -commands = python setup.py test - # python -m unittest discover - -[testenv:py36] -basepython=python3.6 - -[testenv:py37] -basepython=python3.7 - -[testenv:py38] -basepython=python3.8 - -[testenv:py39] -basepython=python3.9 - -[testenv:py310] -basepython=python3.10 - -[testenv:py311] -basepython=python3.11 - -[testenv:py312] -basepython=python3.12 - -[testenv:py313] -basepython=python3.13 - -[testenv:pypy] -basepython=pypy - -[testenv:pypy3] -basepython=pypy3 - -[testenv:apidocs] -description = Build the API documentation - - -deps = - pydoctor>=22.3.0 -allowlist_externals = bash -commands = - bash ./apidocs.sh From 9506b5a94280b883347bdf43f62caf71cea74f13 Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 13:15:10 -0400 Subject: [PATCH 02/17] testing --- .github/workflows/apidocs.yml | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/.github/workflows/apidocs.yml b/.github/workflows/apidocs.yml index b8f6a04d..edf97a3c 100644 --- a/.github/workflows/apidocs.yml +++ b/.github/workflows/apidocs.yml @@ -2,9 +2,9 @@ name: apidocs on: push: - branches: [ master ] - tags: - - '*' + # branches: [ master ] + # tags: + # - '*' jobs: deploy: @@ -18,14 +18,14 @@ jobs: python-version: 3.8 - name: Install requirements for documentation generation - run: python -m pip install --upgrade pip setuptools wheel tox + run: python -m pip install --upgrade pip pydoctor>=22.3.0 - name: Generate API documentation with pydoctor - run: tox -e apidocs + run: ./apidocs.sh - - name: Push API documentation to Github Pages - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./apidocs - commit_message: "Generate API documentation" + # - name: Push API documentation to Github Pages + # uses: peaceiris/actions-gh-pages@v3 + # with: + # github_token: ${{ secrets.GITHUB_TOKEN }} + # publish_dir: ./apidocs + # commit_message: "Generate API documentation" From 9f3da2eab03023ba34d56f5124644459eaa36496 Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 13:20:01 -0400 Subject: [PATCH 03/17] . --- .github/workflows/apidocs.yml | 7 ++++--- .github/workflows/test.yml | 15 +++++++++++++++ 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/.github/workflows/apidocs.yml b/.github/workflows/apidocs.yml index edf97a3c..4fe0443f 100644 --- a/.github/workflows/apidocs.yml +++ b/.github/workflows/apidocs.yml @@ -2,9 +2,10 @@ name: apidocs on: push: - # branches: [ master ] - # tags: - # - '*' + branches: [ master ] + tags: + - '*' + pull_request: jobs: deploy: diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 59ba0693..691d04cf 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -88,6 +88,21 @@ jobs: path: .coverage retention-days: 1 + apidocs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.13 + + - name: Install requirements for documentation generation + run: python -m pip install --upgrade pip pydoctor>=22.3.0 + + - name: Generate API documentation + run: ./apidocs.sh + coverage: runs-on: ubuntu-latest needs: test From 4ba1d28874370f279eda8ad40104aa9f89ce01ac Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 13:20:30 -0400 Subject: [PATCH 04/17] . --- .github/workflows/apidocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/apidocs.yml b/.github/workflows/apidocs.yml index 4fe0443f..67112182 100644 --- a/.github/workflows/apidocs.yml +++ b/.github/workflows/apidocs.yml @@ -5,7 +5,6 @@ on: branches: [ master ] tags: - '*' - pull_request: jobs: deploy: From caa985eb7f117eac9da1b9c4eea79ebcc33c9d8a Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 13:24:04 -0400 Subject: [PATCH 05/17] Put everything back --- .github/workflows/apidocs.yml | 16 ++++++------ tox.ini | 48 +++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 8 deletions(-) create mode 100644 tox.ini diff --git a/.github/workflows/apidocs.yml b/.github/workflows/apidocs.yml index 67112182..b8f6a04d 100644 --- a/.github/workflows/apidocs.yml +++ b/.github/workflows/apidocs.yml @@ -18,14 +18,14 @@ jobs: python-version: 3.8 - name: Install requirements for documentation generation - run: python -m pip install --upgrade pip pydoctor>=22.3.0 + run: python -m pip install --upgrade pip setuptools wheel tox - name: Generate API documentation with pydoctor - run: ./apidocs.sh + run: tox -e apidocs - # - name: Push API documentation to Github Pages - # uses: peaceiris/actions-gh-pages@v3 - # with: - # github_token: ${{ secrets.GITHUB_TOKEN }} - # publish_dir: ./apidocs - # commit_message: "Generate API documentation" + - name: Push API documentation to Github Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./apidocs + commit_message: "Generate API documentation" diff --git a/tox.ini b/tox.ini new file mode 100644 index 00000000..6ee0cc1e --- /dev/null +++ b/tox.ini @@ -0,0 +1,48 @@ +[tox] +envlist = py35, py36, py37, py38, py39, py310, py311, pypy, pypy3 + +[testenv] +#setenv = PYTHONPATH = {toxinidir}:{toxinidir}/configmanager + +commands = python setup.py test + # python -m unittest discover + +[testenv:py36] +basepython=python3.6 + +[testenv:py37] +basepython=python3.7 + +[testenv:py38] +basepython=python3.8 + +[testenv:py39] +basepython=python3.9 + +[testenv:py310] +basepython=python3.10 + +[testenv:py311] +basepython=python3.11 + +[testenv:py312] +basepython=python3.12 + +[testenv:py313] +basepython=python3.13 + +[testenv:pypy] +basepython=pypy + +[testenv:pypy3] +basepython=pypy3 + +[testenv:apidocs] +description = Build the API documentation + + +deps = + pydoctor>=22.3.0 +allowlist_externals = bash +commands = + bash ./apidocs.sh From 4a85aebd91d91dffd0595087dfa61982322cd246 Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 14:01:55 -0400 Subject: [PATCH 06/17] . --- apidocs.sh | 9 +++------ configargparse.py | 25 +++++++++++++------------ 2 files changed, 16 insertions(+), 18 deletions(-) diff --git a/apidocs.sh b/apidocs.sh index 0463dc75..da30ae4b 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 @@ -29,7 +26,7 @@ mkdir -p "${docs_folder}" # We generate the docs for the argparse module too, such that we can document # the methods inherited from argparse.ArgumentParser, not only the methods that configargparse overrides. # And it help to have a better vision of the whole thing also. -curl https://raw.githubusercontent.com/python/cpython/3.9/Lib/argparse.py > ./argparse.py +curl https://raw.githubusercontent.com/python/cpython/3.13/Lib/argparse.py > ./argparse.py echo "__docformat__ = 'restructuredtext'" >> ./argparse.py # Delete the file when the script exits trap "rm -f ./argparse.py" EXIT @@ -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 diff --git a/configargparse.py b/configargparse.py index fc44aa1a..f39346b8 100644 --- a/configargparse.py +++ b/configargparse.py @@ -106,7 +106,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: A config file input stream (such as an open file object). Returns: OrderedDict: Items where the keys are strings and the @@ -426,7 +426,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): @@ -447,7 +447,7 @@ def parse_toml_section_name(section_name): The following names are all valid: - .. python:: + .. code-block:: python "a.b.c" # this is best practice -> returns ("a", "b", "c") " d.e.f " # same as [d.e.f] -> returns ("d", "e", "f") @@ -463,7 +463,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 @@ -484,6 +484,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 @@ -494,7 +495,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. @@ -505,7 +506,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): @@ -602,7 +603,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 @@ -680,10 +681,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): @@ -738,7 +739,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 @@ -1346,7 +1347,7 @@ def _open_config_files(self, command_line_args): command_line_args: List of all args Returns: - list[IO]: open config files + list: open config files """ # open any default config files config_files = [] @@ -1532,7 +1533,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 From 40f7c67a1030bdfd9b9e6212b361ad8152f3e9c1 Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 16:08:00 -0400 Subject: [PATCH 07/17] Adds check --- .github/workflows/test.yml | 25 +++++++------------------ 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 691d04cf..d52e435a 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -18,9 +18,13 @@ jobs: python-version: 3.13 - name: Run linters - run: | - python -m pip install --upgrade pip black - black . --check + run: python -m pip install --upgrade pip black pydoctor>=22.3.0 + + - name: Black + run: black . --check + + - name: PyDoctor + run: pydoctor ./configargparse.py --intersphinx=https://docs.python.org/3/objects.inv --docformat=google test: name: ${{ matrix.os }} py${{ matrix.python-version }} ${{ matrix.use-docker && '(docker)' || '' }} @@ -88,21 +92,6 @@ jobs: path: .coverage retention-days: 1 - apidocs: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: 3.13 - - - name: Install requirements for documentation generation - run: python -m pip install --upgrade pip pydoctor>=22.3.0 - - - name: Generate API documentation - run: ./apidocs.sh - coverage: runs-on: ubuntu-latest needs: test From 28b93516f7642056b89d0bb1e78c440cae58aab1 Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 16:10:42 -0400 Subject: [PATCH 08/17] No need to pin an old version --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d52e435a..d35219fc 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -18,7 +18,7 @@ jobs: python-version: 3.13 - name: Run linters - run: python -m pip install --upgrade pip black pydoctor>=22.3.0 + run: python -m pip install --upgrade pip black pydoctor - name: Black run: black . --check From c336c4332be53768fec3e84a74d13b4a828c3cf8 Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 16:11:27 -0400 Subject: [PATCH 09/17] . --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d35219fc..f87b1e7b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -17,7 +17,7 @@ jobs: with: python-version: 3.13 - - name: Run linters + - name: Install linters run: python -m pip install --upgrade pip black pydoctor - name: Black From 7e43068ed871ecb5d0b48636b78aab5a2a73a568 Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 16:13:46 -0400 Subject: [PATCH 10/17] . --- apidocs.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apidocs.sh b/apidocs.sh index da30ae4b..21f34cec 100755 --- a/apidocs.sh +++ b/apidocs.sh @@ -43,4 +43,4 @@ pydoctor \ --html-output="${docs_folder}" \ ./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}" From dfc12d115744f1223dc15fc962e97fc98e0e1f4a Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Sun, 6 Jul 2025 16:17:33 -0400 Subject: [PATCH 11/17] . --- apidocs.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apidocs.sh b/apidocs.sh index 21f34cec..a3a2c670 100755 --- a/apidocs.sh +++ b/apidocs.sh @@ -26,7 +26,7 @@ mkdir -p "${docs_folder}" # We generate the docs for the argparse module too, such that we can document # the methods inherited from argparse.ArgumentParser, not only the methods that configargparse overrides. # And it help to have a better vision of the whole thing also. -curl https://raw.githubusercontent.com/python/cpython/3.13/Lib/argparse.py > ./argparse.py +curl https://raw.githubusercontent.com/python/cpython/3.9/Lib/argparse.py > ./argparse.py echo "__docformat__ = 'restructuredtext'" >> ./argparse.py # Delete the file when the script exits trap "rm -f ./argparse.py" EXIT From 14b1e1adf7a4cefa57f0458b19629be7ac6b0b35 Mon Sep 17 00:00:00 2001 From: Javier Buzzi Date: Thu, 17 Jul 2025 17:29:36 -0400 Subject: [PATCH 12/17] Apply suggestions from code review Co-authored-by: tristanlatr <19967168+tristanlatr@users.noreply.github.com> --- .github/workflows/test.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index f87b1e7b..7c7b9a19 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -23,8 +23,8 @@ jobs: - name: Black run: black . --check - - name: PyDoctor - run: pydoctor ./configargparse.py --intersphinx=https://docs.python.org/3/objects.inv --docformat=google + - 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)' || '' }} From 0e9c2148ad0426d9d061500074e77cfa7322cf27 Mon Sep 17 00:00:00 2001 From: Javier Buzzi Date: Thu, 17 Jul 2025 17:39:53 -0400 Subject: [PATCH 13/17] Update configargparse.py --- configargparse.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configargparse.py b/configargparse.py index f39346b8..d42d2662 100644 --- a/configargparse.py +++ b/configargparse.py @@ -447,7 +447,7 @@ def parse_toml_section_name(section_name): The following names are all valid: - .. code-block:: python + python:: "a.b.c" # this is best practice -> returns ("a", "b", "c") " d.e.f " # same as [d.e.f] -> returns ("d", "e", "f") From 6df32f3236b7084b53237f072dafd89948c04f5f Mon Sep 17 00:00:00 2001 From: Javier Buzzi Date: Thu, 17 Jul 2025 17:40:48 -0400 Subject: [PATCH 14/17] Update configargparse.py --- configargparse.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configargparse.py b/configargparse.py index d42d2662..6fd375d3 100644 --- a/configargparse.py +++ b/configargparse.py @@ -447,7 +447,7 @@ def parse_toml_section_name(section_name): The following names are all valid: - python:: + .. python:: "a.b.c" # this is best practice -> returns ("a", "b", "c") " d.e.f " # same as [d.e.f] -> returns ("d", "e", "f") From bc5102308392aa1de8ad35184f25b5d2f106a2bc Mon Sep 17 00:00:00 2001 From: Javier Buzzi Date: Thu, 17 Jul 2025 17:42:40 -0400 Subject: [PATCH 15/17] Update configargparse.py --- configargparse.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configargparse.py b/configargparse.py index 6fd375d3..e29edc15 100644 --- a/configargparse.py +++ b/configargparse.py @@ -106,7 +106,7 @@ def parse(self, stream): one of: "yes", "no", "on", "off", "true", "false". Otherwise an error will be raised. Args: - stream: A config file input stream (such as an open file object). + stream (IO): A config file input stream (such as an open file object). Returns: OrderedDict: Items where the keys are strings and the From 9ef50d1b1e6f1705bdbaefbd05d833a350e96533 Mon Sep 17 00:00:00 2001 From: Javier Buzzi Date: Thu, 17 Jul 2025 17:43:03 -0400 Subject: [PATCH 16/17] Update configargparse.py --- configargparse.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configargparse.py b/configargparse.py index e29edc15..261462e7 100644 --- a/configargparse.py +++ b/configargparse.py @@ -1347,7 +1347,7 @@ def _open_config_files(self, command_line_args): command_line_args: List of all args Returns: - list: open config files + list[IO]: open config files """ # open any default config files config_files = [] From 424e53e9a10a559202e57381e63c17cdfa24109b Mon Sep 17 00:00:00 2001 From: kingbuzzman Date: Thu, 17 Jul 2025 17:53:08 -0400 Subject: [PATCH 17/17] Updates link --- configargparse.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configargparse.py b/configargparse.py index 261462e7..71e916af 100644 --- a/configargparse.py +++ b/configargparse.py @@ -106,7 +106,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 @@ -1347,7 +1347,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 = []