Skip to content

Commit c8c3eef

Browse files
jdkanderssonjdkandersson
authored
Alpha (#1)
* add tests for getting sections * add tests for args * add tests for attrs * add tests for raises * add tests for yields and returns * add tests for parse * add implementation for getting docstring information * add check for missing docstring * add check for arguments on function not defined in docstring * add check for function with arguments without the args section * add check for no function args but docstring has args section * add check for arguments in docstring but not function * add capturing all args section names * add check for multiple args sections * include checks for *args and **kwargs * skip test functions * add integration tests * add support for positional only arguments * add support for kyword only args * add support for async function * add support for skipping fixture * add getting started * add docs for checks that returns section is present * add check for return value * add support for checking for empty args section * add check for returns section for function without return value * add check for multiple returns sections * add documentation for check that yield functions have the yield docstring section * add checks for yields * add documentation for raises section * add checks for raises section * add check for raise without any exceptions defined * add capturing all attrs section * add augmented and typed assignment * add tests for multiple functions/ classes
1 parent f41a2b9 commit c8c3eef

28 files changed

+7984
-1
lines changed

‎.devcontainer/devcontainer.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"name": "Python 3",
3+
"image": "mcr.microsoft.com/devcontainers/python:0-3.11",
4+
"features": {
5+
"ghcr.io/devcontainers/features/python:1": {},
6+
"ghcr.io/devcontainers-contrib/features/black:1": {},
7+
"ghcr.io/devcontainers-contrib/features/tox:1": {},
8+
"ghcr.io/devcontainers-contrib/features/isort:1": {},
9+
"ghcr.io/devcontainers-contrib/features/poetry:1": {}
10+
}
11+
}

