Merge branch 'main' into refactoring

Author: lagru

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+<!--
+- Reference relevant issues or related pull requests with their URL / #<number>.
+- Use `pre-commit` to check and format code.
+-->
+
+
+## Release note
+
+For maintainers and optionally contributors, please refer to [changelist's README](https://github.com/scientific-python/changelist) on how to document this PR for the release notes.
+
+```release-note
+...
+```

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "quarterly"
+    labels:
+      - "devops"
+      - "bot"
+    groups:
+      actions:
+        patterns:
+          - "*"

.github/workflows/cd.yml

@@ -23,7 +23,7 @@ jobs:
     permissions:
       id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
     name: pre-commit
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - uses: actions/setup-python@v5
@@ -50,7 +50,7 @@ jobs:
         python-version: ["3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
@@ -73,7 +73,10 @@ jobs:
 
       - name: Compare example stubs
         run: |
-          python -m docstub run -v --config=examples/docstub.toml examples/example_pkg
+          python -m docstub run -v \
+              --config=examples/docstub.toml \
+              --out-dir=examples/example_pkg-stubs \
+              examples/example_pkg
           git diff --exit-code examples/ && echo "Stubs for example_pkg did not change"
 
       - name: Generate stubs for docstub

.pre-commit-config.yaml

@@ -7,33 +7,28 @@ exclude: |
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: "cef0300fd0fc4d2a87a85fa2093c6b283ea36f4b"  # frozen: v5.0.0
+    rev: "3e8a8703264a2f4a69428a0aa4dcb512790b2c8c"  # frozen: v6.0.0
     hooks:
       - id: check-added-large-files
       - id: check-ast
-      - id: check-builtin-literals
       - id: check-case-conflict
       - id: check-merge-conflict
       - id: check-symlinks
-      - id: check-yaml
-        args: [--allow-multiple-documents]
       - id: check-json
       - id: check-toml
+      - id: check-yaml
+        args: [--allow-multiple-documents]
       - id: debug-statements
-      - id: end-of-file-fixer
+      - id: detect-private-key
       - id: mixed-line-ending
       - id: name-tests-test
         args: ["--pytest-test-first"]
-      - id: requirements-txt-fixer
       - id: trailing-whitespace
-
-  - repo: https://github.com/psf/black
-    rev: "1b2427a2b785cc4aac97c19bb4b9a0de063f9547"  # frozen: 24.10.0
-    hooks:
-      - id: black
+        args: [--markdown-linebreak-ext=md]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "75b98813cfb7e663870a28c74366a1e99d7bfe79"  # frozen: v0.6.9
+    rev: "0acff885bcb16381b67930fefb91e460202f172c"  # frozen: v0.12.10
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: ["--fix", "--show-fixes", "--exit-non-zero-on-fix"]
+      - id: ruff-format

LICENSE

@@ -0,0 +1,88 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Source: https://github.com/scientific-python/docstub
+
+Files: *
+Copyright: 2025, Scientific Python Developers
+           2024, Lars Grüter
+License: BSD 3-Clause
+
+Files: src/docstub/_vendored/stdlib.py
+Copyright: 2001-2025, Python Software Foundation
+License: PSF-2.0
+
+License: BSD-3-Clause
+  All rights reserved.
+  .
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions are met:
+  .
+  * Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+  .
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+  .
+  * Neither the name of the vector package developers nor the names of its
+    contributors may be used to endorse or promote products derived from
+    this software without specific prior written permission.
+  .
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+License: PSF-2.0
+  PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+  --------------------------------------------
+  .
+  1. This LICENSE AGREEMENT is between the Python Software Foundation
+  ("PSF"), and the Individual or Organization ("Licensee") accessing and
+  otherwise using this software ("Python") in source or binary form and
+  its associated documentation.
+  .
+  2. Subject to the terms and conditions of this License Agreement, PSF hereby
+  grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
+  analyze, test, perform and/or display publicly, prepare derivative works,
+  distribute, and otherwise use Python alone or in any derivative version,
+  provided, however, that PSF's License Agreement and PSF's notice of copyright,
+  i.e., "Copyright (c) 2001 Python Software Foundation; All Rights Reserved"
+  are retained in Python alone or in any derivative version prepared by Licensee.
+  .
+  3. In the event Licensee prepares a derivative work that is based on
+  or incorporates Python or any part thereof, and wants to make
+  the derivative work available to others as provided herein, then
+  Licensee hereby agrees to include in any such work a brief summary of
+  the changes made to Python.
+  .
+  4. PSF is making Python available to Licensee on an "AS IS"
+  basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
+  IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
+  DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
+  FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON WILL NOT
+  INFRINGE ANY THIRD PARTY RIGHTS.
+  .
+  5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
+  FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
+  A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON,
+  OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
+  .
+  6. This License Agreement will automatically terminate upon a material
+  breach of its terms and conditions.
+  .
+  7. Nothing in this License Agreement shall be deemed to create any
+  relationship of agency, partnership, or joint venture between PSF and
+  Licensee.  This License Agreement does not grant permission to use PSF
+  trademarks or trade name in a trademark sense to endorse or promote
+  products or services of Licensee, or any third party.
+  .
+  8. By copying, installing or otherwise using Python, Licensee
+  agrees to be bound by the terms and conditions of this License
+  Agreement.

LICENSE.txt

@@ -15,7 +15,8 @@ Options:
   -h, --help  Show this message and exit.
 
 Commands:
-  run  Generate Python stub files.
+  clean  Clean the cache.
+  run    Generate Python stub files.
 ```
 
 <!--- end cli-docstub --->
@@ -43,15 +44,39 @@ Options:
   --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.
 ```
 
 <!--- end cli-docstub-run --->
+
+
+## Command `docstub clean`
+
+<!--- The following block is checked by the test suite --->
+<!--- begin cli-docstub-clean --->
+
+```plain
+Usage: docstub clean [OPTIONS]
+
+  Clean the cache.
+
+  Looks for a cache directory relative to the current working directory. If
+  one exists, remove it.
+
+Options:
+  -v, --verbose  Print more details (repeatable).
+  -h, --help     Show this message and exit.
+```
+
+<!--- end cli-docstub-clean --->

docs/command_line.md

@@ -0,0 +1,95 @@
+# Configuration reference
+
+Docstub will automatically look for configuration in files named
+
+- `pyproject.toml`, and
+- `docstub.toml`
+
+in the current working directory.
+If config files are explicitly passed to the command line interface via the `--config` option, docstub won't look implicitly look for files in the current directory.
+Multiple configuration files can be used, whose content will be merged.
+
+Out of the box, docstub makes use of an internal configuration file [`numpy_config.toml`](../src/docstub/numpy_config.toml) which provides defaults to use NumPy types.
+
+
+## Configuration fields in `[tool.docstub]`
+
+All configuration must be declared inside a `[tool.docstub]` table.
+
+
+### `ignore_files`
+
+- [TOML type](https://toml.io/en/latest): array of string(s)
+
+Ignore files and directories matching these [glob-style patterns](https://docs.python.org/3/library/glob.html#glob.translate).
+Patterns that don't start with "/" are interpreted as relative to the
+directory that contains the Python package for which stubs are generated.
+
+Example:
+
+```toml
+[tool.docstub]
+ignore_files = [
+    "**/tests",
+]
+```
+
+- Will ignore any directory anywhere that is named `tests`.
+
+
+### `types`
+
+- [TOML type](https://toml.io/en/latest): table, mapping string to string
+
+Types and their external modules to use in docstrings.
+Docstub can't yet automatically discover where to import types from other packages from.
+Instead, you can provide this information explicitly.
+Any type on the left side will be associated with the given "module" on the right side.
+
+Example:
+
+```toml
+[tool.docstub.types]
+Path = "pathlib"
+NDArray = "numpy.typing"
+```
+
+- Will allow using `Path` in docstrings and will use `from pathlib import Path` to import the type.
+- Will allow using `NDarray` in docstrings and will use `from numpy.typing import NDArray` to import the type.
+
+
+### `type_prefixes`
+
+- [TOML type](https://toml.io/en/latest): table, mapping string to string
+
+Prefixes for external modules to match types in docstrings.
+Docstub can't yet automatically discover where to import types from other packages from.
+Instead, you can provide this information explicitly.
+Any type in a docstring whose prefix matches the name given on the left side, will be associated with the given "module" on the right side.
+
+Example:
+
+```toml
+[tool.docstub.type_prefixes]
+np = "numpy"
+plt = "matplotlib.pyplot
+```
+
+- Will match `np.uint8` and `np.typing.NDarray` and use `import numpy as np`.
+- Will match `plt.Figure` use `import matplotlib.pyplot as plt`.
+
+
+### `type_nicknames`
+
+- [TOML type](https://toml.io/en/latest): table, mapping string to string
+
+Nicknames for types that can be used in docstrings to describe valid Python types or annotations.
+
+Example:
+
+```toml
+[tool.docstub.type_nicknames]
+func = "Callable"
+```
+
+- Will map `func` to the `Callable` type from the `typing` module.