interrogate.py

Every public method of your python package should have a docstring. To check if your package actually does this, you can use interrogate.

You can install it via;

pip install interrogate

Once installed you can use it from the command line to point to a folder/file that it needs to check. In the video we're checking the clumper folder so the command is:

interrogate clumper

The base command will only show if the check passes, but you can also get a table that highlights the performance per file.

interrogate -v clumper

If you're interested in the view per method, you can increase the verbosity.

interrogate -vv clumper

There's lots of settings that you may want to configure. The ones that we've used in our video are --ignore-semiprivate, --ignore-private, --ignore-magic and --fail-under=80.

interrogate -vv \
  --ignore-semiprivate \
  --ignore-private \
  --ignore-magic \
  --fail-under=80 \
   clumper

Configure

There's a lot to configre, but the setting that we've come to like most is the one where we're less strict. It's completely up to your if you want to use different settings though. Here's the setting that we've ended up using in the long run.

interrogate -vv \
  --ignore-nested-functions \
  --ignore-nested-classes \
  --ignore-semiprivate \
  --ignore-private \
  --ignore-magic \
  --ignore-module \
  --ignore-init-method \
  --fail-under 100 \
  clumper

Tests!

It's great to check for docstrings in your source code, but let's not forget about your tests! If a test ever fails you'd like to understand what the test is supposed to check and it'd be a shame if the only explanation is the name of the test.

Pre Commit

You can also add interrogate to your pre-commit hooks. That way, on every commit we check if any new method has a docstring attached.

repos:
-   repo: https://github.com/econchick/interrogate
    rev: 1.4.0
    hooks:
      - id: interrogate
        args: [--quiet, --fail-under=70, clumper]
-   repo: https://github.com/econchick/interrogate
    rev: 1.4.0
    hooks:
      - id: interrogate
        args: [--quiet, --fail-under=50, tests]

In case you're interested, yes we've started working on a PR for clumper.