pep257’s documentation

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

Contents:

Usage

Installation

Use pip or easy_install:

pip install pep257

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

Command Line Interface

Usage

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

Options:
--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'
--match-dir=<pattern>
                        search only dirs that exactly match <pattern> regular
                        expression; default is --match-dir='[^\.].*', which
                        matches all dirs that don't start with a dot
-d, --debug           print debug information
-v, --verbose         print status information
--count               print total number of errors to stdout

Configuration Files

pep257 looks for a config file in the root of the project (the common prefix of all checked files) and goes up in the directory tree until it finds one of the following files (in this order):

  • setup.cfg
  • tox.ini
  • .pep257

The first found file is read, and configurations in the [pep257] section are used, if such a section exists.

Example
[pep257]
verbose = true
ignore = D100,D203,D405
explain = true

Error Codes

Grouping

Missing Docstrings
D100 Missing docstring in public module
D101 Missing docstring in public class
D102 Missing docstring in public method
D103 Missing docstring in public function
Whitespace Issues
D200 One-line docstring should fit on one line with quotes
D201 No blank lines allowed before function docstring
D202 No blank lines allowed after function docstring
D203 1 blank line required before class docstring
D204 1 blank line required after class docstring
D205 1 blank line required between summary line and description
D206 Docstring should be indented with spaces, not tabs
D207 Docstring is under-indented
D208 Docstring is over-indented
D209 Multi-line docstring closing quotes should be on a separate line
D210 No whitespaces allowed surrounding docstring text
Quotes Issues
D300 Use “”“triple double quotes”“”
D301 Use r”“” if any backslashes in a docstring
D302 Use u”“” for Unicode docstrings
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”

Release Notes

Current Development Version

0.5.0 - March 14th, 2015

New Features

  • Added check D210: No whitespaces allowed surrounding docstring text (#95).
  • Added real documentation rendering using Sphinx (#100, #101).

Bug Fixes

  • Removed log level configuration from module level (#98).
  • D205 used to check that there was a blank line between the one line summary and the description. It now checks that there is exactly one blank line between them (#79).
  • Fixed a bug where --match-dir was not properly respected (#108, #109).

0.4.1 - January 10th, 2015

Bug Fixes

  • Getting ImportError when trying to run pep257 as the installed script (#92, #93).

0.4.0 - January 4th, 2015

Warning

A fatal bug was discovered in this version (#92). Please use a newer version.

New Features

  • Added configuration file support (#58, #87).
  • Added a --count flag that prints the number of violations found (#86, #89).
  • Added support for Python 3.4, PyPy and PyPy3 (#81).

Bug Fixes

  • Fixed broken tests (#74).
  • Fixed parsing various colon and parenthesis combinations in definitions (#82).
  • Allow for greater flexibility in parsing __all__ (#67).
  • Fixed handling of one-liner definitions (#77).

0.3.2 - March 11th, 2014

First documented release!

License

Copyright (c) 2012 GreenSteam, <http://greensteam.dk/>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Quick Start

  1. Install

    pip install pep257

  2. Run

    $ pep257 test.py
test.py:18 in private nested class `meta`:
        D101: Docstring missing
test.py:22 in public method `method`:
        D102: Docstring missing
...

  3. Fix your code :)

Credits

Created by Vladimir Keleshev.

Maintained by Amir Rachum.