docstringify 1.1.1__tar.gz → 2.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. {docstringify-1.1.1 → docstringify-2.0.1}/.github/dependabot.yml +4 -2
  2. {docstringify-1.1.1 → docstringify-2.0.1}/.github/workflows/ci.yml +12 -5
  3. {docstringify-1.1.1 → docstringify-2.0.1}/.github/workflows/greetings.yml +4 -4
  4. {docstringify-1.1.1 → docstringify-2.0.1}/.github/workflows/pypi-publish.yml +9 -9
  5. {docstringify-1.1.1 → docstringify-2.0.1}/.pre-commit-config.yaml +22 -8
  6. docstringify-2.0.1/.pre-commit-hooks.yaml +26 -0
  7. {docstringify-1.1.1 → docstringify-2.0.1}/PKG-INFO +84 -26
  8. {docstringify-1.1.1 → docstringify-2.0.1}/README.md +79 -21
  9. {docstringify-1.1.1 → docstringify-2.0.1}/pyproject.toml +25 -18
  10. docstringify-2.0.1/src/docstringify/cli.py +237 -0
  11. docstringify-2.0.1/src/docstringify/converters/__init__.py +26 -0
  12. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/nodes/base.py +5 -6
  13. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/nodes/function.py +3 -2
  14. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/traversal/__init__.py +1 -4
  15. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/traversal/transformer.py +2 -5
  16. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/traversal/visitor.py +9 -17
  17. docstringify-2.0.1/uv.lock +433 -0
  18. docstringify-1.1.1/.pre-commit-hooks.yaml +0 -8
  19. docstringify-1.1.1/src/docstringify/cli.py +0 -128
  20. docstringify-1.1.1/src/docstringify/converters/__init__.py +0 -13
  21. docstringify-1.1.1/uv.lock +0 -423
  22. {docstringify-1.1.1 → docstringify-2.0.1}/.github/ISSUE_TEMPLATE/bug_report.md +0 -0
  23. {docstringify-1.1.1 → docstringify-2.0.1}/.github/ISSUE_TEMPLATE/feature_request.md +0 -0
  24. {docstringify-1.1.1 → docstringify-2.0.1}/.github/pull_request_template.md +0 -0
  25. {docstringify-1.1.1 → docstringify-2.0.1}/.github/release.yml +0 -0
  26. {docstringify-1.1.1 → docstringify-2.0.1}/.gitignore +0 -0
  27. {docstringify-1.1.1 → docstringify-2.0.1}/.python-version +0 -0
  28. {docstringify-1.1.1 → docstringify-2.0.1}/CODE_OF_CONDUCT.md +0 -0
  29. {docstringify-1.1.1 → docstringify-2.0.1}/CONTRIBUTING.md +0 -0
  30. {docstringify-1.1.1 → docstringify-2.0.1}/LICENSE +0 -0
  31. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/__init__.py +0 -0
  32. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/__main__.py +0 -0
  33. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/components.py +0 -0
  34. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/converters/base.py +0 -0
  35. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/converters/google.py +0 -0
  36. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/converters/numpydoc.py +0 -0
  37. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/converters/stub.py +0 -0
  38. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/exceptions.py +0 -0
  39. {docstringify-1.1.1 → docstringify-2.0.1}/src/docstringify/nodes/__init__.py +0 -0
{docstringify-1.1.1 → docstringify-2.0.1}/.github/dependabot.yml RENAMED
@@ -7,8 +7,10 @@ updates:
7
7
  - package-ecosystem: "github-actions"
8
8
  directory: "/"
9
9
  schedule:
10
- # Check for updates to GitHub Actions every month
11
- interval: "monthly"
10
+ interval: "quarterly"
11
+ ignore: # only update minor or major version changes
12
+ - dependency-name: "*"
13
+ update-types: ["version-update:semver-patch"]
12
14
  groups:
13
15
  actions:
14
16
  patterns:
{docstringify-1.1.1 → docstringify-2.0.1}/.github/workflows/ci.yml RENAMED
@@ -43,13 +43,13 @@ jobs:
43
43
  fail-fast: false
