Skip to content

Commit 3300b10

Browse files
gahjellegahjelle
authored
Add interrogate to enforce docstrings (#27)
* Add missing docstrings * Update flit * Add configuration for interrogate * Add interrogate to tox (CI tests) * Add interrogate badge to ReadMe * Add information about interrogate to Contributing docs * Add interrogate to changelog
1 parent 0738bd8 commit 3300b10

8 files changed

Lines changed: 100 additions & 41 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ The format is based on [Keep a Changelog](https://keepachangelog1.com/en/1.0.0/)
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- Testing with [Interrogate](https://interrogate.readthedocs.io/) to enforce docstrings ([#27]).
13+
14+
1015
## [1.2.0] - 2020-03-03
1116

1217
### Added
@@ -44,3 +49,4 @@ Initial version of `codetiming`. Version 1.0.0 corresponds to the code in the tu
4449
[#23]: https://github.com/realpython/codetiming/pull/23
4550
[#24]: https://github.com/realpython/codetiming/issues/24
4651
[#25]: https://github.com/realpython/codetiming/pull/25
52+
[#27]: https://github.com/realpython/codetiming/pull/27

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,4 +65,10 @@ Run tests using [`tox`](https://tox.readthedocs.io/). `tox` helps to enforce the
6565
$ pytest --cov=codetiming --cov-report=term-missing
6666
```
6767
68+
- All modules, functions, classes, and methods must have docstrings. This is enforced by [Interrogation](https://interrogate.readthedocs.io/). You can test compliance as follows:
69+
70+
```
71+
$ interrogate -c pyproject.toml -vv
72+
```
73+
6874
Feel free to ask for help in your PR if you are having challenges with any of these tests.

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
[![Python versions](https://img.shields.io/pypi/pyversions/codetiming.svg)](https://pypi.org/project/codetiming/)
77
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
88
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
9+
[![Interrogate DocStrings](https://github.com/realpython/codetiming/blob/master/interrogate_badge.svg)](https://interrogate.readthedocs.io/)
910
[![CircleCI](https://circleci.com/gh/realpython/codetiming.svg?style=shield)](https://circleci.com/gh/realpython/codetiming)
1011

1112
Install `codetiming` from PyPI:

‎codetiming/_timers.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414

1515

1616
class Timers(UserDict):
17+
"""Custom dictionary that stores information about timers"""
18+
1719
def __init__(self, *args: Any, **kwargs: Any) -> None:
1820
"""Add a private dictionary keeping track of all timings"""
1921
super().__init__(*args, **kwargs)

‎interrogate_badge.svg‎

Lines changed: 20 additions & 0 deletions
Loading

‎pyproject.toml‎

Lines changed: 55 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,61 @@
11
[build-system]
2-
requires = ["flit_core >=2,<3"]
2+
requires = ["flit_core >=2,<4"]
33
build-backend = "flit_core.buildapi"
44

5-
[tool.flit.metadata]
6-
module = "codetiming"
7-
author = "Real Python"
8-
author-email = "info@realpython.com"
9-
home-page = "https://realpython.com/python-timer"
10-
description-file = "README.md"
11-
classifiers = [
12-
"Development Status :: 5 - Production/Stable",
13-
"Intended Audience :: Developers",
14-
"License :: OSI Approved :: MIT License",
15-
"Natural Language :: English",
16-
"Operating System :: MacOS",
17-
"Operating System :: Microsoft",
18-
"Operating System :: POSIX :: Linux",
19-
"Programming Language :: Python :: 3.6",
20-
"Programming Language :: Python :: 3.7",
21-
"Programming Language :: Python :: 3.8",
22-
"Programming Language :: Python :: 3.9",
23-
"Topic :: Education",
24-
"Topic :: Software Development :: Libraries :: Python Modules",
25-
"Topic :: System :: Monitoring",
26-
"Typing :: Typed",
27-
]
28-
keywords = "timer class contextmanager decorator"
29-
30-
# Requirements
31-
requires-python = ">=3.6"
32-
requires = [
33-
"dataclasses; python_version < '3.7'",
34-
]
35-
36-
37-
[tool.flit.metadata.urls]
38-
"Source Code" = "https://github.com/realpython/codetiming"
39-
"Tutorial" = "https://realpython.com/python-timer"
40-
41-
[tool.flit.metadata.requires-extra]
42-
dev = ["black", "bump2version", "flake8", "flit", "isort", "mypy"]
43-
test = ["pytest", "pytest-cov", "tox"]
5+
6+
[tool.flit]
7+
8+
[tool.flit.metadata]
9+
module = "codetiming"
10+
author = "Real Python"
11+
author-email = "info@realpython.com"
12+
home-page = "https://realpython.com/python-timer"
13+
description-file = "README.md"
14+
classifiers = [
15+
"Development Status :: 5 - Production/Stable",
16+
"Intended Audience :: Developers",
17+
"License :: OSI Approved :: MIT License",
18+
"Natural Language :: English",
19+
"Operating System :: MacOS",
20+
"Operating System :: Microsoft",
21+
"Operating System :: POSIX :: Linux",
22+
"Programming Language :: Python :: 3.6",
23+
"Programming Language :: Python :: 3.7",
24+
"Programming Language :: Python :: 3.8",
25+
"Programming Language :: Python :: 3.9",
26+
"Topic :: Education",
27+
"Topic :: Software Development :: Libraries :: Python Modules",
28+
"Topic :: System :: Monitoring",
29+
"Typing :: Typed",
30+
]
31+
keywords = "timer class contextmanager decorator"
32+
33+
# Requirements
34+
requires-python = ">=3.6"
35+
requires = [
36+
"dataclasses; python_version < '3.7'",
37+
]
38+
39+
40+
[tool.flit.metadata.urls]
41+
"Source Code" = "https://github.com/realpython/codetiming"
42+
"Tutorial" = "https://realpython.com/python-timer"
43+
44+
[tool.flit.metadata.requires-extra]
45+
dev = ["black", "bump2version", "flake8", "flit", "interrogate", "isort", "mypy"]
46+
test = ["black", "interrogate", "pytest", "pytest-cov", "tox"]
47+
48+
49+
[tool.interrogate]
50+
ignore-init-method = false
51+
ignore-init-module = false
52+
ignore-magic = false
53+
ignore-semiprivate = false
54+
ignore-private = false
55+
ignore-module = false
56+
fail-under = 100
57+
verbose = 0
58+
4459

4560
[tool.isort]
4661
multi_line_output = 3

‎tests/test_codetiming.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,11 @@ class CustomLogger:
4242
"""Simple class used to test custom logging capabilities in Timer"""
4343

4444
def __init__(self):
45+
"""Store log messages in the .messages attribute"""
4546
self.messages = ""
4647

4748
def __call__(self, message):
49+
"""Add a log message to the .messages attribute"""
4850
self.messages += message
4951

5052

‎tox.ini‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[tox]
22
isolated_build = True
3-
envlist = py,black,mypy
3+
envlist = py, black, interrogate, mypy
44

55

66
[testenv]
@@ -16,6 +16,13 @@ deps = black
1616
commands = python -m black --check codetiming/
1717

1818

19+
[testenv:interrogate]
20+
deps = interrogate
21+
skip_install = true
22+
commands =
23+
interrogate --config=pyproject.toml
24+
25+
1926
[testenv:mypy]
2027
deps = mypy
2128
commands = python -m mypy --strict codetiming/

0 commit comments

Comments
 (0)