docstringify 0.5.1__tar.gz → 0.7.0__tar.gz

docstringify-0.7.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+<!-- Which issue does this address? -->
+Fixes #
+
+**Describe your changes**
+
+<!-- TODO -->
+
+**Checklist**
+
+<!-- Place an X between the [ ] for completed tasks -->
+
+- [ ] Test cases have been modified/added to cover any code changes.
+- [ ] Docstrings have been modified/created for any code changes.
+- [ ] All linting and formatting checks pass (see the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md) for more information).

{docstringify-0.5.1 → docstringify-0.7.0}/.github/workflows/ci.yml

@@ -41,13 +41,13 @@ jobs:
         fail-fast: false
         matrix:
             os: [macos-latest, ubuntu-latest, windows-latest]
-            python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+            python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55  # v5.5.0
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
         with:
           python-version: ${{ matrix.python-version }}
 

{docstringify-0.5.1 → docstringify-0.7.0}/.github/workflows/pypi-publish.yml

@@ -12,7 +12,7 @@ jobs:
     steps:
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
     - name: Set up Python
-      uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55  # v5.5.0
+      uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
       with:
         python-version: "3.x"
     - name: Install pypa/build
@@ -44,7 +44,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e  # v4.2.1
+      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
       with:
         name: python-package-distributions
         path: dist/
@@ -65,7 +65,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e  # v4.2.1
+      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
       with:
         name: python-package-distributions
         path: dist/
@@ -110,7 +110,7 @@ jobs:
 
     steps:
     - name: Download all the dists
-      uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e  # v4.2.1
+      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
       with:
         name: python-package-distributions
         path: dist/

{docstringify-0.5.1 → docstringify-0.7.0}/.pre-commit-config.yaml

@@ -11,8 +11,14 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
 
+  - repo: https://github.com/stefmolin/docstringify
+    rev: 0.6.0
+    hooks:
+      - id: docstringify
+        args: [--make-changes-inplace=numpydoc]
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.2
+    rev: v0.11.9
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix, --show-fixes]
@@ -23,3 +29,9 @@ repos:
     hooks:
       - id: pyproject-fmt
         args: [--keep-full-version, --no-print-diff]
+
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.8.0
+    hooks:
+      - id: numpydoc-validation
+        exclude: (tests|docs)/.*

docstringify-0.7.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+docstringify-coc@stefaniemolin.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

