Merge branch 'main' into html-docs

Author: lagru

.github/dependabot.yml

@@ -5,6 +5,8 @@ updates:
     directory: "/"
     schedule:
       interval: "quarterly"
+    cooldown:
+      default-days: 14
     labels:
       - "devops"
       - "bot"

.github/workflows/cd.yml

@@ -26,8 +26,9 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
+          persist-credentials: false
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.13"
 
@@ -38,4 +39,4 @@ jobs:
           python -m build --sdist --wheel
 
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0

.github/workflows/ci.yml

@@ -7,6 +7,8 @@ on:
     branches:
       - main
 
+permissions: {}
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -30,10 +32,11 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v5
+          persist-credentials: false
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
-      - uses: pre-commit/action@v3.0.1
+      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd  # v3.0.1
         with:
           extra_args: --hook-stage manual --all-files
 
@@ -46,15 +49,19 @@ jobs:
         runs-on:
           - { short: linux, name: ubuntu-latest }
           - { short: win, name: windows-latest }
-          - { short: macos, name: macos-14 }
-        python-version: ["3.12", "3.13"]
+          - { short: macos, name: macos-latest }
+        python-version: ["3.12", "3.14"]
+        include:
+          - runs-on: { short: linux, name: ubuntu-latest }
+            python-version: "3.13"
 
     steps:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
+          persist-credentials: false
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true

.pre-commit-config.yaml

@@ -27,8 +27,13 @@ repos:
         args: [--markdown-linebreak-ext=md]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "0acff885bcb16381b67930fefb91e460202f172c"  # frozen: v0.12.10
+    rev: "f298305809c552671cc47e0fec0ba43e96c146a2"  # frozen: v0.13.2
     hooks:
       - id: ruff-check
         args: ["--fix", "--show-fixes", "--exit-non-zero-on-fix"]
       - id: ruff-format
+
+  - repo: https://github.com/woodruffw/zizmor-pre-commit
+    rev: 3c10df247c55cf21f75003105b879f145096bd4a  # frozen: v1.14.2
+    hooks:
+      - id: zizmor

docs/command_line.md

@@ -40,25 +40,30 @@ Usage: docstub run [OPTIONS] PACKAGE_PATH
   annotations or to override them.
 
 Options:
-  -o, --out-dir PATH  Set output directory explicitly. Stubs will be directly
-                      written into that directory while preserving the
-                      directory structure under `PACKAGE_PATH`. Otherwise,
-                      stubs are generated inplace.
-  --config PATH       Set one or more configuration file(s) explicitly.
-                      Otherwise, it will look for a `pyproject.toml` or
-                      `docstub.toml` in the current directory.
-  --ignore GLOB       Ignore files matching this glob-style pattern. Can be
-                      used multiple times.
-  --group-errors      Group identical errors together and list where they
-                      occurred. Will delay showing errors until all files have
-                      been processed. Otherwise, simply report errors as the
-                      occur.
-  --allow-errors INT  Allow this many or fewer errors. If docstub reports
-                      more, exit with error code '1'. This is useful to adopt
-                      docstub gradually.  [default: 0; x>=0]
-  --no-cache          Ignore pre-existing cache and don't create a new one.
-  -v, --verbose       Print more details (repeatable).
-  -h, --help          Show this message and exit.
+  -o, --out-dir PATH     Set output directory explicitly. Stubs will be
+                         directly written into that directory while preserving
+                         the directory structure under `PACKAGE_PATH`.
+                         Otherwise, stubs are generated inplace.
+  --config PATH          Set one or more configuration file(s) explicitly.
+                         Otherwise, it will look for a `pyproject.toml` or
+                         `docstub.toml` in the current directory.
+  --ignore GLOB          Ignore files matching this glob-style pattern. Can be
+                         used multiple times.
+  --group-errors         Group identical errors together and list where they
+                         occurred. Will delay showing errors until all files
+                         have been processed. Otherwise, simply report errors
+                         as the occur.
+  --allow-errors INT     Allow this many or fewer errors. If docstub reports
+                         more, exit with error code '1'. This is useful to
+                         adopt docstub gradually.   [default: 0; x>=0]
+  -W, --fail-on-warning  Return non-zero exit code when a warning is raised.
+                         Will add to '--allow-errors'.
+  --no-cache             Ignore pre-existing cache and don't create a new one.
+  -v, --verbose          Print more details. Use once to show information
+                         messages. Use '-vv' to print debug messages.
+  -q, --quiet            Print less details. Use once to hide warnings. Use
+                         '-qq' to completely silence output.
+  -h, --help             Show this message and exit.
 ```
 
 <!--- end cli-docstub-run --->
@@ -78,7 +83,10 @@ Usage: docstub clean [OPTIONS]
   one exists, remove it.
 
 Options:
-  -v, --verbose  Print more details (repeatable).
+  -v, --verbose  Print more details. Use once to show information messages.
+                 Use '-vv' to print debug messages.
+  -q, --quiet    Print less details. Use once to hide warnings. Use '-qq' to
+                 completely silence output.
   -h, --help     Show this message and exit.
 ```
 

