Merge branch 'master' into fix/720hardlink_index

.github/workflows/pydoctor_primer.yaml

@@ -0,0 +1,117 @@
+name: Run pydoctor_primer
+
+on:
+  # Only run on PR, since we diff against master
+  pull_request:
+    paths-ignore:
+    - 'pydoctor/test/**'
+    - 'docs/**'
+    - '*.rst'
+    - '*.txt'
+    - '*.in'
+    - '*.md'
+    - '.*'
+    - 'setup.py'
+
+
+jobs:
+  pydoctor_primer:
+    name: Run pydoctor_primer
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: pydoctor_to_test
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: Install pydoctor_primer
+        run: |
+          python -m pip install -U pip
+          pip install git+https://github.com/twisted/pydoctor_primer.git
+      - name: Run pydoctor_primer
+        shell: bash
+        run: |
+          cd pydoctor_to_test
+          echo "new commit"
+          git rev-list --format=%s --max-count=1 $GITHUB_SHA
+
+          MERGE_BASE=$(git merge-base $GITHUB_SHA origin/$GITHUB_BASE_REF)
+          git checkout -b base_commit $MERGE_BASE
+          echo "base commit"
+          git rev-list --format=%s --max-count=1 base_commit
+
+          echo ''
+          cd ..
+          # fail action if exit code isn't zero or one
+          (
+            pydoctor_primer \
+            --repo pydoctor_to_test \
+            --new $GITHUB_SHA --old base_commit \
+            --debug \
+            --output concise \
+            -j 8 \
+            | tee diff.txt
+          ) || [ $? -eq 1 ]
+
+      - name: Post comment
+        id: post-comment
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const MAX_CHARACTERS = 30000
+            const MAX_CHARACTERS_PER_PROJECT = MAX_CHARACTERS / 3
+
+            const fs = require('fs')
+            let data = fs.readFileSync('diff.txt', { encoding: 'utf8' })
+
+            function truncateIfNeeded(original, maxLength) {
+              if (original.length <= maxLength) {
+                return original
+              }
+              let truncated = original.substring(0, maxLength)
+              // further, remove last line that might be truncated
+              truncated = truncated.substring(0, truncated.lastIndexOf('\n'))
+              let lines_truncated = original.split('\n').length - truncated.split('\n').length
+              return `${truncated}\n\n... (truncated ${lines_truncated} lines) ...`
+            }
+
+            const projects = data.split('\n\n')
+            // don't let one project dominate
+            data = projects.map(project => truncateIfNeeded(project, MAX_CHARACTERS_PER_PROJECT)).join('\n\n')
+            // posting comment fails if too long, so truncate
+            data = truncateIfNeeded(data, MAX_CHARACTERS)
+
+            console.log("Diff from pydoctor_primer:")
+            console.log(data)
+
+            let body
+            if (data.trim()) {
+              body = 'Diff from [pydoctor_primer](https://github.com/tristanlatr/pydoctor_primer), showing the effect of this PR on open source code:\n```diff\n' + data + '```'
+            } else {
+              body = "According to [pydoctor_primer](https://github.com/tristanlatr/pydoctor_primer), this change doesn't affect pydoctor warnings on a corpus of open source code. ✅"
+            }
+            const ev = JSON.parse(
+              fs.readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8')
+            )
+            const prNumber = ev.pull_request.number
+
+            await github.rest.issues.createComment({
+              issue_number: prNumber,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body
+            })
+            return prNumber
+
+      - name: Hide old comments
+        uses: kanga333/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          leave_visible: 1
+          issue_number: ${{ steps.post-comment.outputs.result }}

.github/workflows/system.yaml

@@ -18,16 +18,9 @@ jobs:
     - uses: actions/checkout@v2
 
     - name: Set up CPython
-      if: ${{ matrix.tox_target == 'python-igraph-apidocs' }}
       uses: actions/setup-python@v2
       with:
-        python-version: '3.8'
-
-    - name: Set up PyPy
-      if: ${{ matrix.tox_target != 'python-igraph-apidocs' }}
-      uses: actions/setup-python@v2
-      with:
-        python-version: 'pypy-3.6'
+        python-version: '3.11'
 
     - name: Install tox
       run: |

