docstub 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). 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):

4 reviewers added to this release (alphabetically):