Skip to main content

Python docstring style checker

Project description

pep257 is a static analysis tool for checking compliance with Python PEP 257.

The framework for checking docstring style is flexible, and custom checks can be easily added, for example to cover NumPy docstring conventions.


Use pip or easy_install:

pip install pep257

Alternatively, you can use source file directly–it is self-contained.

pep257 is tested with Python 2.6, 2.7, 3.2, 3.3


$ pep257 --help
Usage: pep257 [options] [<file|dir>...]

  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -e, --explain         show explanation of each error
  -s, --source          show source for each error
  --ignore=<codes>      ignore a list comma-separated error codes, for
                        example: --ignore=D101,D202
  --match=<pattern>     check only files that exactly match <pattern> regular
                        expression; default is --match='(?!test_).*\.py' which
                        matches files that don't start with 'test_' but end
                        with '.py'
                        search only dirs that exactly match <pattern> regular
                        expression; default is --match-dir='[^\.].*', which
                        matches all dirs that don't start with a dot

$ pep257 in private nested class `meta`:
        D101: Docstring missing in public method `method`:
        D102: Docstring missing

$ pep257 --explain in private nested class `meta`:
        D101: Docstring missing

        All modules should normally have docstrings.  [...] all functions and
        classes exported by a module should also have docstrings. Public
        methods (including the __init__ constructor) should also have

        Note: Public (exported) definitions are either those with names listed
              in __all__ variable (if present), or those that do not start
              with a single underscore.

$ pep257 --source in public class `class_`:
        D101: Docstring missing

    15: class class_:

Error codes

All pep257 errors have unique codes. All codes start with a capital D and are grouped as follows:

Missing docstrings
D10{0,1,2,3} Public {module,class,method,function} missing.
Whitespace issues
D200 One-line docstrings should fit on one line with quotes.
D20{1,2} No blank lines allowed {before,after} docstring.
D20{3,4} 1 blank required {before,after} class docstring.
D205 Blank line required between one-line summary and description.
D206 Docstring should be indented with spaces, not tabs.
D20{7,8} Docstring {under,over}-indented.
D209 Multi-line docstring should end with 1 blank line.
Quotes issues
D300 Use “”“triple double quotes”“”.
D301 Use r”“” if any backslashes in your docstring.
D302 Use u”“” for Unicode docstrings (Python 2 only).
Docstring content issues
D400 First line should end with a period.
D401 First line should be in imperative mood.
D402 First line should not be the function’s “signature”.

Project details

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
pep257-0.3.0.tar.gz (10.0 kB) Copy SHA256 hash SHA256 Source None Feb 6, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page