docstringify-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing Guidelines
+
+Contributions are welcome. Please adhere to the following process.
+
+## 1. Open an issue
+Open up an issue describing in detail the bug or feature request you are proposing. Be sure to fill out all the information requested in the template. Please wait for confirmation from a maintainer that this unit of work is in line with the project's roadmap *before* submitting a pull request.
+
+## 2. Work on your changes
+Once you have been given the go ahead, you can start working on the code. Start by forking the project, cloning locally, and then creating a branch to work on. You will need to then install main dependencies as well as the `dev` dependencies, which can be done by running the following command:
+
+```shell
+$ pip install -e '.[dev]'
+```
+
+Set up the pre-commit hooks to make sure you can pass the CI checks:
+
+```shell
+$ pre-commit install
+```
+
+All commits will be squashed, so just make sure that the final commit passes all linting, documentation, and testing checks. These will run in GitHub Actions when you open a pull request, but you should also run them locally:
+
+```shell
+$ pre-commit run --all-files  # linting and documentation checks
+$ pytest                      # run the test suite
+```
+
+Some things to remember:
+
+- All code must be documented using docstrings in the [numpydoc style](https://numpydoc.readthedocs.io/en/latest/format.html) – the pre-commit hooks will check for this.
+- Any changes to the API must be accompanied by either an additional test case or a new test. Run `pytest` to make sure your changes are covered.
+
+## 3. Open a pull request
+
+Once you have finished with the task you are working on and all the checks and tests pass, you can create a pull request. Please consult [GitHub's guide on how to do this](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork), if you need some guidance.
+
+In your description, please do the following:
+1. Link to the corresponding issue for this unit of work.
+2. Describe what you changed and why.
+3. Include, if applicable, any testing instructions.
+
+When you create your pull request, first-time contributors will need to wait for a maintainer to approve running the GitHub Actions workflows. Please be patient until this happens.
+
+Once it does, the same checks described above (testing, documentation, linting) that you ran on your machine will run on Linux, macOS, and Windows with multiple versions of Python. Please note that it is possible that differences in operating systems and/or Python versions results in a failure, despite it working on your machine.
+
+If anything fails, please attempt to fix it as we're unlikely to review your code until everything passes. If stuck, please feel free to leave a note in the pull request enumerating what you have already tried and someone may be able to offer assistance.
+
+## 4. Code review
+
+After all checks in your pull request pass, a maintainer will review your code. In many cases, there will be some feedback to address, and this may require a few iterations to get to the best implementation. Remember to be patient and polite during this process.
+
+## 5. Congratulations!
+
+When the pull request is approved, it will be merged into the `main` branch. Users of this project won't have your changes until the next release is made.

{docstringify-0.5.1 → docstringify-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstringify
-Version: 0.5.1
+Version: 0.7.0
 Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
 Author-email: Stefanie Molin <docstringify@stefaniemolin.com>
 License: MIT License
@@ -30,16 +30,14 @@ Project-URL: Homepage, https://github.com/stefmolin/docstringify
 Project-URL: Source, https://github.com/stefmolin/docstringify
 Keywords: ast,docstring generation,google-style docstring,numpydoc-style docstring,pre-commit
 Classifier: Development Status :: 3 - Alpha
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: dev
@@ -109,7 +107,7 @@ Add the following to your `.pre-commit-config.yaml` file to block commits with m
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.5.1
+  rev: 0.7.0
   hooks:
     - id: docstringify
 ```
@@ -118,17 +116,17 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.5.1
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
 ```
 
-If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google` and `numpydoc`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.5.1
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -138,7 +136,7 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.5.1
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]

{docstringify-0.5.1 → docstringify-0.7.0}/README.md

@@ -58,7 +58,7 @@ Add the following to your `.pre-commit-config.yaml` file to block commits with m
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.5.1
+  rev: 0.7.0
   hooks:
     - id: docstringify
 ```
@@ -67,17 +67,17 @@ By default, all docstrings are required. If you want to be more lenient, you can
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.5.1
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--threshold=0.75]
 ```
 
-If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google` and `numpydoc`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
+If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), provide the `--suggest-changes` argument, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.5.1
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--suggest-changes=numpydoc]
@@ -87,7 +87,7 @@ Use `--make-changes` to create a copy of each file with docstring templates. Her
 
 ```yaml
 - repo: https://github.com/stefmolin/docstringify
-  rev: 0.5.1
+  rev: 0.7.0
   hooks:
     - id: docstringify
       args: [--make-changes=google]

{docstringify-0.5.1 → docstringify-0.7.0}/pyproject.toml

@@ -21,13 +21,11 @@ license = { file = "LICENSE" }
 authors = [
   { name = "Stefanie Molin", email = "docstringify@stefaniemolin.com" },
 ]
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 classifiers = [
   "Development Status :: 3 - Alpha",
-  "License :: OSI Approved :: MIT License",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
@@ -94,3 +92,20 @@ lint.extend-per-file-ignores."tests/*" = [ "ANN" ] # don't require annotations f
 lint.isort.known-first-party = [
   "docstringify",
 ]
+
+[tool.numpydoc_validation]
+checks = [
+  "all",  # report on all checks
+  "ES01", # but don't require an extended summary
+  "EX01", # or examples
+  "SA01", # or a see also section
+  "SS06", # and don't require the summary to fit on one line
+]
+exclude = [ # don't report on checks for these
+  '\.__init__$',
+  '\.__repr__$',
+  '\.__str__$',
+]
+override_SS05 = [ # override SS05 to allow docstrings starting with these words
+  '^Process ',
+]

{docstringify-0.5.1 → docstringify-0.7.0}/src/docstringify/__init__.py

@@ -3,4 +3,4 @@ Flag missing docstrings and, optionally, generate them from signatures and
 type annotations.
 """
 
-__version__ = '0.5.1'
+__version__ = '0.7.0'

{docstringify-0.5.1 → docstringify-0.7.0}/src/docstringify/cli.py

@@ -1,29 +1,60 @@
+"""CLI for Docstringify."""
+
 from __future__ import annotations
 
 import argparse
 import sys
 from functools import partial
-from typing import Sequence
+from typing import TYPE_CHECKING
 
+from . import __doc__ as pkg_description
 from . import __version__
-from .converters import GoogleDocstringConverter, NumpydocDocstringConverter
+from .converters import (
+    GoogleDocstringConverter,
+    NumpydocDocstringConverter,
+    StubDocstringConverter,
+)
 from .traversal import DocstringTransformer, DocstringVisitor
 
-PROG = __package__
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 
-STYLES = {
+PROG = __package__
+STYLES: dict[
+    str,
+    type[GoogleDocstringConverter]
+    | type[NumpydocDocstringConverter]
+    | type[StubDocstringConverter],
+] = {
     'google': GoogleDocstringConverter,
     'numpydoc': NumpydocDocstringConverter,
+    'stub': StubDocstringConverter,
 }
 CLI_DEFAULTS = {'threshold': 1.0}
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog=PROG)
+    """
+    Flag missing docstrings and, optionally, generate them from signatures and
+    type annotations.
+
+    Parameters
+    ----------
+    argv : Sequence[str] | None, default=None
+        The arguments passed on the command line.
+
+    Returns
+    -------
+    int
+        Exit code for the process, where non-zero values indicate errors, and ``1``
+        indicates that more than the allowed percentage of docstrings were missing.
+    """
+
+    parser = argparse.ArgumentParser(prog=PROG, description=pkg_description)
+    parser.add_argument('filenames', nargs='*', help='Filenames to process')
     parser.add_argument(
-        'filenames',
-        nargs='*',
-        help='Filenames to process',
+        '-v', '--verbose', action='store_true', help='Run in verbose mode'
     )
     parser.add_argument(
         '--version', action='version', version=f'%(prog)s {__version__}'
@@ -57,19 +88,19 @@ def main(argv: Sequence[str] | None = None) -> int:
     )
     args = parser.parse_args(argv)
 
-    if style := args.make_changes or args.make_changes_inplace or args.suggest_changes:
-        converter = STYLES[style]
-    else:
-        converter = None
-
     get_docstring_processor = (
         partial(
             DocstringTransformer,
-            converter=converter,
-            **{'overwrite': bool(args.make_changes_inplace)},
+            converter=STYLES[style],
+            overwrite=bool(args.make_changes_inplace),
+            verbose=args.verbose,
+        )
+        if (style := args.make_changes or args.make_changes_inplace)
+        else partial(
+            DocstringVisitor,
+            converter=STYLES.get(args.suggest_changes),
+            verbose=args.verbose,
         )
-        if args.make_changes or args.make_changes_inplace
-        else partial(DocstringVisitor, converter=converter)
     )
 
     docstrings_processed = missing_docstrings = 0
@@ -79,9 +110,11 @@ def main(argv: Sequence[str] | None = None) -> int:
         missing_docstrings += len(processor.missing_docstrings)
         docstrings_processed += processor.docstrings_inspected
 
-    if docstrings_processed and (
-        missing_percentage := (missing_docstrings / docstrings_processed)
-    ) > (1 - args.threshold):
+    if (
+        docstrings_processed
+        and (missing_percentage := (missing_docstrings / docstrings_processed))
+        > 1 - args.threshold
+    ):
         print(f'Missing {missing_percentage:.0%} of docstrings', file=sys.stderr)
         print(
             f'Your settings require {args.threshold:.0%} of docstrings to be present',

{docstringify-0.5.1 → docstringify-0.7.0}/src/docstringify/converters/__init__.py

@@ -3,9 +3,11 @@
 from .base import DocstringConverter
 from .google import GoogleDocstringConverter
 from .numpydoc import NumpydocDocstringConverter
+from .stub import StubDocstringConverter
 
 __all__ = [
     'DocstringConverter',
     'GoogleDocstringConverter',
     'NumpydocDocstringConverter',
+    'StubDocstringConverter',
 ]