pyproject.toml

@@ -27,6 +27,7 @@ classifiers = [
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Code Generators",
     "Topic :: Scientific/Engineering",
 ]

src/docstub/_analysis.py

@@ -14,7 +14,7 @@
 
 from ._utils import accumulate_qualname, module_name_from_path, pyfile_checksum
 
-logger = logging.getLogger(__name__)
+logger: logging.Logger = logging.getLogger(__name__)
 
 
 def _shared_leading_qualname(*qualnames):
@@ -104,6 +104,18 @@ def typeshed_Incomplete(cls):
         return import_
 
     def format_import(self, relative_to=None):
+        """Format import as valid Python import statement.
+
+        Parameters
+        ----------
+        relative_to : str, optional
+            If a dot-delimited module name is given, format the import relative
+            to it.
+
+        Returns
+        -------
+        formatted : str
+        """
         if self.implicit:
             msg = f"cannot import implicit object: {self.implicit!r}"
             raise RuntimeError(msg)
@@ -265,20 +277,6 @@ def common_known_types():
     return types
 
 
-@dataclass(slots=True, kw_only=True)
-class TypeCollectionResult:
-    types: dict[str, PyImport]
-    type_prefixes: dict[str, PyImport]
-
-    @classmethod
-    def serialize(cls, result):
-        pass
-
-    @classmethod
-    def deserialize(cls, result):
-        pass
-
-
 class TypeCollector(cst.CSTVisitor):
     """Collect types from a given Python file.
 
@@ -296,7 +294,13 @@ class TypeCollector(cst.CSTVisitor):
     """
 
     class ImportSerializer:
-        """Implements the `FuncSerializer` protocol to cache `TypeCollector.collect`."""
+        """Implements the `FuncSerializer` protocol to cache `TypeCollector.collect`.
+
+        Attributes
+        ----------
+        suffix : ClassVar[str]
+        encoding : ClassVar[str]
+        """
 
         suffix = ".json"
         encoding = "utf-8"
@@ -524,7 +528,7 @@ def _resolve_nickname(self, name):
             resolved = name
         else:
             logger.warning(
-                "reached limit while resolving nicknames for %r in %s, using %r",
+                "Reached limit while resolving nicknames for %r in %s, using %r",
                 original,
                 self.current_file or "<file not known>",
                 resolved,
@@ -572,7 +576,7 @@ def match(self, search):
                     "%r (original %r) in %s matches multiple types %r, using %r",
                     search,
                     original_search,
-                    self.current_file or "<file not known>",
+                    self.current_file or "<file?>",
                     matches.keys(),
                     shortest_key,
                 )

src/docstub/_cache.py

@@ -2,21 +2,21 @@
 from functools import cached_property
 from typing import Any, Protocol
 
-logger = logging.getLogger(__name__)
+logger: logging.Logger = logging.getLogger(__name__)
 
 
-CACHE_DIR_NAME = ".docstub_cache"
+CACHE_DIR_NAME: str = ".docstub_cache"
 
 
-CACHEDIR_TAG_CONTENT = """\
+CACHEDIR_TAG_CONTENT: str = """\
 Signature: 8a477f597d28d172789f06886806bc55
 # Mark this directory as a cache [1], created by docstub [2]
 # [1] https://bford.info/cachedir/
 # [2] https://github.com/scientific-python/docstub
 """
 
 
-GITHUB_IGNORE_CONTENT = """\
+GITHUB_IGNORE_CONTENT: str = """\
 # Make git ignore this cache directory, created by docstub [1]
 # [1] https://github.com/scientific-python/docstub
 *
@@ -172,7 +172,7 @@ def cache_dir(self):
         create_cache(self._cache_dir)
 
         if _directory_size(self._cache_dir) > 512 * 1024**2:
-            logger.warning("cache size at %r exceeds 512 MiB", self._cache_dir)
+            logger.warning("Cache size at %r exceeds 512 MiB", self._cache_dir)
 
         return self._cache_dir