‎.flake8

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[flake8]
2+
max-line-length = 99
3+
max-doc-length = 99
4+
extend-ignore = E203,W503
5+
per-file-ignores =
6+
tests/*:D205,D400
7+
flake8_docstrings_complete/*:N802
8+
test-docs-pattern = given/when/then

‎.github/dependabot.yml

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# To get started with Dependabot version updates, you'll need to specify which
2+
# package ecosystems to update and where the package manifests are located.
3+
# Please see the documentation for all configuration options:
4+
# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
5+
6+
version: 2
7+
updates:
8+
- package-ecosystem: "github-actions"
9+
directory: "/"
10+
schedule:
11+
interval: "monthly"
12+
- package-ecosystem: "pip"
13+
directory: "/"
14+
schedule:
15+
interval: "monthly"

‎.github/workflows/ci-cd.yaml

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
name: CI-CD
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
tags:
8+
- "v[0-9]+.[0-9]+.[0-9]+"
9+
pull_request:
10+
branches:
11+
- main
12+
13+
jobs:
14+
constants:
15+
name: Constants
16+
runs-on: ubuntu-latest
17+
outputs:
18+
package_name: ${{ steps.output.outputs.package_name }}
19+
package_version: ${{ steps.output.outputs.package_version }}
20+
steps:
21+
- uses: actions/checkout@v3
22+
- uses: actions/setup-python@v4
23+
with:
24+
python-version: '3.11'
25+
- id: output
26+
run: |
27+
echo package_name=$(python -c 'import tomllib;from pathlib import Path;print(tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["tool"]["poetry"]["name"])') >> $GITHUB_OUTPUT
28+
echo package_version=$(python -c 'import tomllib;from pathlib import Path;print(tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["tool"]["poetry"]["version"])') >> $GITHUB_OUTPUT
29+
lint:
30+
name: Lint
31+
runs-on: ubuntu-latest
32+
steps:
33+
- uses: actions/checkout@v3
34+
- uses: actions/setup-python@v4
35+
with:
36+
python-version: '3.11'
37+
- name: Install tox
38+
run: python -m pip install tox
39+
- name: Run linting
40+
run: tox -e lint
41+
test:
42+
name: Test
43+
runs-on: ubuntu-latest
44+
strategy:
45+
matrix:
46+
python-version:
47+
- "3.8"
48+
- "3.9"
49+
- "3.10"
50+
- "3.11"
51+
steps:
52+
- uses: actions/checkout@v3
53+
- name: Set up Python ${{ matrix.python-version }}
54+
uses: actions/setup-python@v4
55+
with:
56+
python-version: ${{ matrix.python-version }}
57+
- name: Install tox
58+
run: python -m pip install tox
59+
- name: Run testing
60+
run: tox -e test
61+
release-test-pypi:
62+
runs-on: ubuntu-latest
63+
if: startsWith(github.ref, 'refs/tags/')
64+
needs:
65+
- test
66+
- lint
67+
steps:
68+
- uses: actions/checkout@v3
69+
- uses: actions/setup-python@v4
70+
with:
71+
python-version: '3.11'
72+
- name: Install poetry
73+
run: python -m pip install poetry
74+
- name: Publish
75+
run: |
76+
poetry config repositories.test-pypi https://test.pypi.org/legacy/
77+
poetry publish --build -u __token__ -p ${{ secrets.test_pypi_password }} -r test-pypi
78+
test-release-test-pypi:
79+
runs-on: ubuntu-latest
80+
if: startsWith(github.ref, 'refs/tags/')
81+
needs:
82+
- release-test-pypi
83+
- constants
84+
strategy:
85+
matrix:
86+
python-version:
87+
- "3.8"
88+
- "3.9"
89+
- "3.10"
90+
- "3.11"
91+
steps:
92+
- name: Set up Python ${{ matrix.python-version }}
93+
uses: actions/setup-python@v4
94+
with:
95+
python-version: ${{ matrix.python-version }}
96+
- name: Run check
97+
run: |
98+
for i in 1 2 3 4 5; do python -m pip install flake8 ${{ needs.constants.outputs.package_name }}==${{ needs.constants.outputs.package_version }} --extra-index-url https://test.pypi.org/simple/ && break || sleep 10; done
99+
echo '"""Docstring."""' > source.py
100+
flake8 source.py
101+
release-pypi:
102+
runs-on: ubuntu-latest
103+
if: startsWith(github.ref, 'refs/tags/')
104+
needs:
105+
- test-release-test-pypi
106+
steps:
107+
- uses: actions/checkout@v3
108+
- uses: actions/setup-python@v4
109+
with:
110+
python-version: '3.11'
111+
- name: Install poetry
112+
run: python -m pip install poetry
113+
- name: Publish
114+
run: poetry publish --build -u __token__ -p ${{ secrets.pypi_password }}
115+
release-github:
116+
runs-on: ubuntu-latest
117+
if: startsWith(github.ref, 'refs/tags/')
118+
needs:
119+
- release-pypi
120+
steps:
121+
- name: Get version from tag
122+
id: tag_name
123+
run: |
124+
echo current_version=${GITHUB_REF#refs/tags/v} >> $GITHUB_OUTPUT
125+
shell: bash
126+
- uses: actions/checkout@v3
127+
- name: Get latest Changelog Entry
128+
id: changelog_reader
129+
uses: mindsers/changelog-reader-action@v2
130+
with:
131+
version: v${{ steps.tag_name.outputs.current_version }}
132+
path: ./CHANGELOG.md
133+
- name: Create Release
134+
id: create_release
135+
uses: actions/create-release@v1
136+
env:
137+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
138+
with:
139+
tag_name: ${{ steps.changelog_reader.outputs.version }}
140+
release_name: Release ${{ steps.changelog_reader.outputs.version }}
141+
body: ${{ steps.changelog_reader.outputs.changes }}
142+
prerelease: ${{ steps.changelog_reader.outputs.status == 'prereleased' }}
143+
draft: ${{ steps.changelog_reader.outputs.status == 'unreleased' }}
144+
test-release-pypi:
145+
runs-on: ubuntu-latest
146+
if: startsWith(github.ref, 'refs/tags/')
147+
needs:
148+
- release-pypi
149+
- constants
150+
strategy:
151+
matrix:
152+
python-version:
153+
- "3.8"
154+
- "3.9"
155+
- "3.10"
156+
- "3.11"
157+
steps:
158+
- name: Set up Python ${{ matrix.python-version }}
159+
uses: actions/setup-python@v4
160+
with:
161+
python-version: ${{ matrix.python-version }}
162+
- name: Run check
163+
run: |
164+
for i in 1 2 3 4 5; do python -m pip install flake8 ${{ needs.constants.outputs.package_name }}==${{ needs.constants.outputs.package_version }} && break || sleep 10; done
165+
echo '"""Docstring."""' > source.py
166+
flake8 source.py

‎.vscode/settings.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"python.analysis.typeCheckingMode": "basic",
3+
"python.linting.pylintEnabled": true,
4+
"python.linting.enabled": true,
5+
"python.formatting.provider": "black"
6+
}

‎CHANGELOG.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Changelog
2+
3+
## [Unreleased]
4+
5+
## [v1.0.0] - 2023-01-02
6+
7+
### Added
8+
9+
#### Function/ Method Arguments
10+
11+
- Lint check that ensures all function/ method arguments are documented
12+
- Lint check that ensures docstring doesn't describe arguments the function/
13+
method doesn't have
14+
- Lint check that ensures there is at most one arguments section in the
15+
docstring
16+
- Lint check that ensures there is no empty arguments section in the docstring
17+
- Support for unused arguments for which descriptions are optional
18+
- Support `*args` and `**kwargs`
19+
- Support positional only arguments
20+
- Support keyword only arguments
21+
- Support ignoring `self` and `cls` arguments
22+
- Support for skipping test functions in test files
23+
- Support for skipping test fixtures in test and fixture files
24+
- Support async functions/ methods
25+
26+
#### Function/ Method Return Value
27+
28+
- Lint check that ensures all functions/ methods that return a value have the
29+
returns section in the docstring
30+
- Lint check that ensures a function that does not return a value does not have
31+
the returns section
32+
- Lint check that ensures there is at most one returns section in the docstring
33+
34+
#### Function/ Method Yield Value
35+
36+
- Lint check that ensures all functions/ methods that yield a value have the
37+
yields section in the docstring
38+
- Lint check that ensures a function that does not yield a value does not have
39+
the yields section
40+
- Lint check that ensures there is at most one yields section in the docstring
41+
42+
#### Function/ Method Exception Handling
43+
44+
- Lint check that ensures all function/ method exceptions are documented
45+
- Lint check that ensures docstring doesn't describe exceptions the function/
46+
method doesn't raise
47+
- Lint check that ensures there is at most one raises section in the docstring
48+
- Lint check that ensures the raises section describes at least one exception
49+
50+
#### Class Attributes
51+
52+
- Lint check that ensures all class attributes are documented
53+
- Lint check that ensures docstring doesn't describe attributes the class
54+
doesn't have
55+
- Lint check that ensures there is at most one attributes section in the
56+
docstring
57+
- Support for private attributes for which descriptions are optional
58+
- Support for class attributes defined on the class and other `classmethod`
59+
methods
60+
- Support for instance attributes defined in `__init__` and other non-static and
61+
non-`classmethod` methods
62+
- Support async functions/ methods
63+
64+
[//]: # "Release links"
65+
[v1.0.0]: https://github.com/jdkandersson/flake8-docstrings-complete/releases/v1.0.0

0 commit comments

Comments
 (0)