.github/workflows/unit.yaml

@@ -14,13 +14,13 @@ jobs:
 
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9, 3.10.8, 3.11.0, pypy-3.6]
+        python-version: [pypy-3.7, 3.7, 3.8, 3.9, '3.10', 3.11, '3.12.0-rc.3']
         os: [ubuntu-20.04]
         include:
           - os: windows-latest
-            python-version: 3.6
+            python-version: 3.7
           - os: macos-latest
-            python-version: 3.6
+            python-version: 3.7
 
     steps:
     - uses: actions/checkout@v2
@@ -45,8 +45,8 @@ jobs:
       run: |
         tox -e test
 
-    - name: Run unit tests with latest Twisted version
-      if: matrix.python-version != '3.6' && matrix.python-version != 'pypy-3.6'
+    - name: Run unit tests with latest Twisted version (only for python 3.8 and later)
+      if: matrix.python-version != '3.7' && matrix.python-version != 'pypy-3.7'
       run: |
         tox -e test-latest-twisted
 

README.rst

@@ -76,18 +76,45 @@ What's New?
 in development
 ^^^^^^^^^^^^^^
 
+This is the last major release to support Python 3.7.
+
+* Drop support for Python 3.6
+* Add support for Python 3.12
+* `ExtRegistrar.register_post_processor()` now supports a `priority` argument that is an int.
+  Highest priority callables will be called first during post-processing.
+* Fix too noisy ``--verbose`` mode (suppres some ambiguous annotations warnings).
+
+pydoctor 23.9.1
+^^^^^^^^^^^^^^^
+
+* Fix regression in link not found warnings' line numbers.
+
+pydoctor 23.9.0
+^^^^^^^^^^^^^^^
+
+This is the last major release to support Python 3.6.
+
 * Do not show `**kwargs` when keywords are specifically documented with the `keyword` field
   and no specific documentation is given for the `**kwargs` entry.
 * Fix annotation resolution edge cases: names are resolved in the context of the module 
   scope when possible, when impossible, the theoretical runtime scopes are used. A warning can
   be reported when an annotation name is ambiguous (can be resolved to different names 
   depending on the scope context) with option ``-v``.
+* Ensure that explicit annotation are honored when there are multiple declarations of the same name.
+* Use stricter verification before marking an attribute as constant: 
+   - instance variables are never marked as constant
+   - a variable that has several definitions will not be marked as constant
+   - a variable declaration under any kind of control flow block will not be marked as constant
+* Do not trigger warnings when pydoctor cannot make sense of a potential constant attribute 
+  (pydoctor is not a static checker).
 * Fix presentation of type aliases in string form.
 * Improve the AST colorizer to output less parenthesis when it's not required.
 * Fix colorization of dictionary unpacking.
 * Improve the class hierarchy such that it links top level names with intersphinx when possible.
 * Add highlighting when clicking on "View In Hierarchy" link from class page.
 * Recognize variadic generics type variables (PEP 646).
+* Fix support for introspection of cython3 generated modules.
+* Instance variables are marked as such across subclasses.
 
 pydoctor 23.4.1
 ^^^^^^^^^^^^^^^

docs/tests/test_standard_library_docs.py

@@ -23,4 +23,11 @@ def test_std_lib_docs() -> None:
         elif entry.is_dir() and entry.joinpath('__init__.py').exists(): # Package
             assert BASE_DIR.joinpath('Lib.'+entry.name+'.html').exists()
 
-
+def test_std_lib_logs() -> None:
+    """
+    'Cannot parse file' do not appear too much.
+    This test expect a run.log file in cpython-output directory
+    """
+    log = (BASE_DIR / 'run.log').read_text()
+    assert log.count('cannot parse file') == 4
+

pydoctor/_configparser.py

@@ -20,6 +20,8 @@
 >>> parser = ArgumentParser(..., default_config_files=['./pyproject.toml', 'setup.cfg', 'my_super_tool.ini'], config_file_parser_class=MixedParser)
 
 """
+from __future__ import annotations
+
 import argparse
 from collections import OrderedDict
 import re