docstub v0.6.0

We're happy to announce the release of docstub v0.6.0 on 2025-11-04!

Enhancement

- Add the new experimental `--workers` option to `docstub run` to **generate stub files in parallel**. This can reduce runtime significantly for projects with many files. For now, multiprocessing has to be explicitly enabled by requesting a number of workers ([#110](#110)).
- **Highlight help messages** (invoked with `-h` or `--help`) of the command line interface with colors and reformat. This should improve the readability ([#109](#109)).
- Don't color output if the environment variable `NO_COLOR=1` is set ([#109](#109)).
- Support using types from the standard library module `types` directly without requiring configuration or imports for them ([#106](#106)).
- Provide file and line context in warnings that are emitted while parsing doctypes ([#108](#108)).
- Add the short command line option `-g` as an alternative to `docstub run --group-errors` ([#109](#109)).
- Hide additional debug information behind "verbosity 3" (`-vvv`). This makes the option `-vv` a bit more usable.  Also use a  more generally visible ANSI color for debug  information (bright_black) ([#104](#104)).

Performance

- Speed-up how fast docstub's command line displays help text with  the `-h` or `--help` option ([#112](#112)).

Bug Fixes

- Ensure that warnings are raised for partially documented signatures. Previously, no warning was raised for untyped parameters when at least one parameter was annotated ([#107](#107)).
- Ensure that docstub still returns a non-zero exit code when it is run with output completely disabled (`-qq`). The same applies when running docstub with  `--quiet --fail-on-warnings` ([#110](#110)).
- Ensure that warnings are raised for undocumented parameters and attributes. Previously, no warning was raised for parameters and attributes when at least that were mentioned in a docstring, but didn't have a doctype ([#111](#111)).

Contributors

1 author(s) added to this release (alphabetically):

- Lars Grüter ([@lagru](https://github.com/lagru))

docstub 0.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](#79)).
- **Automatically add a `py.typed` file** alongside generated stubs. This ensures that type checkers can make use of the stubs ([#98](#98)).
- Include stubs for docstub in the distribution packages ([#96](#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](#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](#78)).
- Avoid infinite loop in module_name_from_path ([#89](#89)).

Documentation

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

DevOps

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

Maintenance

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

Contributors

3 authors added to this release (alphabetically):

- [@dependabot[bot]](https://github.com/apps/dependabot)
- Lars Grüter ([@lagru](https://github.com/lagru))
- Seth G ([@geographika](https://github.com/geographika))

3 reviewers added to this release (alphabetically):

- Dan Baston ([@dbaston](https://github.com/dbaston))
- Lars Grüter ([@lagru](https://github.com/lagru))
- Seth G ([@geographika](https://github.com/geographika))

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](#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](#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](#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](#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](#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](#63)).
- Type nicknames specified in the configuration are now resolved recursively. That means one nickname can point to another nickname ([#63](#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](#69)).
- Add `docstub clean` command to remove temporary files such as the cache directory ([#69](#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](#70)).

Bug Fixes

- Avoid an AttributeError when using a union of dtypes in an array expression ([#52](#52)).
- Support referencing types from `collections.abc` and `typing` with their module name included. So `collections.abc.Iterable` should work now ([#53](#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](#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](#71)).

Documentation

- Add a reference document for the configuration file ([#60](#60)).

DevOps

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

Maintenance

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

Contributors

2 authors added to this release (alphabetically):

- Lars Grüter ([@lagru](https://github.com/lagru))
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

2 reviewers added to this release (alphabetically):

- Lars Grüter ([@lagru](https://github.com/lagru))
- Stefan van der Walt ([@stefanv](https://github.com/stefanv))

Version 0.3.0

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](#49)).
  The new subcommand also includes two new options `--group-errors` ([#30](#30)) and `--allow-errors` to help with adopting docstub gradually ([#32](#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](#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](#18)).
  This includes support for the special case of dataclasses ([#26](#26)).
  You can now document generator functions with the "Yields" and "Receives" docstring sections ([#29](#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](#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](#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](#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](#28)).
- You can now indicate a plural with `(s)` in expressions like `list of int(s)`  ([#37](#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](#2)).
- Point to precise line in parsed source for parsing problems ([#10](#10)).
- Support attributes and type aliases ([#18](#18)).
- Add direct support for dataclasses ([#26](#26)).
- Support Yields section and Generator functions ([#29](#29)).
- Add `--group-errors` option ([#30](#30)).
- Add `--allow-errors` command line option ([#32](#32)).
- Support combined NumPyDoc params ([#41](#41)).

Bug Fixes

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

Performance

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

Documentation

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

Devops

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

Maintenance

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

Contributors

3 authors added to this release (alphabetically):

- Lars Grüter ([@lagru](https://github.com/lagru))
- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

4 reviewers added to this release (alphabetically):

- Brigitta Sipőcz ([@bsipocz](https://github.com/bsipocz))
- Lars Grüter ([@lagru](https://github.com/lagru))
- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

Pre-release 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](#49)).
  The new subcommand also includes two new options `--group-errors` ([#30](#30)) and `--allow-errors` to help with adopting docstub gradually ([#32](#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](#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](#18)).
  This includes support for the special case of dataclasses ([#26](#26)).
  You can now document generator functions with the "Yields" and "Receives" docstring sections ([#29](#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](#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](#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](#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](#28)).
- You can now indicate a plural with `(s)` in expressions like `list of int(s)`  ([#37](#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](#2)).
- Point to precise line in parsed source for parsing problems ([#10](#10)).
- Support attributes and type aliases ([#18](#18)).
- Add direct support for dataclasses ([#26](#26)).
- Support Yields section and Generator functions ([#29](#29)).
- Add `--group-errors` option ([#30](#30)).
- Add `--allow-errors` command line option ([#32](#32)).
- Support combined NumPyDoc params ([#41](#41)).

Bug Fixes

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

Performance

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

Documentation

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

Devops

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

Maintenance

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

Contributors

3 authors added to this release (alphabetically):

- Lars Grüter ([@lagru](https://github.com/lagru))
- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

4 reviewers added to this release (alphabetically):

- Brigitta Sipőcz ([@bsipocz](https://github.com/bsipocz))
- Lars Grüter ([@lagru](https://github.com/lagru))
- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

Version 0.3.0.post0

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

Note: This is a post release and almost identical to the ones tagged 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, this post release 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](#49)).
  The new subcommand also includes two new options `--group-errors` ([#30](#30)) and `--allow-errors` to help with adopting docstub gradually ([#32](#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](#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](#18)).
  This includes support for the special case of dataclasses ([#26](#26)).
  You can now document generator functions with the "Yields" and "Receives" docstring sections ([#29](#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](#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](#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](#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](#28)).
- You can now indicate a plural with `(s)` in expressions like `list of int(s)`  ([#37](#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](#2)).
- Point to precise line in parsed source for parsing problems ([#10](#10)).
- Support attributes and type aliases ([#18](#18)).
- Add direct support for dataclasses ([#26](#26)).
- Support Yields section and Generator functions ([#29](#29)).
- Add `--group-errors` option ([#30](#30)).
- Add `--allow-errors` command line option ([#32](#32)).
- Support combined NumPyDoc params ([#41](#41)).

Bug Fixes

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

Performance

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

Documentation

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

Devops

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

Maintenance

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

Contributors

3 authors added to this release (alphabetically):

- Lars Grüter ([@lagru](https://github.com/lagru))
- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

4 reviewers added to this release (alphabetically):

- Brigitta Sipőcz ([@bsipocz](https://github.com/bsipocz))
- Lars Grüter ([@lagru](https://github.com/lagru))
- Marianne Corvellec ([@mkcor](https://github.com/mkcor))
- Oriol Abril-Pla ([@OriolAbril](https://github.com/OriolAbril))

Release 0.2.1

Adds a first prototype of the tool with the following features:

- Given a source directory `examples/example_pkg`, create a stub files for
  every contained Python file in `examples/example-stubs/`
- No need to import the source package!
- PYI files that already exist in the source package take precedence and are
  copied directly
- Type description in NumPy style docstrings are parsed and transformed into
  Python ready type annotations
  - supports `tuple of float` like syntax
  - supports array syntax like: `(N,) uint8 array-like` or
    `array of dtype float and shape (10, ..., 3)` (shape is discarded for now)
  - supports literals like `{"reflect", "mirror", "constant"}`
  - supports `<some type>, optional, extra information`
  - see included `examples/` for more...
- `Any` is used wherever types are missing, except for the first parameter of
  methods and classmethods
- Specify how used types can be imported via a map in
  `docstub.toml::[tool.docstub.docnames]`. Imports using `from` and `as` are
  supported. This map can also serve to provide synonyms.
- Created stub files are automatically formatted with isort and black, if these
  optional dependencies are available.

Only difference compared to v0.2.0 is a fixed bug and added missing
dependencies.

Release 0.2.0

Adds a first prototype of the tool with the following features:

- Given a source directory `examples/example_pkg`, create a stub files for
  every contained Python file in `examples/example-stubs/`
- No need to import the source package!
- PYI files that already exist in the source package take precedence and are
  copied directly
- Type description in NumPy style docstrings are parsed and transformed into
  Python ready type annotations
  - supports `tuple of float` like syntax
  - supports array syntax like: `(N,) uint8 array-like` or
    `array of dtype float and shape (10, ..., 3)` (shape is discarded for now)
  - supports literals like `{"reflect", "mirror", "constant"}`
  - supports `<some type>, optional, extra information`
  - see included `examples/` for more...
- `Any` is used wherever types are missing, except for the first parameter of
  methods and classmethods
- Specify how used types can be imported via a map in
  `docstub.toml::[tool.docstub.docnames]`. Imports using `from` and `as` are
  supported. This map can also serve to provide synonyms.
- Created stub files are automatically formatted with isort and black, if these
  optional dependencies are available.

Release 0.1.0

This is just an empty package for now.