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
--select=<codes> choose the basic list of checked errors by specifying
which errors to check for (with a list of comma-
separated error codes). for example:
--select=D101,D202
--ignore=<codes> choose the basic list of checked errors by specifying
which errors to ignore (with a list of comma-separated
error codes). for example: --ignore=D101,D202
--convention=<name> choose the basic list of checked errors by specifying
an existing convention. for example:
--convention=pep257
--add-select=<codes> amend the list of errors to check for by specifying
more error codes to check.
--add-ignore=<codes> amend the list of errors to check for by specifying
more error codes to ignore.
--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
Return Code¶
0 | Success - no violations |
1 | Some code violations were found |
2 | Illegal usage - see error message |
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¶
Nothing here yet!
0.6.0 - July 20th, 2015¶
New Features
- Added support for more flexible error selections using
--ignore
,--select
,--convention
,--add-ignore
and--add-select
(#96, #123).
Bug Fixes
- Property setter and deleter methods are now treated as private and do not require docstrings separate from the main property method (#69, #107).
- Fixed an issue where pep257 did not accept docstrings that are both unicode and raw in Python 2.x (#116, #119).
- Fixed an issue where Python 3.x files with Unicode encodings were not read correctly (#118).
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¶
Install
pip install pep257
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 ...
Fix your code :)