44
44
  matrix:
45
45
  os: [macos-latest, ubuntu-latest, windows-latest]
46
- python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
46
+ python-version: ["3.11", "3.12", "3.13", "3.14"]
47
47
 
48
48
  steps:
49
- - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
49
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
50
50
 
51
51
  - name: Set up Python ${{ matrix.python-version }}
52
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
52
+ uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
53
53
  with:
54
54
  python-version: ${{ matrix.python-version }}
55
55
 
@@ -65,5 +65,12 @@ jobs:
65
65
  - name: Install dev dependencies
66
66
  run: python -m pip install --group dev
67
67
 
68
- - name: Validate pre-commit hook
69
- run: pre-commit try-repo . docstringify
68
+ - name: Check that the docstringify-edit pre-commit hook is available
69
+ run: pre-commit try-repo . docstringify-edit
70
+
71
+ - name: Check that the docstringify-suggest pre-commit hook is available
72
+ run: pre-commit try-repo . docstringify-suggest
73
+
74
+ # this is the only hook that works without an additional arg so we can test it like this
75
+ - name: Validate the docstringify-check pre-commit hook
76
+ run: pre-commit try-repo . docstringify-check --all-files
{docstringify-1.1.1 → docstringify-2.0.1}/.github/workflows/greetings.yml RENAMED
@@ -9,8 +9,8 @@ jobs:
9
9
  issues: write
10
10
  pull-requests: write
11
11
  steps:
12
- - uses: actions/first-interaction@34f15e814fe48ac9312ccf29db4e74fa767cbab7 # v1.3.0
12
+ - uses: actions/first-interaction@1c4688942c71f71d4f5502a26ea67c331730fa4d # v3.1.0
13
13
  with:
14
- repo-token: ${{ secrets.GITHUB_TOKEN }}
15
- issue-message: "It looks like this is your first issue here – welcome! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
16
- pr-message: "Congratulations on making your first pull request to `docstringify`! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
14
+ repo_token: ${{ secrets.GITHUB_TOKEN }}
15
+ issue_message: "It looks like this is your first issue here – welcome! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
16
+ pr_message: "Congratulations on making your first pull request to `docstringify`! Please familiarize yourself with the [contributing guidelines](https://github.com/stefmolin/docstringify/blob/main/CONTRIBUTING.md), if you haven't already."
{docstringify-1.1.1 → docstringify-2.0.1}/.github/workflows/pypi-publish.yml RENAMED
@@ -10,9 +10,9 @@ jobs:
10
10
  runs-on: ubuntu-latest
11
11
 
12
12
  steps:
13
- - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
13
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
14
14
  - name: Set up Python
15
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
15
+ uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
16
16
  with:
17
17
  python-version: "3.x"
18
18
  - name: Install pypa/build
@@ -24,7 +24,7 @@ jobs:
24
24
  - name: Build a binary wheel and a source tarball
25
25
  run: python3 -m build
26
26
  - name: Store the distribution packages
27
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
27
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
28
28
  with:
29
29
  name: python-package-distributions
30
30
  path: dist/
@@ -44,12 +44,12 @@ jobs:
44
44
 
45
45
  steps:
46
46
  - name: Download all the dists
47
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
47
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
48
48
  with:
49
49
  name: python-package-distributions
50
50
  path: dist/
51
51
  - name: Publish distribution 📦 to PyPI
52
- uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
52
+ uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
53
53
 
54
54
  github-release:
55
55
  name: >-
@@ -65,12 +65,12 @@ jobs:
65
65
 
66
66
  steps:
67
67
  - name: Download all the dists
68
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
68
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
69
69
  with:
70
70
  name: python-package-distributions
71
71
  path: dist/
72
72
  - name: Sign the dists with Sigstore
73
- uses: sigstore/gh-action-sigstore-python@f514d46b907ebcd5bedc05145c03b69c1edd8b46 # v3.0.0
73
+ uses: sigstore/gh-action-sigstore-python@5b79a39c381910c090341a2c9b0bf022c8b387e1 # v3.4.0
74
74
  with:
75
75
  inputs: >-
76
76
  ./dist/*.tar.gz
@@ -110,11 +110,11 @@ jobs:
110
110
 
111
111
  steps:
112
112
  - name: Download all the dists
113
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
113
+ uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
114
114
  with:
115
115
  name: python-package-distributions
116
116
  path: dist/
117
117
  - name: Publish distribution 📦 to TestPyPI
118
- uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4
118
+ uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
119
119
  with:
120
120
  repository-url: https://test.pypi.org/legacy/
{docstringify-1.1.1 → docstringify-2.0.1}/.pre-commit-config.yaml RENAMED
@@ -1,37 +1,51 @@
1
1
  ci:
2
- autofix_prs: false
2
+ autofix_prs: true
3
3
  autoupdate_schedule: quarterly
4
4
 
5
5
  repos:
6
6
  - repo: https://github.com/pre-commit/pre-commit-hooks
7
- rev: v5.0.0
7
+ rev: v6.0.0
8
8
  hooks:
9
9
  - id: check-toml
10
10
  - id: check-yaml
11
11
  - id: end-of-file-fixer
12
12
  - id: trailing-whitespace
13
13
 
14
+ - repo: https://github.com/codespell-project/codespell
15
+ rev: v2.4.3
16
+ hooks:
17
+ - id: codespell
18
+ additional_dependencies:
19
+ - tomli
20
+ exclude: (\.(svg|png|pdf)$)|(CODE_OF_CONDUCT.md)
21
+
14
22
  - repo: https://github.com/numpy/numpydoc
15
- rev: v1.9.0
23
+ rev: v1.11.0
16
24
  hooks:
17
25
  - id: numpydoc-validation
18
26
  exclude: (tests|docs)/.*
19
27
 
20
28
  - repo: https://github.com/stefmolin/docstringify
21
- rev: 1.0.0
29
+ rev: 2.0.0
22
30
  hooks:
23
- - id: docstringify
24
- args: [--make-changes-inplace=numpydoc]
31
+ - id: docstringify-edit
32
+ name: docstringify source code with numpydoc style
33
+ args: [--overwrite, --style=numpydoc]
34
+ files: src/.*
35
+ - id: docstringify-edit
36
+ name: docstringify tests with stubs
37
+ args: [--overwrite, --style=stub]
38
+ files: tests/.*
25
39
 
26
40
  - repo: https://github.com/astral-sh/ruff-pre-commit
27
- rev: v0.12.2
41
+ rev: v0.16.10
28
42
  hooks:
29
43
  - id: ruff-check
30
44
  args: [--fix, --exit-non-zero-on-fix, --show-fixes]
31
45
  - id: ruff-format
32
46
 
33
47
  - repo: https://github.com/tox-dev/pyproject-fmt
34
- rev: v2.6.0
48
+ rev: v2.30.1
35
49
  hooks:
36
50
  - id: pyproject-fmt
37
51
  args: [--keep-full-version, --no-print-diff]
docstringify-2.0.1/.pre-commit-hooks.yaml ADDED
@@ -0,0 +1,26 @@
1
+ - id: docstringify-edit
2
+ name: generate missing docstrings with docstringify
3
+ description: >-
4
+ Generate missing docstrings from signatures and type annotations,
5
+ injecting them into the source code.
6
+ entry: docstringify edit
7
+ language: python
8
+ types: [python]
9
+
10
+ - id: docstringify-suggest
11
+ name: suggest docstrings with docstringify
12
+ description: >-
13
+ Generate suggestions for missing docstrings from signatures and
14
+ type annotations, printing them for inspection.
15
+ entry: docstringify suggest
16
+ language: python
17
+ types: [python]
18
+
19
+ - id: docstringify-check
20
+ name: check for missing docstrings with docstringify
21
+ description: >-
22
+ Flag missing docstrings, failing if more than the threshold are missing.
23
+ entry: docstringify check
24
+ language: python
25
+ require_serial: true
26
+ types: [python]
{docstringify-1.1.1 → docstringify-2.0.1}/PKG-INFO RENAMED
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: docstringify
3
- Version: 1.1.1
3
+ Version: 2.0.1
4
4
  Summary: Flag missing docstrings and, optionally, generate them from signatures and type annotations.
5
5
  Project-URL: Documentation, https://github.com/stefmolin/docstringify
6
6
  Project-URL: Homepage, https://github.com/stefmolin/docstringify
@@ -12,17 +12,59 @@ Keywords: ast,docstring generation,google-style docstring,numpydoc-style docstri
12
12
  Classifier: Development Status :: 4 - Beta
13
13
  Classifier: Programming Language :: Python
14
14
  Classifier: Programming Language :: Python :: 3 :: Only
15
- Classifier: Programming Language :: Python :: 3.9
16
- Classifier: Programming Language :: Python :: 3.10
17
15
  Classifier: Programming Language :: Python :: 3.11
18
16
  Classifier: Programming Language :: Python :: 3.12
19
17
  Classifier: Programming Language :: Python :: 3.13
20
- Requires-Python: >=3.9
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Programming Language :: Python :: 3.15
20
+ Requires-Python: >=3.11
21
21
  Description-Content-Type: text/markdown
22
22
 
23
23
  # Docstringify
24
24
  Flag missing docstrings and, optionally, generate them from signatures and type annotations.
25
25
 
26
+ <table>
27
+ <tr>
28
+ <td>
29
+ <img alt="Last Release" src="https://img.shields.io/badge/last%20release-inactive?style=for-the-badge">
30
+ </td>
31
+ <td>
32
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
33
+ <img alt="PyPI release" src="https://img.shields.io/pypi/v/docstringify.svg">
34
+ </a>
35
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
36
+ <img alt="Supported Python Versions" src="https://img.shields.io/pypi/pyversions/docstringify">
37
+ </a>
38
+ <a href="https://github.com/stefmolin/docstringify/blob/main/LICENSE" target="_blank" rel="noopener noreferrer">
39
+ <img alt="License" src="https://img.shields.io/pypi/l/docstringify.svg?color=blueviolet">
40
+ </a>
41
+ </td>
42
+ </tr>
43
+ <tr>
44
+ <td>
45
+ <img alt="Build status" src="https://img.shields.io/badge/build%20status-inactive?style=for-the-badge">
46
+ </td>
47
+ <td>
48
+ <!-- <a href="https://codecov.io/gh/stefmolin/docstringify" target="_blank" rel="noopener noreferrer">
49
+ <img alt="codecov" src="https://codecov.io/gh/stefmolin/docstringify/branch/main/graph/badge.svg?token=3SEEG9SZQO">
50
+ </a> -->
51
+ <a href="https://github.com/stefmolin/docstringify/actions/workflows/ci.yml" target="_blank" rel="noopener noreferrer">
52
+ <img alt="CI" src="https://github.com/stefmolin/docstringify/actions/workflows/ci.yml/badge.svg">
53
+ </a>
54
+ </td>
55
+ </tr>
56
+ <tr>
57
+ <td>
58
+ <img alt="Downloads" src="https://img.shields.io/badge/%23downloads-inactive?style=for-the-badge">
59
+ </td>
60
+ <td>
61
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
62
+ <img alt="PyPI downloads" src="https://img.shields.io/pepy/dt/docstringify?label=pypi&color=blueviolet">
63
+ </a>
64
+ </td>
65
+ </tr>
66
+ </table>
67
+
26
68
  ## About
27
69
 
28
70
  Given a file, `test.py`, with the following contents:
@@ -34,12 +76,14 @@ def say_hello(name: str = 'World') -> None:
34
76
 
35
77
  You can use Docstringify in three modes:
36
78
 
37
- 1. Flag missing docstrings:
79
+ 1. `check` &ndash; Flag missing docstrings:
80
+
38
81
  ```
39
82
  test is missing a docstring
40
83
  test.say_hello is missing a docstring
41
84
  ```
42
- 2. Suggest docstring templates based on type annotations:
85
+ 2. `suggest` &ndash; Suggest docstring templates based on type annotations:
86
+
43
87
  ```
44
88
  test is missing a docstring
45
89
  Hint:
@@ -56,10 +100,12 @@ You can use Docstringify in three modes:
56
100
  __description__
57
101
  """
58
102
  ```
59
- 3. Add docstring templates to source code files:
103
+ 3. `edit` &ndash; Add docstring templates to source code files:
104
+
60
105
  ```python
61
106
  """__description__"""
62
107
 
108
+
63
109
  def say_hello(name: str = 'World') -> None:
64
110
  """
65
111
  __description__
@@ -76,55 +122,67 @@ You can use Docstringify in three modes:
76
122
 
77
123
  ### Pre-commit hook
78
124
 
125
+ > [!NOTE]
126
+ > The examples in this section apply to versions 2.0.0 and greater. If you are using an older version, consult the README at that tag.
127
+
128
+ #### Check mode: `docstringify-check`
129
+
79
130
  Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
80
131
 
81
132
  ```yaml
82
133
  - repo: https://github.com/stefmolin/docstringify
83
- rev: 1.1.0
134
+ rev: <version>
84
135
  hooks:
85
- - id: docstringify
136
+ - id: docstringify-check
86
137
  ```
87
138
 
88
139
  By default, all docstrings are required. If you want to be more lenient, you can set the threshold, which is the percentage of docstrings that must be present:
89
140
 
90
141
  ```yaml
91
142
  - repo: https://github.com/stefmolin/docstringify
92
- rev: 1.1.0
143
+ rev: <version>
93
144
  hooks:
94
- - id: docstringify
145
+ - id: docstringify-check
95
146
  args: [--threshold=0.75]
96
147
  ```
97
148
 
98
- 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 stub suggestions (just single lines of `"""__description__"""`):
149
+ #### Suggest mode: `docstringify-suggest`
150
+
151
+ If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), use the `suggest` mode, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
99
152
 
100
153
  ```yaml
101
154
  - repo: https://github.com/stefmolin/docstringify
102
- rev: 1.1.0
155
+ rev: <version>
103
156
  hooks:
104
- - id: docstringify
105
- args: [--suggest-changes=numpydoc]
157
+ - id: docstringify-suggest
158
+ args: [--style=stub]
106
159
  ```
107
160
 
108
- Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
161
+ #### Edit mode: `docstringify-edit`
162
+
163
+ Use the `edit` mode to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
109
164
 
110
165
  ```yaml
111
166
  - repo: https://github.com/stefmolin/docstringify
112
- rev: 1.1.0
167
+ rev: <version>
113
168
  hooks:
114
- - id: docstringify
115
- args: [--make-changes=google]
169
+ - id: docstringify-edit
170
+ args: [--style=google]
116
171
  ```
117
172
 
118
- If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` &ndash; make sure you only operate on files that are in version control with this setting. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
173
+ If you want the changes to be made in place, add `--overwrite`. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
119
174
 
120
175
  ```yaml
121
176
  - repo: https://github.com/stefmolin/docstringify
122
- rev: 1.1.0
177
+ rev: <version>
123
178
  hooks:
124
- - id: docstringify
125
- args: [--make-changes-inplace=numpydoc]
179
+ - id: docstringify-edit
180
+ args: [--overwrite, --style=numpydoc]
126
181
  ```
127
182
 
183
+ > [!WARNING]
184
+ > Make sure you only operate on files that are in version control if you are using `--overwrite`.
185
+
128
186
  Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
129
187
 
130
188
  ### Command line
@@ -135,10 +193,10 @@ First, install the `docstringify` package from PyPI:
135
193
  $ python -m pip install docstringify
136
194
  ```
137
195
 
138
- Then, use the `docstringify` entry point on the file(s) of your choice:
196
+ Then, use the `docstringify` entry point on the file(s) of your choice. For example, to run in `check` mode:
139
197
 
140
198
  ```shell
141
- $ docstringify /path/to/file [/path/to/another/file]
199
+ $ docstringify check /path/to/file [/path/to/another/file]
142
200
  ```
143
201
 
144
202
  Run `docstringify --help` for more information.
{docstringify-1.1.1 → docstringify-2.0.1}/README.md RENAMED
@@ -1,6 +1,48 @@
1
1
  # Docstringify
2
2
  Flag missing docstrings and, optionally, generate them from signatures and type annotations.
3
3
 
4
+ <table>
5
+ <tr>
6
+ <td>
7
+ <img alt="Last Release" src="https://img.shields.io/badge/last%20release-inactive?style=for-the-badge">
8
+ </td>
9
+ <td>
10
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
11
+ <img alt="PyPI release" src="https://img.shields.io/pypi/v/docstringify.svg">
12
+ </a>
13
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
14
+ <img alt="Supported Python Versions" src="https://img.shields.io/pypi/pyversions/docstringify">
15
+ </a>
16
+ <a href="https://github.com/stefmolin/docstringify/blob/main/LICENSE" target="_blank" rel="noopener noreferrer">
17
+ <img alt="License" src="https://img.shields.io/pypi/l/docstringify.svg?color=blueviolet">
18
+ </a>
19
+ </td>
20
+ </tr>
21
+ <tr>
22
+ <td>
23
+ <img alt="Build status" src="https://img.shields.io/badge/build%20status-inactive?style=for-the-badge">
24
+ </td>
25
+ <td>
26
+ <!-- <a href="https://codecov.io/gh/stefmolin/docstringify" target="_blank" rel="noopener noreferrer">
27
+ <img alt="codecov" src="https://codecov.io/gh/stefmolin/docstringify/branch/main/graph/badge.svg?token=3SEEG9SZQO">
28
+ </a> -->
29
+ <a href="https://github.com/stefmolin/docstringify/actions/workflows/ci.yml" target="_blank" rel="noopener noreferrer">
30
+ <img alt="CI" src="https://github.com/stefmolin/docstringify/actions/workflows/ci.yml/badge.svg">
31
+ </a>
32
+ </td>
33
+ </tr>
34
+ <tr>
35
+ <td>
36
+ <img alt="Downloads" src="https://img.shields.io/badge/%23downloads-inactive?style=for-the-badge">
37
+ </td>
38
+ <td>
39
+ <a href="https://pypi.org/project/docstringify/" target="_blank" rel="noopener noreferrer">
40
+ <img alt="PyPI downloads" src="https://img.shields.io/pepy/dt/docstringify?label=pypi&color=blueviolet">
41
+ </a>
42
+ </td>
43
+ </tr>
44
+ </table>
45
+
4
46
  ## About
5
47
 
6
48
  Given a file, `test.py`, with the following contents:
@@ -12,12 +54,14 @@ def say_hello(name: str = 'World') -> None:
12
54
 
13
55
  You can use Docstringify in three modes:
14
56
 
15
- 1. Flag missing docstrings:
57
+ 1. `check` &ndash; Flag missing docstrings:
58
+
16
59
  ```
17
60
  test is missing a docstring
18
61
  test.say_hello is missing a docstring
19
62
  ```
20
- 2. Suggest docstring templates based on type annotations:
63
+ 2. `suggest` &ndash; Suggest docstring templates based on type annotations:
64
+
21
65
  ```
22
66
  test is missing a docstring
23
67
  Hint:
@@ -34,10 +78,12 @@ You can use Docstringify in three modes:
34
78
  __description__
35
79
  """
36
80
  ```
37
- 3. Add docstring templates to source code files:
81
+ 3. `edit` &ndash; Add docstring templates to source code files:
82
+
38
83
  ```python
39
84
  """__description__"""
40
85
 
86
+
41
87
  def say_hello(name: str = 'World') -> None:
42
88
  """
43
89
  __description__
@@ -54,55 +100,67 @@ You can use Docstringify in three modes:
54
100
 
55
101
  ### Pre-commit hook
56
102
 
103
+ > [!NOTE]
104
+ > The examples in this section apply to versions 2.0.0 and greater. If you are using an older version, consult the README at that tag.
105
+
106
+ #### Check mode: `docstringify-check`
107
+
57
108
  Add the following to your `.pre-commit-config.yaml` file to block commits with missing docstrings before any formatters like `ruff`:
58
109
 
59
110
  ```yaml
60
111
  - repo: https://github.com/stefmolin/docstringify
61
- rev: 1.1.0
112
+ rev: <version>
62
113
  hooks:
63
- - id: docstringify
114
+ - id: docstringify-check
64
115
  ```
65
116
 
66
117
  By default, all docstrings are required. If you want to be more lenient, you can set the threshold, which is the percentage of docstrings that must be present:
67
118
 
68
119
  ```yaml
69
120
  - repo: https://github.com/stefmolin/docstringify
70
- rev: 1.1.0
121
+ rev: <version>
71
122
  hooks:
72
- - id: docstringify
123
+ - id: docstringify-check
73
124
  args: [--threshold=0.75]
74
125
  ```
75
126
 
76
- 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 stub suggestions (just single lines of `"""__description__"""`):
127
+ #### Suggest mode: `docstringify-suggest`
128
+
129
+ If you would like to see suggested docstring templates (inferred from type annotations for functions and methods), use the `suggest` mode, along with the docstring style you want to use (options are `google`, `numpydoc`, and `stub`). Here, we ask for stub suggestions (just single lines of `"""__description__"""`):
77
130
 
78
131
  ```yaml
79
132
  - repo: https://github.com/stefmolin/docstringify
80
- rev: 1.1.0
133
+ rev: <version>
81
134
  hooks:
82
- - id: docstringify
83
- args: [--suggest-changes=numpydoc]
135
+ - id: docstringify-suggest
136
+ args: [--style=stub]
84
137
  ```
85
138
 
86
- Use `--make-changes` to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
139
+ #### Edit mode: `docstringify-edit`
140
+
141
+ Use the `edit` mode to create a copy of each file with docstring templates. Here, we ask for changes using the [Google docstring style](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html):
87
142
 
88
143
  ```yaml
89
144
  - repo: https://github.com/stefmolin/docstringify
90
- rev: 1.1.0
145
+ rev: <version>
91
146
  hooks:
92
- - id: docstringify
93
- args: [--make-changes=google]
147
+ - id: docstringify-edit
148
+ args: [--style=google]
94
149
  ```
95
150
 
96
- If you want the changes to be made in place, change `--make-changes` to `--make-changes-inplace` &ndash; make sure you only operate on files that are in version control with this setting. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
151
+ If you want the changes to be made in place, add `--overwrite`. Here, we ask for [numpydoc-style docstring](https://numpydoc.readthedocs.io/en/latest/format.html#) suggestions:
97
152
 
98
153
  ```yaml
99
154
  - repo: https://github.com/stefmolin/docstringify
100
- rev: 1.1.0
155
+ rev: <version>
101
156
  hooks:
102
- - id: docstringify
103
- args: [--make-changes-inplace=numpydoc]
157
+ - id: docstringify-edit
158
+ args: [--overwrite, --style=numpydoc]
104
159
  ```
105
160
 
161
+ > [!WARNING]
162
+ > Make sure you only operate on files that are in version control if you are using `--overwrite`.
163
+
106
164
  Be sure to check out the [pre-commit documentation](https://pre-commit.com/#pre-commit-configyaml---hooks) for additional configuration options.
107
165
 
108
166
  ### Command line
@@ -113,10 +171,10 @@ First, install the `docstringify` package from PyPI:
113
171
  $ python -m pip install docstringify
114
172
  ```
115
173
 
116
- Then, use the `docstringify` entry point on the file(s) of your choice:
174
+ Then, use the `docstringify` entry point on the file(s) of your choice. For example, to run in `check` mode:
117
175
 
118
176
  ```shell
119
- $ docstringify /path/to/file [/path/to/another/file]
177
+ $ docstringify check /path/to/file [/path/to/another/file]
120
178
  ```
121
179
 
122
180
  Run `docstringify --help` for more information.