v0.5.0

We're happy to announce the feature release of docstub 0.5.0 on 2025-10-25!
This release supports Python 3.12 to 3.14.

Enhancement

• Improve output and error reporting. All output of docstub is now controllable with the existing --verbose option and the new --quiet option. Also indicate the (severity) level of output with a single char, e.g. "I" for information or "W" for warnings (#79).
• Automatically add a py.typed file alongside generated stubs. This ensures that type checkers can make use of the stubs (#98).
• Include stubs for docstub in the distribution packages (#96).

Deprecations

• Remove array expressions inspired by scikit-image. This impacts forms like (M, 3) int array. Instead, prefer the more expressive convention used by scikit-learn, for example, array of dtype int and shape (M, 3) (#77).

Bug Fixes

• Ensure glob patterns to ignore files work with relative paths. Previously, if docstub was invoked on a relative path, no files would be ignored (#78).
• Avoid infinite loop in module_name_from_path (#89).

Documentation

• Setup HTML documentation on Read the Docs (#84).
• Update documentation and add a glossary with a few central terms (#84).
• Add a dedicated installation guide to the documentation (#97).
• Add a short section on "Distributing stubs files" to the introduction guide. This also describes docstubs behavior regarding py.typed files (#98).
• Improve introduction statement in introduction guide (#100).

DevOps

• Add (some) suggestions from repo-review (#81).
• Bump actions/checkout from 4 to 5 in the actions group (#82).
• Use macos-latest runner (#85).
• Bump actions/setup-python and pypa/gh-action-pypi-publish (#86).
• Add zizmor as pre-commit hook (#87).
• Add 14 days cooldown period to dependabot (#88).
• Test on Python 3.14 (#90).
• Explicitly place Read the Docs ethical ads (#92).
• Pad ethical ad from Read the Docs (#93).
• Add the version string to the sidebar in the HTML docs (#95).
• Prevent .github/scripts/assert-unchanged.sh from exiting early (#98).

Maintenance

• Use dependency-groups for development dependencies (#83).
• Refactor reporting to use Python's native logging implementation (#79).
• Link to introduction on RTD in README (#94).

Contributors

3 authors added to this release (alphabetically):

• @dependabot[bot]
• Lars Grüter (@lagru)
• Seth G (@geographika)

3 reviewers added to this release (alphabetically):

• Dan Baston (@dbaston)
• Lars Grüter (@lagru)
• Seth G (@geographika)

v0.4.0

docstub 0.4.0

We're happy to announce the release of docstub 0.4.0! 🎉

Highlights

• Inline annotations override types in docstrings
  This provides a fallback and a solution in case docstub is missing support or if Python's type system can't express what you want to say in the docstring (#61).

• Derive types from import statements in parsed files
  Types imported in your project are made implicitly available to reference in docstrings. You no longer need to declare them explicitly in configuration (#63).

• Ignore files
  A new command line option --ignore and a config option ignore_files now help you ignore files you don't want to create stubs for (#60).

Find a more detailed list of pull requests contributing to this release below.

Enhancement

• Ensure that existing inline annotations aren't overridden by annotations in docstrings. This allows documenting types inside docstrings that are not (yet) supported by Python's type system. Instead, more general inlined type annotations can be used as a fallback. Previously, annotations in docstrings would take precedence (#61).
• Add new command line option --ignore and config option ignore_files. Both allow ignoring directories or files in the package directory that docstub is invoked on (#60).
• Use import statements in the parsed package to collect additional type information. This makes imported types available in the same module scope to be used in docstrings. Some of the imports can be used package wide even if not imported there. E.g. from pathlib import Path will allow using "Path" inside the modules scope. Outside of that module, you must use the full pathlib.Path to reference that type (#63).
• Type nicknames specified in the configuration are now resolved recursively. That means one nickname can point to another nickname (#63).
• Add --no-cache option to docstub run which avoids creating or reading to a cache entirely; mostly useful during development. Also note when the cache is used during type collection (#69).
• Add docstub clean command to remove temporary files such as the cache directory (#69).
• Relax grammar for specifying optional and additional information after type descriptions in docstrings. You can now specify as much optional information after the first top-level comma as you want and in arbitrary order, e.g., some_param: int, in range (0, 1), optional. This optional information is ignored by docstub (#70).

Bug Fixes

• Avoid an AttributeError when using a union of dtypes in an array expression (#52).
• Support referencing types from collections.abc and typing with their module name included. So collections.abc.Iterable should work now (#53).
• Make sure that no warning is raised for inline annotations, if there is no conflicting annotation in a docstring. Otherwise, the inlined annotation takes precedence and a warning is printed (#66).
• Nesting natural language containers didn't work in all cases. Now, doctypes like list of (list of int) will work. For complex nested types, falling back to Python's typing syntax might be more readable though (#71).

Documentation

• Add a reference document for the configuration file (#60).

DevOps

• Fix broken diff check due to changed output behavior (#54).
• Add pull request template for changelist (#67).

Maintenance

• Improve walking of the source directory (#68).
• Prepare release of version 0.4.0 (#72).

Contributors

2 authors added to this release (alphabetically):

• Lars Grüter (@lagru)
• Oriol Abril-Pla (@OriolAbril)

2 reviewers added to this release (alphabetically):

• Lars Grüter (@lagru)
• Stefan van der Walt (@stefanv)

v0.3.0

docstub 0.3.0

This release marks the first "Alpha" release of docstub. 🎉

Note

This release points at 0.3.0.post0 and is almost identical to v0.3.0rc0 and v0.3.0. It addresses problems with the deployment workflow. v0.3.0rc0 and v0.3.0 were pointing to the same commit. This lead to PyPI rejecting the upload for v0.3.0. Accordingly, 0.3.0.post0 is made on a new commit that updates deprecated metadata in the pyproject.toml.

Highlights

• A revamped command line interface
  Stubs are created with the new subcommand docstub run which leaves room to add other subcommands in the future (#49).
  The new subcommand also includes two new options --group-errors (#30) and --allow-errors to help with adopting docstub gradually (#32).

• Improved error reporting and statistics
  When docstub encounters errors in the package it is running on it will now point at the file and line where they are originating from (#10).
  Similarly, docstub will report the total number of errors, types that it didn't know where to import from and the total runtime.

• Improved typing support
  Module and class attributes can now be typed in docstrings too (#18).
  This includes support for the special case of dataclasses (#26).
  You can now document generator functions with the "Yields" and "Receives" docstring sections (#29).
  For edge cases, that docstub doesn't yet (correctly) support, you can now wrap lines in # docstub: off and # docstub: on.
  This selectively prevents docstub from changing lines during stub creation (#25).

• Improved configuration
  Simplified the configuration file.
  Declaring external types should be a lot more straightforward.
  A reference for the configuration file is scheduled for the next release (#45).

• We added a user guide to get started with using docstub as well as a reference for the extended typing syntax that can be used in docstrings (#24).

Find a more detailed list of pull requests contributing to this release below.

Enhancement

• Stub files are now created inplace if no explicit output directory is specified.
  Pre-existing stub files that are not managed by docstub are preserved as before (#28).
• You can now indicate a plural with (s) in expressions like list of int(s) (#37).
  The grammar supporting the typing syntax in docstring should be better behaved for edge cases now.
• Collect docnames of analyzed source in advance (#2).
• Point to precise line in parsed source for parsing problems (#10).
• Support attributes and type aliases (#18).
• Add direct support for dataclasses (#26).
• Support Yields section and Generator functions (#29).
• Add --group-errors option (#30).
• Add --allow-errors command line option (#32).
• Support combined NumPyDoc params (#41).

Bug Fixes

• Only use | None for optional parameters if appropriate (#14).
• Check test suite with mypy (#27).
• fix check for length 1 literal (#40).
• Allow signed numbers in literals (#46).

Performance

• Types collected while creating stubs for a package are now cached so that the next run is a lot faster (#15).

Documentation

• Attribute copyright to Scientific Python Developers (#4).
• Reword descriptions in manual (#23).
• Refactor and document doctype grammar (#33).
• Add minimal documentation (#24).

Devops

• Add basic CI configuration (#8).
• Enable doctests by default (#12).
• Use mypy.stubtest in CI (#25).
• Check test suite with mypy (#27).
• Check tests/ with basedpyright in CI in "standard" mode (#50).
• Prepare release of version 0.3.0 (#51).

Maintenance

• Fix python_requires (#5).
• Refactor and document doctype grammar (#33).
• Update import for Generator and Callable types (#34).
• Refactor configuration fields (#45).
• Add minimal documentation (#24).
• Move main CLI functionality into docstub run subcommand (#49).

Contributors

3 authors added to this release (alphabetically):

• Lars Grüter (@lagru)
• Marianne Corvellec (@mkcor)
• Oriol Abril-Pla (@OriolAbril)

4 reviewers added to this release (alphabetically):

• Brigitta Sipőcz (@bsipocz)
• Lars Grüter (@lagru)
• Marianne Corvellec (@mkcor)
• Oriol Abril-Pla (@OriolAbril)

v0.3.0rc0

docstub 0.3.0rc0

This release marks the first "Alpha" release of docstub. 🎉

Highlights

• A revamped command line interface
  Stubs are created with the new subcommand docstub run which leaves room to add other subcommands in the future (#49).
  The new subcommand also includes two new options --group-errors (#30) and --allow-errors to help with adopting docstub gradually (#32).

• Improved error reporting and statistics
  When docstub encounters errors in the package it is running on it will now point at the file and line where they are originating from (#10).
  Similarly, docstub will report the total number of errors, types that it didn't know where to import from and the total runtime.

• Improved typing support
  Module and class attributes can now be typed in docstrings too (#18).
  This includes support for the special case of dataclasses (#26).
  You can now document generator functions with the "Yields" and "Receives" docstring sections (#29).
  For edge cases, that docstub doesn't yet (correctly) support, you can now wrap lines in # docstub: off and # docstub: on.
  This selectively prevents docstub from changing lines during stub creation (#25).

• Improved configuration
  Simplified the configuration file.
  Declaring external types should be a lot more straightforward.
  A reference for the configuration file is scheduled for the next release (#45).

• We added a user guide to get started with using docstub as well as a reference for the extended typing syntax that can be used in docstrings (#24).

Find a more detailed list of pull requests contributing to this release below.

Enhancement

• Stub files are now created inplace if no explicit output directory is specified.
  Pre-existing stub files that are not managed by docstub are preserved as before (#28).
• You can now indicate a plural with (s) in expressions like list of int(s) (#37).
  The grammar supporting the typing syntax in docstring should be better behaved for edge cases now.
• Collect docnames of analyzed source in advance (#2).
• Point to precise line in parsed source for parsing problems (#10).
• Support attributes and type aliases (#18).
• Add direct support for dataclasses (#26).
• Support Yields section and Generator functions (#29).
• Add --group-errors option (#30).
• Add --allow-errors command line option (#32).
• Support combined NumPyDoc params (#41).

Bug Fixes

• Only use | None for optional parameters if appropriate (#14).
• Check test suite with mypy (#27).
• fix check for length 1 literal (#40).
• Allow signed numbers in literals (#46).

Performance

• Types collected while creating stubs for a package are now cached so that the next run is a lot faster (#15).

Documentation

• Attribute copyright to Scientific Python Developers (#4).
• Reword descriptions in manual (#23).
• Refactor and document doctype grammar (#33).
• Add minimal documentation (#24).

Devops

• Add basic CI configuration (#8).
• Enable doctests by default (#12).
• Use mypy.stubtest in CI (#25).
• Check test suite with mypy (#27).
• Check tests/ with basedpyright in CI in "standard" mode (#50).
• Prepare release of version 0.3.0 (#51).

Maintenance

• Fix python_requires (#5).
• Refactor and document doctype grammar (#33).
• Update import for Generator and Callable types (#34).
• Refactor configuration fields (#45).
• Add minimal documentation (#24).
• Move main CLI functionality into docstub run subcommand (#49).

Contributors

3 authors added to this release (alphabetically):

• Lars Grüter (@lagru)
• Marianne Corvellec (@mkcor)
• Oriol Abril-Pla (@OriolAbril)

4 reviewers added to this release (alphabetically):

• Brigitta Sipőcz (@bsipocz)
• Lars Grüter (@lagru)
• Marianne Corvellec (@mkcor)
• Oriol Abril-Pla (@OriolAbril)