Mercurial Repositories > eric / changeset
changeset
Started to change the names of the various code style checkers to make them more appropriate to the broadened scope.
Mon, 30 Sep 2013 19:06:37 +0200
- author
- Detlev Offenbach <detlev@die-offenbachs.de>
- date
- Mon, 30 Sep 2013 19:06:37 +0200
- changeset 2971
- efd4a4343019
- parent 2969
- 0e1af1313b8b
- child 2972
- ae58d4b2562e
Started to change the names of the various code style checkers to make them more appropriate to the broadened scope.
--- a/Documentation/Source/eric5.Plugins.CheckerPlugins.Pep8.Pep257Checker.html Sun Sep 29 19:24:27 2013 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,918 +0,0 @@ -<!DOCTYPE html> -<html><head> -<title>eric5.Plugins.CheckerPlugins.Pep8.Pep257Checker</title> -<meta charset="UTF-8"> -<style> -body { - background: #EDECE6; - margin: 0em 1em 10em 1em; - color: black; -} - -h1 { color: white; background: #85774A; } -h2 { color: white; background: #85774A; } -h3 { color: white; background: #9D936E; } -h4 { color: white; background: #9D936E; } - -a { color: #BA6D36; } - -</style> -</head> -<body><a NAME="top" ID="top"></a> -<h1>eric5.Plugins.CheckerPlugins.Pep8.Pep257Checker</h1> -<p> -Module implementing a checker for PEP-257 documentation string conventions. -</p> -<h3>Global Attributes</h3> -<table> -<tr><td>None</td></tr> -</table> -<h3>Classes</h3> -<table> -<tr> -<td><a href="#Pep257Checker">Pep257Checker</a></td> -<td>Class implementing a checker for PEP-257 documentation string conventions.</td> -</tr><tr> -<td><a href="#Pep257Context">Pep257Context</a></td> -<td>Class implementing the source context.</td> -</tr> -</table> -<h3>Functions</h3> -<table> -<tr><td>None</td></tr> -</table> -<hr /><hr /> -<a NAME="Pep257Checker" ID="Pep257Checker"></a> -<h2>Pep257Checker</h2> -<p> - Class implementing a checker for PEP-257 documentation string conventions. -</p> -<h3>Derived from</h3> -object -<h3>Class Attributes</h3> -<table> -<tr><td>Codes</td></tr><tr><td>Messages</td></tr> -</table> -<h3>Class Methods</h3> -<table> -<tr> -<td><a href="#Pep257Checker.getMessage">getMessage</a></td> -<td>Class method to get a translated and formatted message for a given code.</td> -</tr> -</table> -<h3>Methods</h3> -<table> -<tr> -<td><a href="#Pep257Checker.__init__">Pep257Checker</a></td> -<td>Constructor</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkBackslashes">__checkBackslashes</a></td> -<td>Private method to check, that all docstrings containing backslashes are surrounded by raw triple double quotes.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkBlankAfterLastParagraph">__checkBlankAfterLastParagraph</a></td> -<td>Private method to check, that the last paragraph of docstrings is followed by a blank line.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkBlankAfterSummary">__checkBlankAfterSummary</a></td> -<td>Private method to check, that docstring summaries are followed by a blank line.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkBlankBeforeAndAfterClass">__checkBlankBeforeAndAfterClass</a></td> -<td>Private method to check, that class docstrings have one blank line around them.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkClassDocstring">__checkClassDocstring</a></td> -<td>Private method to check, that all public functions and methods have a docstring.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEndsWithPeriod">__checkEndsWithPeriod</a></td> -<td>Private method to check, that docstring summaries end with a period.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEricBlankAfterSummary">__checkEricBlankAfterSummary</a></td> -<td>Private method to check, that docstring summaries are followed by a blank line.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEricEndsWithPeriod">__checkEricEndsWithPeriod</a></td> -<td>Private method to check, that docstring summaries end with a period.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEricException">__checkEricException</a></td> -<td>Private method to check, that docstrings contain an @exception line if they raise an exception and don't otherwise.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEricFunctionArguments">__checkEricFunctionArguments</a></td> -<td>Private method to check, that docstrings contain an @param and/or @keyparam line for each argument.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEricNBlankAfterLastParagraph">__checkEricNBlankAfterLastParagraph</a></td> -<td>Private method to check, that the last paragraph of docstrings is not followed by a blank line.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEricNoBlankBeforeAndAfterClassOrFunction">__checkEricNoBlankBeforeAndAfterClassOrFunction</a></td> -<td>Private method to check, that class and function/method docstrings have no blank line around them.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEricQuotesOnSeparateLines">__checkEricQuotesOnSeparateLines</a></td> -<td>Private method to check, that leading and trailing quotes are on a line by themselves.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkEricReturn">__checkEricReturn</a></td> -<td>Private method to check, that docstrings contain an @return line if they return anything and don't otherwise.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkFunctionDocstring">__checkFunctionDocstring</a></td> -<td>Private method to check, that all public functions and methods have a docstring.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkImperativeMood">__checkImperativeMood</a></td> -<td>Private method to check, that docstring summaries are in imperative mood.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkIndent">__checkIndent</a></td> -<td>Private method to check, that docstrings are properly indented.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkModulesDocstrings">__checkModulesDocstrings</a></td> -<td>Private method to check, if the module has a docstring.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkNoBlankLineBefore">__checkNoBlankLineBefore</a></td> -<td>Private method to check, that function/method docstrings are not preceded by a blank line.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkNoSignature">__checkNoSignature</a></td> -<td>Private method to check, that docstring summaries don't repeat the function's signature.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkOneLiner">__checkOneLiner</a></td> -<td>Private method to check, that one-liner docstrings fit on one line with quotes.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkReturnType">__checkReturnType</a></td> -<td>Private method to check, that docstrings mention the return value type.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkTripleDoubleQuotes">__checkTripleDoubleQuotes</a></td> -<td>Private method to check, that all docstrings are surrounded by triple double quotes.</td> -</tr><tr> -<td><a href="#Pep257Checker.__checkUnicode">__checkUnicode</a></td> -<td>Private method to check, that all docstrings containing unicode characters are surrounded by unicode triple double quotes.</td> -</tr><tr> -<td><a href="#Pep257Checker.__error">__error</a></td> -<td>Private method to record an issue.</td> -</tr><tr> -<td><a href="#Pep257Checker.__getArgNames">__getArgNames</a></td> -<td></td> -</tr><tr> -<td><a href="#Pep257Checker.__getSummaryLine">__getSummaryLine</a></td> -<td>Private method to extract the summary line.</td> -</tr><tr> -<td><a href="#Pep257Checker.__getSummaryLines">__getSummaryLines</a></td> -<td>Private method to extract the summary lines.</td> -</tr><tr> -<td><a href="#Pep257Checker.__ignoreCode">__ignoreCode</a></td> -<td>Private method to check if the error code should be ignored.</td> -</tr><tr> -<td><a href="#Pep257Checker.__parseClasses">__parseClasses</a></td> -<td>Private method to extract top-level classes.</td> -</tr><tr> -<td><a href="#Pep257Checker.__parseContexts">__parseContexts</a></td> -<td>Private method to extract a context from the source.</td> -</tr><tr> -<td><a href="#Pep257Checker.__parseDocstring">__parseDocstring</a></td> -<td>Private method to extract a docstring given `def` or `class` source.</td> -</tr><tr> -<td><a href="#Pep257Checker.__parseFunctions">__parseFunctions</a></td> -<td>Private method to extract top-level functions.</td> -</tr><tr> -<td><a href="#Pep257Checker.__parseMethods">__parseMethods</a></td> -<td>Private method to extract methods of all classes.</td> -</tr><tr> -<td><a href="#Pep257Checker.__parseModuleDocstring">__parseModuleDocstring</a></td> -<td>Private method to extract a docstring given a module source.</td> -</tr><tr> -<td><a href="#Pep257Checker.__parseTopLevel">__parseTopLevel</a></td> -<td>Private method to extract top-level functions or classes.</td> -</tr><tr> -<td><a href="#Pep257Checker.__readline">__readline</a></td> -<td>Private method to get the next line from the source.</td> -</tr><tr> -<td><a href="#Pep257Checker.__resetReadline">__resetReadline</a></td> -<td>Private method to reset the internal readline function.</td> -</tr><tr> -<td><a href="#Pep257Checker.__skipIndentedBlock">__skipIndentedBlock</a></td> -<td>Private method to skip over an indented block of source code.</td> -</tr><tr> -<td><a href="#Pep257Checker.run">run</a></td> -<td>Public method to check the given source for violations of doc string conventions according to PEP-257.</td> -</tr><tr> -<td><a href="#Pep257Checker.unpackArgs">unpackArgs</a></td> -<td>Local helper function to unpack function argument names.</td> -</tr> -</table> -<h3>Static Methods</h3> -<table> -<tr><td>None</td></tr> -</table> -<a NAME="Pep257Checker.getMessage" ID="Pep257Checker.getMessage"></a> -<h4>Pep257Checker.getMessage (class method)</h4> -<b>getMessage</b>(<i>code, *args</i>) -<p> - Class method to get a translated and formatted message for a - given code. -</p><dl> -<dt><i>code</i></dt> -<dd> -message code (string) -</dd><dt><i>args</i></dt> -<dd> -arguments for a formatted message (list) -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -translated and formatted message (string) -</dd> -</dl><a NAME="Pep257Checker.__init__" ID="Pep257Checker.__init__"></a> -<h4>Pep257Checker (Constructor)</h4> -<b>Pep257Checker</b>(<i>source, filename, select, ignore, expected, repeat, maxLineLength=79, docType="pep257"</i>) -<p> - Constructor -</p><dl> -<dt><i>source</i></dt> -<dd> -source code to be checked (list of string) -</dd><dt><i>filename</i></dt> -<dd> -name of the source file (string) -</dd><dt><i>select</i></dt> -<dd> -list of selected codes (list of string) -</dd><dt><i>ignore</i></dt> -<dd> -list of codes to be ignored (list of string) -</dd><dt><i>expected</i></dt> -<dd> -list of expected codes (list of string) -</dd><dt><i>repeat</i></dt> -<dd> -flag indicating to report each occurrence of a code - (boolean) -</dd><dt><i>maxLineLength=</i></dt> -<dd> -allowed line length (integer) -</dd><dt><i>docType=</i></dt> -<dd> -type of the documentation strings - (string, one of 'eric' or 'pep257') -</dd> -</dl><a NAME="Pep257Checker.__checkBackslashes" ID="Pep257Checker.__checkBackslashes"></a> -<h4>Pep257Checker.__checkBackslashes</h4> -<b>__checkBackslashes</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that all docstrings containing - backslashes are surrounded by raw triple double quotes. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkBlankAfterLastParagraph" ID="Pep257Checker.__checkBlankAfterLastParagraph"></a> -<h4>Pep257Checker.__checkBlankAfterLastParagraph</h4> -<b>__checkBlankAfterLastParagraph</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that the last paragraph of docstrings is - followed by a blank line. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkBlankAfterSummary" ID="Pep257Checker.__checkBlankAfterSummary"></a> -<h4>Pep257Checker.__checkBlankAfterSummary</h4> -<b>__checkBlankAfterSummary</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstring summaries are followed - by a blank line. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkBlankBeforeAndAfterClass" ID="Pep257Checker.__checkBlankBeforeAndAfterClass"></a> -<h4>Pep257Checker.__checkBlankBeforeAndAfterClass</h4> -<b>__checkBlankBeforeAndAfterClass</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that class docstrings have one - blank line around them. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkClassDocstring" ID="Pep257Checker.__checkClassDocstring"></a> -<h4>Pep257Checker.__checkClassDocstring</h4> -<b>__checkClassDocstring</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that all public functions and methods - have a docstring. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEndsWithPeriod" ID="Pep257Checker.__checkEndsWithPeriod"></a> -<h4>Pep257Checker.__checkEndsWithPeriod</h4> -<b>__checkEndsWithPeriod</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstring summaries end with a period. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEricBlankAfterSummary" ID="Pep257Checker.__checkEricBlankAfterSummary"></a> -<h4>Pep257Checker.__checkEricBlankAfterSummary</h4> -<b>__checkEricBlankAfterSummary</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstring summaries are followed - by a blank line. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEricEndsWithPeriod" ID="Pep257Checker.__checkEricEndsWithPeriod"></a> -<h4>Pep257Checker.__checkEricEndsWithPeriod</h4> -<b>__checkEricEndsWithPeriod</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstring summaries end with a period. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEricException" ID="Pep257Checker.__checkEricException"></a> -<h4>Pep257Checker.__checkEricException</h4> -<b>__checkEricException</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstrings contain an @exception line - if they raise an exception and don't otherwise. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEricFunctionArguments" ID="Pep257Checker.__checkEricFunctionArguments"></a> -<h4>Pep257Checker.__checkEricFunctionArguments</h4> -<b>__checkEricFunctionArguments</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstrings contain an @param and/or - @keyparam line for each argument. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEricNBlankAfterLastParagraph" ID="Pep257Checker.__checkEricNBlankAfterLastParagraph"></a> -<h4>Pep257Checker.__checkEricNBlankAfterLastParagraph</h4> -<b>__checkEricNBlankAfterLastParagraph</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that the last paragraph of docstrings is - not followed by a blank line. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEricNoBlankBeforeAndAfterClassOrFunction" ID="Pep257Checker.__checkEricNoBlankBeforeAndAfterClassOrFunction"></a> -<h4>Pep257Checker.__checkEricNoBlankBeforeAndAfterClassOrFunction</h4> -<b>__checkEricNoBlankBeforeAndAfterClassOrFunction</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that class and function/method docstrings - have no blank line around them. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEricQuotesOnSeparateLines" ID="Pep257Checker.__checkEricQuotesOnSeparateLines"></a> -<h4>Pep257Checker.__checkEricQuotesOnSeparateLines</h4> -<b>__checkEricQuotesOnSeparateLines</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that leading and trailing quotes are on - a line by themselves. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkEricReturn" ID="Pep257Checker.__checkEricReturn"></a> -<h4>Pep257Checker.__checkEricReturn</h4> -<b>__checkEricReturn</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstrings contain an @return line - if they return anything and don't otherwise. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkFunctionDocstring" ID="Pep257Checker.__checkFunctionDocstring"></a> -<h4>Pep257Checker.__checkFunctionDocstring</h4> -<b>__checkFunctionDocstring</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that all public functions and methods - have a docstring. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkImperativeMood" ID="Pep257Checker.__checkImperativeMood"></a> -<h4>Pep257Checker.__checkImperativeMood</h4> -<b>__checkImperativeMood</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstring summaries are in - imperative mood. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkIndent" ID="Pep257Checker.__checkIndent"></a> -<h4>Pep257Checker.__checkIndent</h4> -<b>__checkIndent</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstrings are properly indented. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkModulesDocstrings" ID="Pep257Checker.__checkModulesDocstrings"></a> -<h4>Pep257Checker.__checkModulesDocstrings</h4> -<b>__checkModulesDocstrings</b>(<i>docstringContext, context</i>) -<p> - Private method to check, if the module has a docstring. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkNoBlankLineBefore" ID="Pep257Checker.__checkNoBlankLineBefore"></a> -<h4>Pep257Checker.__checkNoBlankLineBefore</h4> -<b>__checkNoBlankLineBefore</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that function/method docstrings are not - preceded by a blank line. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkNoSignature" ID="Pep257Checker.__checkNoSignature"></a> -<h4>Pep257Checker.__checkNoSignature</h4> -<b>__checkNoSignature</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstring summaries don't repeat - the function's signature. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkOneLiner" ID="Pep257Checker.__checkOneLiner"></a> -<h4>Pep257Checker.__checkOneLiner</h4> -<b>__checkOneLiner</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that one-liner docstrings fit on - one line with quotes. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkReturnType" ID="Pep257Checker.__checkReturnType"></a> -<h4>Pep257Checker.__checkReturnType</h4> -<b>__checkReturnType</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that docstrings mention the return value type. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkTripleDoubleQuotes" ID="Pep257Checker.__checkTripleDoubleQuotes"></a> -<h4>Pep257Checker.__checkTripleDoubleQuotes</h4> -<b>__checkTripleDoubleQuotes</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that all docstrings are surrounded - by triple double quotes. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__checkUnicode" ID="Pep257Checker.__checkUnicode"></a> -<h4>Pep257Checker.__checkUnicode</h4> -<b>__checkUnicode</b>(<i>docstringContext, context</i>) -<p> - Private method to check, that all docstrings containing unicode - characters are surrounded by unicode triple double quotes. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd><dt><i>context</i></dt> -<dd> -context of the docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__error" ID="Pep257Checker.__error"></a> -<h4>Pep257Checker.__error</h4> -<b>__error</b>(<i>lineNumber, offset, code, *args</i>) -<p> - Private method to record an issue. -</p><dl> -<dt><i>lineNumber</i></dt> -<dd> -line number of the issue (integer) -</dd><dt><i>offset</i></dt> -<dd> -position within line of the issue (integer) -</dd><dt><i>code</i></dt> -<dd> -message code (string) -</dd><dt><i>args</i></dt> -<dd> -arguments for the message (list) -</dd> -</dl><a NAME="Pep257Checker.__getArgNames" ID="Pep257Checker.__getArgNames"></a> -<h4>Pep257Checker.__getArgNames</h4> -<b>__getArgNames</b>(<i>node</i>) -<a NAME="Pep257Checker.__getSummaryLine" ID="Pep257Checker.__getSummaryLine"></a> -<h4>Pep257Checker.__getSummaryLine</h4> -<b>__getSummaryLine</b>(<i>docstringContext</i>) -<p> - Private method to extract the summary line. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -summary line (string) and the line it was found on (integer) -</dd> -</dl><a NAME="Pep257Checker.__getSummaryLines" ID="Pep257Checker.__getSummaryLines"></a> -<h4>Pep257Checker.__getSummaryLines</h4> -<b>__getSummaryLines</b>(<i>docstringContext</i>) -<p> - Private method to extract the summary lines. -</p><dl> -<dt><i>docstringContext</i></dt> -<dd> -docstring context (Pep257Context) -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -summary lines (list of string) and the line it was found on - (integer) -</dd> -</dl><a NAME="Pep257Checker.__ignoreCode" ID="Pep257Checker.__ignoreCode"></a> -<h4>Pep257Checker.__ignoreCode</h4> -<b>__ignoreCode</b>(<i>code</i>) -<p> - Private method to check if the error code should be ignored. -</p><dl> -<dt><i>code</i></dt> -<dd> -message code to check for (string) -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -flag indicating to ignore the given code (boolean) -</dd> -</dl><a NAME="Pep257Checker.__parseClasses" ID="Pep257Checker.__parseClasses"></a> -<h4>Pep257Checker.__parseClasses</h4> -<b>__parseClasses</b>(<i></i>) -<p> - Private method to extract top-level classes. -</p><dl> -<dt>Returns:</dt> -<dd> -extracted class contexts (list of Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__parseContexts" ID="Pep257Checker.__parseContexts"></a> -<h4>Pep257Checker.__parseContexts</h4> -<b>__parseContexts</b>(<i>kind</i>) -<p> - Private method to extract a context from the source. -</p><dl> -<dt><i>kind</i></dt> -<dd> -kind of context to extract (string) -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -requested contexts (list of Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__parseDocstring" ID="Pep257Checker.__parseDocstring"></a> -<h4>Pep257Checker.__parseDocstring</h4> -<b>__parseDocstring</b>(<i>context, what=''</i>) -<p> - Private method to extract a docstring given `def` or `class` source. -</p><dl> -<dt><i>context</i></dt> -<dd> -context data to get the docstring from (Pep257Context) -</dd><dt><i>what</i></dt> -<dd> -string denoting what is being parsed (string) -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -context of extracted docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__parseFunctions" ID="Pep257Checker.__parseFunctions"></a> -<h4>Pep257Checker.__parseFunctions</h4> -<b>__parseFunctions</b>(<i></i>) -<p> - Private method to extract top-level functions. -</p><dl> -<dt>Returns:</dt> -<dd> -extracted function contexts (list of Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__parseMethods" ID="Pep257Checker.__parseMethods"></a> -<h4>Pep257Checker.__parseMethods</h4> -<b>__parseMethods</b>(<i></i>) -<p> - Private method to extract methods of all classes. -</p><dl> -<dt>Returns:</dt> -<dd> -extracted method contexts (list of Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__parseModuleDocstring" ID="Pep257Checker.__parseModuleDocstring"></a> -<h4>Pep257Checker.__parseModuleDocstring</h4> -<b>__parseModuleDocstring</b>(<i>source</i>) -<p> - Private method to extract a docstring given a module source. -</p><dl> -<dt><i>source</i></dt> -<dd> -source to parse (list of string) -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -context of extracted docstring (Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__parseTopLevel" ID="Pep257Checker.__parseTopLevel"></a> -<h4>Pep257Checker.__parseTopLevel</h4> -<b>__parseTopLevel</b>(<i>keyword</i>) -<p> - Private method to extract top-level functions or classes. -</p><dl> -<dt><i>keyword</i></dt> -<dd> -keyword signaling what to extract (string) -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -extracted function or class contexts (list of Pep257Context) -</dd> -</dl><a NAME="Pep257Checker.__readline" ID="Pep257Checker.__readline"></a> -<h4>Pep257Checker.__readline</h4> -<b>__readline</b>(<i></i>) -<p> - Private method to get the next line from the source. -</p><dl> -<dt>Returns:</dt> -<dd> -next line of source (string) -</dd> -</dl><a NAME="Pep257Checker.__resetReadline" ID="Pep257Checker.__resetReadline"></a> -<h4>Pep257Checker.__resetReadline</h4> -<b>__resetReadline</b>(<i></i>) -<p> - Private method to reset the internal readline function. -</p><a NAME="Pep257Checker.__skipIndentedBlock" ID="Pep257Checker.__skipIndentedBlock"></a> -<h4>Pep257Checker.__skipIndentedBlock</h4> -<b>__skipIndentedBlock</b>(<i>tokenGenerator</i>) -<p> - Private method to skip over an indented block of source code. -</p><dl> -<dt><i>tokenGenerator</i></dt> -<dd> -token generator -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -last token of the indented block -</dd> -</dl><a NAME="Pep257Checker.run" ID="Pep257Checker.run"></a> -<h4>Pep257Checker.run</h4> -<b>run</b>(<i></i>) -<p> - Public method to check the given source for violations of doc string - conventions according to PEP-257. -</p><a NAME="Pep257Checker.unpackArgs" ID="Pep257Checker.unpackArgs"></a> -<h4>Pep257Checker.unpackArgs</h4> -<b>unpackArgs</b>(<i></i>) -<p> - Local helper function to unpack function argument names. -</p><dl> -<dt><i>args</i></dt> -<dd> -list of AST node arguments -</dd> -</dl><dl> -<dt>Returns:</dt> -<dd> -list of argument names (list of string) -</dd> -</dl> -<div align="right"><a href="#top">Up</a></div> -<hr /><hr /> -<a NAME="Pep257Context" ID="Pep257Context"></a> -<h2>Pep257Context</h2> -<p> - Class implementing the source context. -</p> -<h3>Derived from</h3> -object -<h3>Class Attributes</h3> -<table> -<tr><td>None</td></tr> -</table> -<h3>Class Methods</h3> -<table> -<tr><td>None</td></tr> -</table> -<h3>Methods</h3> -<table> -<tr> -<td><a href="#Pep257Context.__init__">Pep257Context</a></td> -<td>Constructor</td> -</tr><tr> -<td><a href="#Pep257Context.contextType">contextType</a></td> -<td>Public method to get the context type.</td> -</tr><tr> -<td><a href="#Pep257Context.end">end</a></td> -<td>Public method to get the end line number.</td> -</tr><tr> -<td><a href="#Pep257Context.indent">indent</a></td> -<td>Public method to get the indentation of the first line.</td> -</tr><tr> -<td><a href="#Pep257Context.source">source</a></td> -<td>Public method to get the source.</td> -</tr><tr> -<td><a href="#Pep257Context.ssource">ssource</a></td> -<td>Public method to get the joined source lines.</td> -</tr><tr> -<td><a href="#Pep257Context.start">start</a></td> -<td>Public method to get the start line number.</td> -</tr> -</table> -<h3>Static Methods</h3> -<table> -<tr><td>None</td></tr> -</table> -<a NAME="Pep257Context.__init__" ID="Pep257Context.__init__"></a> -<h4>Pep257Context (Constructor)</h4> -<b>Pep257Context</b>(<i>source, startLine, contextType</i>) -<p> - Constructor -</p><dl> -<dt><i>source</i></dt> -<dd> -source code of the context (list of string or string) -</dd><dt><i>startLine</i></dt> -<dd> -line number the context starts in the source (integer) -</dd><dt><i>contextType</i></dt> -<dd> -type of the context object (string) -</dd> -</dl><a NAME="Pep257Context.contextType" ID="Pep257Context.contextType"></a> -<h4>Pep257Context.contextType</h4> -<b>contextType</b>(<i></i>) -<p> - Public method to get the context type. -</p><dl> -<dt>Returns:</dt> -<dd> -context type (string) -</dd> -</dl><a NAME="Pep257Context.end" ID="Pep257Context.end"></a> -<h4>Pep257Context.end</h4> -<b>end</b>(<i></i>) -<p> - Public method to get the end line number. -</p><dl> -<dt>Returns:</dt> -<dd> -end line number (integer) -</dd> -</dl><a NAME="Pep257Context.indent" ID="Pep257Context.indent"></a> -<h4>Pep257Context.indent</h4> -<b>indent</b>(<i></i>) -<p> - Public method to get the indentation of the first line. -</p><dl> -<dt>Returns:</dt> -<dd> -indentation string (string) -</dd> -</dl><a NAME="Pep257Context.source" ID="Pep257Context.source"></a> -<h4>Pep257Context.source</h4> -<b>source</b>(<i></i>) -<p> - Public method to get the source. -</p><dl> -<dt>Returns:</dt> -<dd> -source (list of string) -</dd> -</dl><a NAME="Pep257Context.ssource" ID="Pep257Context.ssource"></a> -<h4>Pep257Context.ssource</h4> -<b>ssource</b>(<i></i>) -<p> - Public method to get the joined source lines. -</p><dl> -<dt>Returns:</dt> -<dd> -source (string) -</dd> -</dl><a NAME="Pep257Context.start" ID="Pep257Context.start"></a> -<h4>Pep257Context.start</h4> -<b>start</b>(<i></i>) -<p> - Public method to get the start line number. -</p><dl> -<dt>Returns:</dt> -<dd> -start line number (integer) -</dd> -</dl> -<div align="right"><a href="#top">Up</a></div> -<hr /> -</body></html> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Plugins/CheckerPlugins/Pep8/DocStyleChecker.py Mon Sep 30 19:06:37 2013 +0200 @@ -0,0 +1,1307 @@ +# -*- coding: utf-8 -*- + +# Copyright (c) 2013 Detlev Offenbach <detlev@die-offenbachs.de> +# + +""" +Module implementing a checker for PEP-257 documentation string conventions. +""" + +# +# The routines of the checker class are modeled after the ones found in +# pep257.py (version 0.2.4). +# + +try: + # Python 2 + from StringIO import StringIO # __IGNORE_EXCEPTION__ +except ImportError: + # Python 3 + from io import StringIO # __IGNORE_WARNING__ +import tokenize +import ast +import sys + +from PyQt4.QtCore import QT_TRANSLATE_NOOP, QCoreApplication + + +class DocStyleContext(object): + """ + Class implementing the source context. + """ + def __init__(self, source, startLine, contextType): + """ + Constructor + + @param source source code of the context (list of string or string) + @param startLine line number the context starts in the source (integer) + @param contextType type of the context object (string) + """ + if isinstance(source, str): + self.__source = source.splitlines(True) + else: + self.__source = source[:] + self.__start = startLine + self.__indent = "" + self.__type = contextType + + # ensure first line is left justified + if self.__source: + self.__indent = self.__source[0].replace( + self.__source[0].lstrip(), "") + self.__source[0] = self.__source[0].lstrip() + + def source(self): + """ + Public method to get the source. + + @return source (list of string) + """ + return self.__source + + def ssource(self): + """ + Public method to get the joined source lines. + + @return source (string) + """ + return "".join(self.__source) + + def start(self): + """ + Public method to get the start line number. + + @return start line number (integer) + """ + return self.__start + + def end(self): + """ + Public method to get the end line number. + + @return end line number (integer) + """ + return self.__start + len(self.__source) - 1 + + def indent(self): + """ + Public method to get the indentation of the first line. + + @return indentation string (string) + """ + return self.__indent + + def contextType(self): + """ + Public method to get the context type. + + @return context type (string) + """ + return self.__type + + +class DocStyleChecker(object): + """ + Class implementing a checker for PEP-257 documentation string conventions. + """ + Codes = [ + "D101", "D102", "D103", "D104", "D105", + "D111", "D112", "D113", + "D121", "D122", + "D131", "D132", "D133", "D134", + "D141", "D142", "D143", "D144", "D145", + + "D203", "D205", + "D221", "D222", + "D231", "D234", "D235", "D236", "D237", "D238", "D239", + "D242", "D243", "D244", "D245", "D246", "D247", + "D250", "D251", + ] + + Messages = { + "D101": QT_TRANSLATE_NOOP( + "DocStyleChecker", "module is missing a docstring"), + "D102": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "public function/method is missing a docstring"), + "D103": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "private function/method may be missing a docstring"), + "D104": QT_TRANSLATE_NOOP( + "DocStyleChecker", "public class is missing a docstring"), + "D105": QT_TRANSLATE_NOOP( + "DocStyleChecker", "private class may be missing a docstring"), + "D111": QT_TRANSLATE_NOOP( + "DocStyleChecker", 'docstring not surrounded by """'), + "D112": QT_TRANSLATE_NOOP( + "DocStyleChecker", + 'docstring containing \\ not surrounded by r"""'), + "D113": QT_TRANSLATE_NOOP( + "DocStyleChecker", + 'docstring containing unicode character not surrounded by u"""'), + "D121": QT_TRANSLATE_NOOP( + "DocStyleChecker", "one-liner docstring on multiple lines"), + "D122": QT_TRANSLATE_NOOP( + "DocStyleChecker", "docstring has wrong indentation"), + "D131": QT_TRANSLATE_NOOP( + "DocStyleChecker", "docstring summary does not end with a period"), + "D132": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring summary is not in imperative mood" + " (Does instead of Do)"), + "D133": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring summary looks like a function's/method's signature"), + "D134": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring does not mention the return value type"), + "D141": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "function/method docstring is separated by a blank line"), + "D142": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "class docstring is not preceded by a blank line"), + "D143": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "class docstring is not followed by a blank line"), + "D144": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring summary is not followed by a blank line"), + "D145": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "last paragraph of docstring is not followed by a blank line"), + + "D203": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "private function/method is missing a docstring"), + "D205": QT_TRANSLATE_NOOP( + "DocStyleChecker", "private class is missing a docstring"), + "D221": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "leading quotes of docstring not on separate line"), + "D222": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "trailing quotes of docstring not on separate line"), + "D231": QT_TRANSLATE_NOOP( + "DocStyleChecker", "docstring summary does not end with a period"), + "D234": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring does not contain a @return line but function/method" + " returns something"), + "D235": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring contains a @return line but function/method doesn't" + " return anything"), + "D236": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring does not contain enough @param/@keyparam lines"), + "D237": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring contains too many @param/@keyparam lines"), + "D238": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "keyword only arguments must be documented with @keyparam lines"), + "D239": QT_TRANSLATE_NOOP( + "DocStyleChecker", "order of @param/@keyparam lines does" + " not match the function/method signature"), + "D242": QT_TRANSLATE_NOOP( + "DocStyleChecker", "class docstring is preceded by a blank line"), + "D243": QT_TRANSLATE_NOOP( + "DocStyleChecker", "class docstring is followed by a blank line"), + "D244": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "function/method docstring is preceded by a blank line"), + "D245": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "function/method docstring is followed by a blank line"), + "D246": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring summary is not followed by a blank line"), + "D247": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "last paragraph of docstring is followed by a blank line"), + "D250": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring does not contain a @exception line but function/method" + " raises an exception"), + "D251": QT_TRANSLATE_NOOP( + "DocStyleChecker", + "docstring contains a @exception line but function/method doesn't" + " raise an exception"), + } + + def __init__(self, source, filename, select, ignore, expected, repeat, + maxLineLength=79, docType="pep257"): + """ + Constructor + + @param source source code to be checked (list of string) + @param filename name of the source file (string) + @param select list of selected codes (list of string) + @param ignore list of codes to be ignored (list of string) + @param expected list of expected codes (list of string) + @param repeat flag indicating to report each occurrence of a code + (boolean) + @keyparam maxLineLength allowed line length (integer) + @keyparam docType type of the documentation strings + (string, one of 'eric' or 'pep257') + """ + assert docType in ("eric", "pep257") + + self.__select = tuple(select) + self.__ignore = tuple(ignore) + self.__expected = expected[:] + self.__repeat = repeat + self.__maxLineLength = maxLineLength + self.__docType = docType + self.__filename = filename + self.__source = source[:] + + # statistics counters + self.counters = {} + + # collection of detected errors + self.errors = [] + + self.__lineNumber = 0 + + # caches + self.__functionsCache = None + self.__classesCache = None + self.__methodsCache = None + + self.__keywords = [ + 'moduleDocstring', 'functionDocstring', + 'classDocstring', 'methodDocstring', + 'defDocstring', 'docstring' + ] + if self.__docType == "pep257": + checkersWithCodes = { + "moduleDocstring": [ + (self.__checkModulesDocstrings, ("D101",)), + ], + "functionDocstring": [ + ], + "classDocstring": [ + (self.__checkClassDocstring, ("D104", "D105")), + (self.__checkBlankBeforeAndAfterClass, ("D142", "D143")), + ], + "methodDocstring": [ + ], + "defDocstring": [ + (self.__checkFunctionDocstring, ("D102", "D103")), + (self.__checkImperativeMood, ("D132",)), + (self.__checkNoSignature, ("D133",)), + (self.__checkReturnType, ("D134",)), + (self.__checkNoBlankLineBefore, ("D141",)), + ], + "docstring": [ + (self.__checkTripleDoubleQuotes, ("D111",)), + (self.__checkBackslashes, ("D112",)), + (self.__checkUnicode, ("D113",)), + (self.__checkOneLiner, ("D121",)), + (self.__checkIndent, ("D122",)), + (self.__checkEndsWithPeriod, ("D131",)), + (self.__checkBlankAfterSummary, ("D144",)), + (self.__checkBlankAfterLastParagraph, ("D145",)), + ], + } + elif self.__docType == "eric": + checkersWithCodes = { + "moduleDocstring": [ + (self.__checkModulesDocstrings, ("D101",)), + ], + "functionDocstring": [ + ], + "classDocstring": [ + (self.__checkClassDocstring, ("D104", "D205")), + (self.__checkEricNoBlankBeforeAndAfterClassOrFunction, + ("D242", "D243")), + ], + "methodDocstring": [ + ], + "defDocstring": [ + (self.__checkFunctionDocstring, ("D102", "D203")), + (self.__checkImperativeMood, ("D132",)), + (self.__checkNoSignature, ("D133",)), + (self.__checkEricReturn, ("D234", "D235")), + (self.__checkEricFunctionArguments, + ("D236", "D237", "D238", "D239")), + (self.__checkEricNoBlankBeforeAndAfterClassOrFunction, + ("D244", "D245")), + (self.__checkEricException, ("D250", "D251")), + ], + "docstring": [ + (self.__checkTripleDoubleQuotes, ("D111",)), + (self.__checkBackslashes, ("D112",)), + (self.__checkUnicode, ("D113",)), + (self.__checkIndent, ("D122",)), + (self.__checkEricEndsWithPeriod, ("D231",)), + (self.__checkEricBlankAfterSummary, ("D246",)), + (self.__checkEricNBlankAfterLastParagraph, ("D247",)), + (self.__checkEricQuotesOnSeparateLines, ("D222", "D223")) + ], + } + + self.__checkers = {} + for key, checkers in checkersWithCodes.items(): + for checker, codes in checkers: + if any(not (code and self.__ignoreCode(code)) + for code in codes): + if key not in self.__checkers: + self.__checkers[key] = [] + self.__checkers[key].append(checker) + + def __ignoreCode(self, code): + """ + Private method to check if the error code should be ignored. + + @param code message code to check for (string) + @return flag indicating to ignore the given code (boolean) + """ + return (code.startswith(self.__ignore) and + not code.startswith(self.__select)) + + def __error(self, lineNumber, offset, code, *args): + """ + Private method to record an issue. + + @param lineNumber line number of the issue (integer) + @param offset position within line of the issue (integer) + @param code message code (string) + @param args arguments for the message (list) + """ + if self.__ignoreCode(code): + return + + if code in self.counters: + self.counters[code] += 1 + else: + self.counters[code] = 1 + + # Don't care about expected codes + if code in self.__expected: + return + + if code and (self.counters[code] == 1 or self.__repeat): + if code in DocStyleChecker.Codes: + text = self.getMessage(code, *args) + else: + text = code + " " + QCoreApplication.translate( + "DocStyleChecker", "no message for this code defined") + # record the issue with one based line number + self.errors.append((self.__filename, lineNumber + 1, offset, text)) + + @classmethod + def getMessage(cls, code, *args): + """ + Class method to get a translated and formatted message for a + given code. + + @param code message code (string) + @param args arguments for a formatted message (list) + @return translated and formatted message (string) + """ + if code in DocStyleChecker.Messages: + return code + " " + QCoreApplication.translate( + "DocStyleChecker", DocStyleChecker.Messages[code]).format(*args) + else: + return code + " " + QCoreApplication.translate( + "DocStyleChecker", "no message for this code defined") + + def __resetReadline(self): + """ + Private method to reset the internal readline function. + """ + self.__lineNumber = 0 + + def __readline(self): + """ + Private method to get the next line from the source. + + @return next line of source (string) + """ + self.__lineNumber += 1 + if self.__lineNumber > len(self.__source): + return '' + return self.__source[self.__lineNumber - 1] + + def run(self): + """ + Public method to check the given source for violations of doc string + conventions according to PEP-257. + """ + if not self.__source or not self.__filename: + # don't do anything, if essential data is missing + return + + if not self.__checkers: + # don't do anything, if no codes were selected + return + + for keyword in self.__keywords: + if keyword in self.__checkers: + for check in self.__checkers[keyword]: + for context in self.__parseContexts(keyword): + docstring = self.__parseDocstring(context, keyword) + check(docstring, context) + + def __getSummaryLine(self, docstringContext): + """ + Private method to extract the summary line. + + @param docstringContext docstring context (DocStyleContext) + @return summary line (string) and the line it was found on (integer) + """ + lines = docstringContext.source() + + line = (lines[0] + .replace('r"""', "", 1) + .replace('u"""', "", 1) + .replace('"""', "") + .replace("r'''", "", 1) + .replace("u'''", "", 1) + .replace("'''", "") + .strip()) + + if len(lines) == 1 or len(line) > 0: + return line, 0 + return lines[1].strip().replace('"""', "").replace("'''", ""), 1 + + def __getSummaryLines(self, docstringContext): + """ + Private method to extract the summary lines. + + @param docstringContext docstring context (DocStyleContext) + @return summary lines (list of string) and the line it was found on + (integer) + """ + summaries = [] + lines = docstringContext.source() + + line0 = (lines[0] + .replace('r"""', "", 1) + .replace('u"""', "", 1) + .replace('"""', "") + .replace("r'''", "", 1) + .replace("u'''", "", 1) + .replace("'''", "") + .strip()) + if len(lines) > 1: + line1 = lines[1].strip().replace('"""', "").replace("'''", "") + else: + line1 = "" + if len(lines) > 2: + line2 = lines[2].strip().replace('"""', "").replace("'''", "") + else: + line2 = "" + if line0: + lineno = 0 + summaries.append(line0) + if not line0.endswith(".") and line1: + # two line summary + summaries.append(line1) + elif line1: + lineno = 1 + summaries.append(line1) + if not line1.endswith(".") and line2: + # two line summary + summaries.append(line2) + else: + lineno = 2 + summaries.append(line2) + return summaries, lineno + + if sys.version_info[0] < 3: + def __getArgNames(self, node): + """ + Private method to get the argument names of a function node. + + @param node AST node to extract arguments names from + @return tuple of two list of argument names, one for arguments + and one for keyword arguments (tuple of list of string) + """ + def unpackArgs(args): + """ + Local helper function to unpack function argument names. + + @param args list of AST node arguments + @return list of argument names (list of string) + """ + ret = [] + for arg in args: + if isinstance(arg, ast.Tuple): + ret.extend(unpackArgs(arg.elts)) + else: + ret.append(arg.id) + return ret + + arguments = unpackArgs(node.args.args) + if node.args.vararg is not None: + arguments.append(node.args.vararg) + kwarguments = [] + if node.args.kwarg is not None: + kwarguments.append(node.args.kwarg) + return arguments, kwarguments + else: + def __getArgNames(self, node): # __IGNORE_WARNING__ + """ + Private method to get the argument names of a function node. + + @param node AST node to extract arguments names from + @return tuple of two list of argument names, one for arguments + and one for keyword arguments (tuple of list of string) + """ + arguments = [] + arguments.extend([arg.arg for arg in node.args.args]) + if node.args.vararg is not None: + arguments.append(node.args.vararg) + + kwarguments = [] + kwarguments.extend([arg.arg for arg in node.args.kwonlyargs]) + if node.args.kwarg is not None: + kwarguments.append(node.args.kwarg) + return arguments, kwarguments + + ################################################################## + ## Parsing functionality below + ################################################################## + + def __parseModuleDocstring(self, source): + """ + Private method to extract a docstring given a module source. + + @param source source to parse (list of string) + @return context of extracted docstring (DocStyleContext) + """ + for kind, value, (line, char), _, _ in tokenize.generate_tokens( + StringIO("".join(source)).readline): + if kind in [tokenize.COMMENT, tokenize.NEWLINE, tokenize.NL]: + continue + elif kind == tokenize.STRING: # first STRING should be docstring + return DocStyleContext(value, line - 1, "docstring") + else: + return None + + def __parseDocstring(self, context, what=''): + """ + Private method to extract a docstring given `def` or `class` source. + + @param context context data to get the docstring from (DocStyleContext) + @param what string denoting what is being parsed (string) + @return context of extracted docstring (DocStyleContext) + """ + moduleDocstring = self.__parseModuleDocstring(context.source()) + if what.startswith('module') or context.contextType() == "module": + return moduleDocstring + if moduleDocstring: + return moduleDocstring + + tokenGenerator = tokenize.generate_tokens( + StringIO(context.ssource()).readline) + try: + kind = None + while kind != tokenize.INDENT: + kind, _, _, _, _ = next(tokenGenerator) + kind, value, (line, char), _, _ = next(tokenGenerator) + if kind == tokenize.STRING: # STRING after INDENT is a docstring + return DocStyleContext( + value, context.start() + line - 1, "docstring") + except StopIteration: + pass + + return None + + def __parseTopLevel(self, keyword): + """ + Private method to extract top-level functions or classes. + + @param keyword keyword signaling what to extract (string) + @return extracted function or class contexts (list of DocStyleContext) + """ + self.__resetReadline() + tokenGenerator = tokenize.generate_tokens(self.__readline) + kind, value, char = None, None, None + contexts = [] + try: + while True: + start, end = None, None + while not (kind == tokenize.NAME and + value == keyword and + char == 0): + kind, value, (line, char), _, _ = next(tokenGenerator) + start = line - 1, char + while not (kind == tokenize.DEDENT and + value == '' and + char == 0): + kind, value, (line, char), _, _ = next(tokenGenerator) + end = line - 1, char + contexts.append(DocStyleContext( + self.__source[start[0]:end[0]], start[0], keyword)) + except StopIteration: + return contexts + + def __parseFunctions(self): + """ + Private method to extract top-level functions. + + @return extracted function contexts (list of DocStyleContext) + """ + if not self.__functionsCache: + self.__functionsCache = self.__parseTopLevel('def') + return self.__functionsCache + + def __parseClasses(self): + """ + Private method to extract top-level classes. + + @return extracted class contexts (list of DocStyleContext) + """ + if not self.__classesCache: + self.__classesCache = self.__parseTopLevel('class') + return self.__classesCache + + def __skipIndentedBlock(self, tokenGenerator): + """ + Private method to skip over an indented block of source code. + + @param tokenGenerator token generator + @return last token of the indented block + """ + kind, value, start, end, raw = next(tokenGenerator) + while kind != tokenize.INDENT: + kind, value, start, end, raw = next(tokenGenerator) + indent = 1 + for kind, value, start, end, raw in tokenGenerator: + if kind == tokenize.INDENT: + indent += 1 + elif kind == tokenize.DEDENT: + indent -= 1 + if indent == 0: + return kind, value, start, end, raw + + def __parseMethods(self): + """ + Private method to extract methods of all classes. + + @return extracted method contexts (list of DocStyleContext) + """ + if not self.__methodsCache: + contexts = [] + for classContext in self.__parseClasses(): + tokenGenerator = tokenize.generate_tokens( + StringIO(classContext.ssource()).readline) + kind, value, char = None, None, None + try: + while True: + start, end = None, None + while not (kind == tokenize.NAME and value == 'def'): + kind, value, (line, char), _, _ = \ + next(tokenGenerator) + start = line - 1, char + kind, value, (line, char), _, _ = \ + self.__skipIndentedBlock(tokenGenerator) + end = line - 1, char + startLine = classContext.start() + start[0] + endLine = classContext.start() + end[0] + contexts.append( + DocStyleContext(self.__source[startLine:endLine], + startLine, "def")) + except StopIteration: + pass + self.__methodsCache = contexts + + return self.__methodsCache + + def __parseContexts(self, kind): + """ + Private method to extract a context from the source. + + @param kind kind of context to extract (string) + @return requested contexts (list of DocStyleContext) + """ + if kind == 'moduleDocstring': + return [DocStyleContext(self.__source, 0, "module")] + if kind == 'functionDocstring': + return self.__parseFunctions() + if kind == 'classDocstring': + return self.__parseClasses() + if kind == 'methodDocstring': + return self.__parseMethods() + if kind == 'defDocstring': + return self.__parseFunctions() + self.__parseMethods() + if kind == 'docstring': + return ([DocStyleContext(self.__source, 0, "module")] + + self.__parseFunctions() + + self.__parseClasses() + + self.__parseMethods()) + return [] # fall back + + ################################################################## + ## Checking functionality below (PEP-257) + ################################################################## + + def __checkModulesDocstrings(self, docstringContext, context): + """ + Private method to check, if the module has a docstring. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + self.__error(context.start(), 0, "D101") + return + + docstring = docstringContext.ssource() + if (not docstring or not docstring.strip() or + not docstring.strip('\'"')): + self.__error(context.start(), 0, "D101") + + def __checkFunctionDocstring(self, docstringContext, context): + """ + Private method to check, that all public functions and methods + have a docstring. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + functionName = context.source()[0].lstrip().split()[1].split("(")[0] + if functionName.startswith('_') and not functionName.endswith('__'): + if self.__docType == "eric": + code = "D203" + else: + code = "D103" + else: + code = "D102" + + if docstringContext is None: + self.__error(context.start(), 0, code) + return + + docstring = docstringContext.ssource() + if (not docstring or not docstring.strip() or + not docstring.strip('\'"')): + self.__error(context.start(), 0, code) + + def __checkClassDocstring(self, docstringContext, context): + """ + Private method to check, that all public functions and methods + have a docstring. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + className = context.source()[0].lstrip().split()[1].split("(")[0] + if className.startswith('_'): + if self.__docType == "eric": + code = "D205" + else: + code = "D105" + else: + code = "D104" + + if docstringContext is None: + self.__error(context.start(), 0, code) + return + + docstring = docstringContext.ssource() + if (not docstring or not docstring.strip() or + not docstring.strip('\'"')): + self.__error(context.start(), 0, code) + + def __checkTripleDoubleQuotes(self, docstringContext, context): + """ + Private method to check, that all docstrings are surrounded + by triple double quotes. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + docstring = docstringContext.ssource().strip() + if not docstring.startswith(('"""', 'r"""', 'u"""')): + self.__error(docstringContext.start(), 0, "D111") + + def __checkBackslashes(self, docstringContext, context): + """ + Private method to check, that all docstrings containing + backslashes are surrounded by raw triple double quotes. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + docstring = docstringContext.ssource().strip() + if "\\" in docstring and not docstring.startswith('r"""'): + self.__error(docstringContext.start(), 0, "D112") + + def __checkUnicode(self, docstringContext, context): + """ + Private method to check, that all docstrings containing unicode + characters are surrounded by unicode triple double quotes. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + docstring = docstringContext.ssource().strip() + if not docstring.startswith('u"""') and \ + any(ord(char) > 127 for char in docstring): + self.__error(docstringContext.start(), 0, "D113") + + def __checkOneLiner(self, docstringContext, context): + """ + Private method to check, that one-liner docstrings fit on + one line with quotes. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + lines = docstringContext.source() + if len(lines) > 1: + nonEmptyLines = [l for l in lines if l.strip().strip('\'"')] + if len(nonEmptyLines) == 1: + modLen = len(context.indent() + '"""' + + nonEmptyLines[0].strip() + '"""') + if context.contextType() != "module": + modLen += 4 + if not nonEmptyLines[0].strip().endswith("."): + # account for a trailing dot + modLen += 1 + if modLen <= self.__maxLineLength: + self.__error(docstringContext.start(), 0, "D121") + + def __checkIndent(self, docstringContext, context): + """ + Private method to check, that docstrings are properly indented. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + lines = docstringContext.source() + if len(lines) == 1: + return + + nonEmptyLines = [l.rstrip() for l in lines[1:] if l.strip()] + if not nonEmptyLines: + return + + indent = min([len(l) - len(l.strip()) for l in nonEmptyLines]) + if context.contextType() == "module": + expectedIndent = 0 + else: + expectedIndent = len(context.indent()) + 4 + if indent != expectedIndent: + self.__error(docstringContext.start(), 0, "D122") + + def __checkEndsWithPeriod(self, docstringContext, context): + """ + Private method to check, that docstring summaries end with a period. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + summary, lineNumber = self.__getSummaryLine(docstringContext) + if not summary.endswith("."): + self.__error(docstringContext.start() + lineNumber, 0, "D131") + + def __checkImperativeMood(self, docstringContext, context): + """ + Private method to check, that docstring summaries are in + imperative mood. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + summary, lineNumber = self.__getSummaryLine(docstringContext) + firstWord = summary.strip().split()[0] + if firstWord.endswith("s") and not firstWord.endswith("ss"): + self.__error(docstringContext.start() + lineNumber, 0, "D132") + + def __checkNoSignature(self, docstringContext, context): + """ + Private method to check, that docstring summaries don't repeat + the function's signature. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + functionName = context.source()[0].lstrip().split()[1].split("(")[0] + summary, lineNumber = self.__getSummaryLine(docstringContext) + if functionName + "(" in summary.replace(" ", "") and \ + not functionName + "()" in summary.replace(" ", ""): + # report only, if it is not an abbreviated form (i.e. function() ) + self.__error(docstringContext.start() + lineNumber, 0, "D133") + + def __checkReturnType(self, docstringContext, context): + """ + Private method to check, that docstrings mention the return value type. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + if "return" not in docstringContext.ssource().lower(): + tokens = list( + tokenize.generate_tokens(StringIO(context.ssource()).readline)) + return_ = [tokens[i + 1][0] for i, token in enumerate(tokens) + if token[1] == "return"] + if (set(return_) - + set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) != + set([])): + self.__error(docstringContext.end(), 0, "D134") + + def __checkNoBlankLineBefore(self, docstringContext, context): + """ + Private method to check, that function/method docstrings are not + preceded by a blank line. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + contextLines = context.source() + cti = 0 + while cti < len(contextLines) and \ + not contextLines[cti].strip().startswith( + ('"""', 'r"""', 'u"""', "'''", "r'''", "u'''")): + cti += 1 + if cti == len(contextLines): + return + + if not contextLines[cti - 1].strip(): + self.__error(docstringContext.start(), 0, "D141") + + def __checkBlankBeforeAndAfterClass(self, docstringContext, context): + """ + Private method to check, that class docstrings have one + blank line around them. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + contextLines = context.source() + cti = 0 + while cti < len(contextLines) and \ + not contextLines[cti].strip().startswith( + ('"""', 'r"""', 'u"""', "'''", "r'''", "u'''")): + cti += 1 + if cti == len(contextLines): + return + + start = cti + if contextLines[cti].strip() in ( + '"""', 'r"""', 'u"""', "'''", "r'''", "u'''"): + # it is a multi line docstring + cti += 1 + + while cti < len(contextLines) and \ + not contextLines[cti].strip().endswith(('"""', "'''")): + cti += 1 + end = cti + if cti >= len(contextLines) - 1: + return + + if contextLines[start - 1].strip(): + self.__error(docstringContext.start(), 0, "D142") + if contextLines[end + 1].strip(): + self.__error(docstringContext.end(), 0, "D143") + + def __checkBlankAfterSummary(self, docstringContext, context): + """ + Private method to check, that docstring summaries are followed + by a blank line. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + docstrings = docstringContext.source() + if len(docstrings) <= 3: + # correct/invalid one-liner + return + + summary, lineNumber = self.__getSummaryLine(docstringContext) + if len(docstrings) > 2: + if docstrings[lineNumber + 1].strip(): + self.__error(docstringContext.start() + lineNumber, 0, "D144") + + def __checkBlankAfterLastParagraph(self, docstringContext, context): + """ + Private method to check, that the last paragraph of docstrings is + followed by a blank line. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + docstrings = docstringContext.source() + if len(docstrings) <= 3: + # correct/invalid one-liner + return + + if docstrings[-2].strip(): + self.__error(docstringContext.end(), 0, "D145") + + ################################################################## + ## Checking functionality below (eric specific ones) + ################################################################## + + def __checkEricQuotesOnSeparateLines(self, docstringContext, context): + """ + Private method to check, that leading and trailing quotes are on + a line by themselves. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + lines = docstringContext.source() + if lines[0].strip().strip('ru"\''): + self.__error(docstringContext.start(), 0, "D221") + if lines[-1].strip().strip('"\''): + self.__error(docstringContext.end(), 0, "D222") + + def __checkEricEndsWithPeriod(self, docstringContext, context): + """ + Private method to check, that docstring summaries end with a period. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + summaryLines, lineNumber = self.__getSummaryLines(docstringContext) + if summaryLines[-1].lstrip().startswith("@"): + summaryLines.pop(-1) + summary = " ".join([s.strip() for s in summaryLines if s]) + if not summary.endswith(".") and \ + not summary.split(None, 1)[0].lower() == "constructor": + self.__error( + docstringContext.start() + lineNumber + len(summaryLines) - 1, + 0, "D231") + + def __checkEricReturn(self, docstringContext, context): + """ + Private method to check, that docstrings contain an @return line + if they return anything and don't otherwise. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + tokens = list( + tokenize.generate_tokens(StringIO(context.ssource()).readline)) + return_ = [tokens[i + 1][0] for i, token in enumerate(tokens) + if token[1] in ("return", "yield")] + if "@return" not in docstringContext.ssource(): + if (set(return_) - + set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) != + set([])): + self.__error(docstringContext.end(), 0, "D234") + else: + if (set(return_) - + set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) == + set([])): + self.__error(docstringContext.end(), 0, "D235") + + def __checkEricFunctionArguments(self, docstringContext, context): + """ + Private method to check, that docstrings contain an @param and/or + @keyparam line for each argument. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + try: + tree = ast.parse(context.ssource()) + except (SyntaxError, TypeError): + return + if (isinstance(tree, ast.Module) and len(tree.body) == 1 and + isinstance(tree.body[0], ast.FunctionDef)): + functionDef = tree.body[0] + argNames, kwNames = self.__getArgNames(functionDef) + if "self" in argNames: + argNames.remove("self") + if "cls" in argNames: + argNames.remove("cls") + + docstring = docstringContext.ssource() + if (docstring.count("@param") + docstring.count("@keyparam") < + len(argNames + kwNames)): + self.__error(docstringContext.end(), 0, "D236") + elif (docstring.count("@param") + docstring.count("@keyparam") > + len(argNames + kwNames)): + self.__error(docstringContext.end(), 0, "D237") + else: + # extract @param and @keyparam from docstring + args = [] + kwargs = [] + for line in docstringContext.source(): + if line.strip().startswith(("@param", "@keyparam")): + at, name = line.strip().split(None, 2)[:2] + if at == "@keyparam": + kwargs.append(name.lstrip("*")) + args.append(name.lstrip("*")) + + # do the checks + for name in kwNames: + if name not in kwargs: + self.__error(docstringContext.end(), 0, "D238") + return + if argNames + kwNames != args: + self.__error(docstringContext.end(), 0, "D239") + + def __checkEricException(self, docstringContext, context): + """ + Private method to check, that docstrings contain an @exception line + if they raise an exception and don't otherwise. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + tokens = list( + tokenize.generate_tokens(StringIO(context.ssource()).readline)) + exception = [tokens[i + 1][0] for i, token in enumerate(tokens) + if token[1] == "raise"] + if "@exception" not in docstringContext.ssource() and \ + "@throws" not in docstringContext.ssource() and \ + "@raise" not in docstringContext.ssource(): + if (set(exception) - + set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) != + set([])): + self.__error(docstringContext.end(), 0, "D250") + else: + if (set(exception) - + set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) == + set([])): + self.__error(docstringContext.end(), 0, "D251") + + def __checkEricBlankAfterSummary(self, docstringContext, context): + """ + Private method to check, that docstring summaries are followed + by a blank line. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + docstrings = docstringContext.source() + if len(docstrings) <= 3: + # correct/invalid one-liner + return + + summaryLines, lineNumber = self.__getSummaryLines(docstringContext) + if len(docstrings) - 2 > lineNumber + len(summaryLines) - 1: + if docstrings[lineNumber + len(summaryLines)].strip(): + self.__error(docstringContext.start() + lineNumber, 0, "D246") + + def __checkEricNoBlankBeforeAndAfterClassOrFunction( + self, docstringContext, context): + """ + Private method to check, that class and function/method docstrings + have no blank line around them. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + contextLines = context.source() + isClassContext = contextLines[0].lstrip().startswith("class ") + cti = 0 + while cti < len(contextLines) and \ + not contextLines[cti].strip().startswith( + ('"""', 'r"""', 'u"""', "'''", "r'''", "u'''")): + cti += 1 + if cti == len(contextLines): + return + + start = cti + if contextLines[cti].strip() in ( + '"""', 'r"""', 'u"""', "'''", "r'''", "u'''"): + # it is a multi line docstring + cti += 1 + + while cti < len(contextLines) and \ + not contextLines[cti].strip().endswith(('"""', "'''")): + cti += 1 + end = cti + if cti >= len(contextLines) - 1: + return + + if isClassContext: + if not contextLines[start - 1].strip(): + self.__error(docstringContext.start(), 0, "D242") + if not contextLines[end + 1].strip(): + self.__error(docstringContext.end(), 0, "D243") + else: + if not contextLines[start - 1].strip(): + self.__error(docstringContext.start(), 0, "D244") + if not contextLines[end + 1].strip(): + self.__error(docstringContext.end(), 0, "D245") + + def __checkEricNBlankAfterLastParagraph(self, docstringContext, context): + """ + Private method to check, that the last paragraph of docstrings is + not followed by a blank line. + + @param docstringContext docstring context (DocStyleContext) + @param context context of the docstring (DocStyleContext) + """ + if docstringContext is None: + return + + docstrings = docstringContext.source() + if len(docstrings) <= 3: + # correct/invalid one-liner + return + + if not docstrings[-2].strip(): + self.__error(docstringContext.end(), 0, "D247")
--- a/Plugins/CheckerPlugins/Pep8/Pep257Checker.py Sun Sep 29 19:24:27 2013 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1304 +0,0 @@ -# -*- coding: utf-8 -*- - -# Copyright (c) 2013 Detlev Offenbach <detlev@die-offenbachs.de> -# - -""" -Module implementing a checker for PEP-257 documentation string conventions. -""" - -# -# The routines of the checker class are modeled after the ones found in -# pep257.py (version 0.2.4). -# - -try: - # Python 2 - from StringIO import StringIO # __IGNORE_EXCEPTION__ -except ImportError: - # Python 3 - from io import StringIO # __IGNORE_WARNING__ -import tokenize -import ast -import sys - -from PyQt4.QtCore import QT_TRANSLATE_NOOP, QCoreApplication - - -class Pep257Context(object): - """ - Class implementing the source context. - """ - def __init__(self, source, startLine, contextType): - """ - Constructor - - @param source source code of the context (list of string or string) - @param startLine line number the context starts in the source (integer) - @param contextType type of the context object (string) - """ - if isinstance(source, str): - self.__source = source.splitlines(True) - else: - self.__source = source[:] - self.__start = startLine - self.__indent = "" - self.__type = contextType - - # ensure first line is left justified - if self.__source: - self.__indent = self.__source[0].replace( - self.__source[0].lstrip(), "") - self.__source[0] = self.__source[0].lstrip() - - def source(self): - """ - Public method to get the source. - - @return source (list of string) - """ - return self.__source - - def ssource(self): - """ - Public method to get the joined source lines. - - @return source (string) - """ - return "".join(self.__source) - - def start(self): - """ - Public method to get the start line number. - - @return start line number (integer) - """ - return self.__start - - def end(self): - """ - Public method to get the end line number. - - @return end line number (integer) - """ - return self.__start + len(self.__source) - 1 - - def indent(self): - """ - Public method to get the indentation of the first line. - - @return indentation string (string) - """ - return self.__indent - - def contextType(self): - """ - Public method to get the context type. - - @return context type (string) - """ - return self.__type - - -class Pep257Checker(object): - """ - Class implementing a checker for PEP-257 documentation string conventions. - """ - Codes = [ - "D101", "D102", "D103", "D104", "D105", - "D111", "D112", "D113", - "D121", "D122", - "D131", "D132", "D133", "D134", - "D141", "D142", "D143", "D144", "D145", - - "D203", "D205", - "D221", "D222", - "D231", "D234", "D235", "D236", "D237", "D238", "D239", - "D242", "D243", "D244", "D245", "D246", "D247", - "D250", "D251", - ] - - Messages = { - "D101": QT_TRANSLATE_NOOP( - "Pep257Checker", "module is missing a docstring"), - "D102": QT_TRANSLATE_NOOP( - "Pep257Checker", "public function/method is missing a docstring"), - "D103": QT_TRANSLATE_NOOP( - "Pep257Checker", - "private function/method may be missing a docstring"), - "D104": QT_TRANSLATE_NOOP( - "Pep257Checker", "public class is missing a docstring"), - "D105": QT_TRANSLATE_NOOP( - "Pep257Checker", "private class may be missing a docstring"), - "D111": QT_TRANSLATE_NOOP( - "Pep257Checker", 'docstring not surrounded by """'), - "D112": QT_TRANSLATE_NOOP( - "Pep257Checker", 'docstring containing \\ not surrounded by r"""'), - "D113": QT_TRANSLATE_NOOP( - "Pep257Checker", - 'docstring containing unicode character not surrounded by u"""'), - "D121": QT_TRANSLATE_NOOP( - "Pep257Checker", "one-liner docstring on multiple lines"), - "D122": QT_TRANSLATE_NOOP( - "Pep257Checker", "docstring has wrong indentation"), - "D131": QT_TRANSLATE_NOOP( - "Pep257Checker", "docstring summary does not end with a period"), - "D132": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring summary is not in imperative mood" - " (Does instead of Do)"), - "D133": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring summary looks like a function's/method's signature"), - "D134": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring does not mention the return value type"), - "D141": QT_TRANSLATE_NOOP( - "Pep257Checker", - "function/method docstring is separated by a blank line"), - "D142": QT_TRANSLATE_NOOP( - "Pep257Checker", - "class docstring is not preceded by a blank line"), - "D143": QT_TRANSLATE_NOOP( - "Pep257Checker", - "class docstring is not followed by a blank line"), - "D144": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring summary is not followed by a blank line"), - "D145": QT_TRANSLATE_NOOP( - "Pep257Checker", - "last paragraph of docstring is not followed by a blank line"), - - "D203": QT_TRANSLATE_NOOP( - "Pep257Checker", "private function/method is missing a docstring"), - "D205": QT_TRANSLATE_NOOP( - "Pep257Checker", "private class is missing a docstring"), - "D221": QT_TRANSLATE_NOOP( - "Pep257Checker", - "leading quotes of docstring not on separate line"), - "D222": QT_TRANSLATE_NOOP( - "Pep257Checker", - "trailing quotes of docstring not on separate line"), - "D231": QT_TRANSLATE_NOOP( - "Pep257Checker", "docstring summary does not end with a period"), - "D234": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring does not contain a @return line but function/method" - " returns something"), - "D235": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring contains a @return line but function/method doesn't" - " return anything"), - "D236": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring does not contain enough @param/@keyparam lines"), - "D237": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring contains too many @param/@keyparam lines"), - "D238": QT_TRANSLATE_NOOP( - "Pep257Checker", - "keyword only arguments must be documented with @keyparam lines"), - "D239": QT_TRANSLATE_NOOP( - "Pep257Checker", "order of @param/@keyparam lines does" - " not match the function/method signature"), - "D242": QT_TRANSLATE_NOOP( - "Pep257Checker", "class docstring is preceded by a blank line"), - "D243": QT_TRANSLATE_NOOP( - "Pep257Checker", "class docstring is followed by a blank line"), - "D244": QT_TRANSLATE_NOOP( - "Pep257Checker", - "function/method docstring is preceded by a blank line"), - "D245": QT_TRANSLATE_NOOP( - "Pep257Checker", - "function/method docstring is followed by a blank line"), - "D246": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring summary is not followed by a blank line"), - "D247": QT_TRANSLATE_NOOP( - "Pep257Checker", - "last paragraph of docstring is followed by a blank line"), - "D250": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring does not contain a @exception line but function/method" - " raises an exception"), - "D251": QT_TRANSLATE_NOOP( - "Pep257Checker", - "docstring contains a @exception line but function/method doesn't" - " raise an exception"), - } - - def __init__(self, source, filename, select, ignore, expected, repeat, - maxLineLength=79, docType="pep257"): - """ - Constructor - - @param source source code to be checked (list of string) - @param filename name of the source file (string) - @param select list of selected codes (list of string) - @param ignore list of codes to be ignored (list of string) - @param expected list of expected codes (list of string) - @param repeat flag indicating to report each occurrence of a code - (boolean) - @keyparam maxLineLength allowed line length (integer) - @keyparam docType type of the documentation strings - (string, one of 'eric' or 'pep257') - """ - assert docType in ("eric", "pep257") - - self.__select = tuple(select) - self.__ignore = tuple(ignore) - self.__expected = expected[:] - self.__repeat = repeat - self.__maxLineLength = maxLineLength - self.__docType = docType - self.__filename = filename - self.__source = source[:] - - # statistics counters - self.counters = {} - - # collection of detected errors - self.errors = [] - - self.__lineNumber = 0 - - # caches - self.__functionsCache = None - self.__classesCache = None - self.__methodsCache = None - - self.__keywords = [ - 'moduleDocstring', 'functionDocstring', - 'classDocstring', 'methodDocstring', - 'defDocstring', 'docstring' - ] - if self.__docType == "pep257": - checkersWithCodes = { - "moduleDocstring": [ - (self.__checkModulesDocstrings, ("D101",)), - ], - "functionDocstring": [ - ], - "classDocstring": [ - (self.__checkClassDocstring, ("D104", "D105")), - (self.__checkBlankBeforeAndAfterClass, ("D142", "D143")), - ], - "methodDocstring": [ - ], - "defDocstring": [ - (self.__checkFunctionDocstring, ("D102", "D103")), - (self.__checkImperativeMood, ("D132",)), - (self.__checkNoSignature, ("D133",)), - (self.__checkReturnType, ("D134",)), - (self.__checkNoBlankLineBefore, ("D141",)), - ], - "docstring": [ - (self.__checkTripleDoubleQuotes, ("D111",)), - (self.__checkBackslashes, ("D112",)), - (self.__checkUnicode, ("D113",)), - (self.__checkOneLiner, ("D121",)), - (self.__checkIndent, ("D122",)), - (self.__checkEndsWithPeriod, ("D131",)), - (self.__checkBlankAfterSummary, ("D144",)), - (self.__checkBlankAfterLastParagraph, ("D145",)), - ], - } - elif self.__docType == "eric": - checkersWithCodes = { - "moduleDocstring": [ - (self.__checkModulesDocstrings, ("D101",)), - ], - "functionDocstring": [ - ], - "classDocstring": [ - (self.__checkClassDocstring, ("D104", "D205")), - (self.__checkEricNoBlankBeforeAndAfterClassOrFunction, - ("D242", "D243")), - ], - "methodDocstring": [ - ], - "defDocstring": [ - (self.__checkFunctionDocstring, ("D102", "D203")), - (self.__checkImperativeMood, ("D132",)), - (self.__checkNoSignature, ("D133",)), - (self.__checkEricReturn, ("D234", "D235")), - (self.__checkEricFunctionArguments, - ("D236", "D237", "D238", "D239")), - (self.__checkEricNoBlankBeforeAndAfterClassOrFunction, - ("D244", "D245")), - (self.__checkEricException, ("D250", "D251")), - ], - "docstring": [ - (self.__checkTripleDoubleQuotes, ("D111",)), - (self.__checkBackslashes, ("D112",)), - (self.__checkUnicode, ("D113",)), - (self.__checkIndent, ("D122",)), - (self.__checkEricEndsWithPeriod, ("D231",)), - (self.__checkEricBlankAfterSummary, ("D246",)), - (self.__checkEricNBlankAfterLastParagraph, ("D247",)), - (self.__checkEricQuotesOnSeparateLines, ("D222", "D223")) - ], - } - - self.__checkers = {} - for key, checkers in checkersWithCodes.items(): - for checker, codes in checkers: - if any(not (code and self.__ignoreCode(code)) - for code in codes): - if key not in self.__checkers: - self.__checkers[key] = [] - self.__checkers[key].append(checker) - - def __ignoreCode(self, code): - """ - Private method to check if the error code should be ignored. - - @param code message code to check for (string) - @return flag indicating to ignore the given code (boolean) - """ - return (code.startswith(self.__ignore) and - not code.startswith(self.__select)) - - def __error(self, lineNumber, offset, code, *args): - """ - Private method to record an issue. - - @param lineNumber line number of the issue (integer) - @param offset position within line of the issue (integer) - @param code message code (string) - @param args arguments for the message (list) - """ - if self.__ignoreCode(code): - return - - if code in self.counters: - self.counters[code] += 1 - else: - self.counters[code] = 1 - - # Don't care about expected codes - if code in self.__expected: - return - - if code and (self.counters[code] == 1 or self.__repeat): - if code in Pep257Checker.Codes: - text = self.getMessage(code, *args) - else: - text = code + " " + QCoreApplication.translate( - "Pep257Checker", "no message for this code defined") - # record the issue with one based line number - self.errors.append((self.__filename, lineNumber + 1, offset, text)) - - @classmethod - def getMessage(cls, code, *args): - """ - Class method to get a translated and formatted message for a - given code. - - @param code message code (string) - @param args arguments for a formatted message (list) - @return translated and formatted message (string) - """ - if code in Pep257Checker.Messages: - return code + " " + QCoreApplication.translate( - "Pep257Checker", Pep257Checker.Messages[code]).format(*args) - else: - return code + " " + QCoreApplication.translate( - "Pep257Checker", "no message for this code defined") - - def __resetReadline(self): - """ - Private method to reset the internal readline function. - """ - self.__lineNumber = 0 - - def __readline(self): - """ - Private method to get the next line from the source. - - @return next line of source (string) - """ - self.__lineNumber += 1 - if self.__lineNumber > len(self.__source): - return '' - return self.__source[self.__lineNumber - 1] - - def run(self): - """ - Public method to check the given source for violations of doc string - conventions according to PEP-257. - """ - if not self.__source or not self.__filename: - # don't do anything, if essential data is missing - return - - if not self.__checkers: - # don't do anything, if no codes were selected - return - - for keyword in self.__keywords: - if keyword in self.__checkers: - for check in self.__checkers[keyword]: - for context in self.__parseContexts(keyword): - docstring = self.__parseDocstring(context, keyword) - check(docstring, context) - - def __getSummaryLine(self, docstringContext): - """ - Private method to extract the summary line. - - @param docstringContext docstring context (Pep257Context) - @return summary line (string) and the line it was found on (integer) - """ - lines = docstringContext.source() - - line = (lines[0] - .replace('r"""', "", 1) - .replace('u"""', "", 1) - .replace('"""', "") - .replace("r'''", "", 1) - .replace("u'''", "", 1) - .replace("'''", "") - .strip()) - - if len(lines) == 1 or len(line) > 0: - return line, 0 - return lines[1].strip().replace('"""', "").replace("'''", ""), 1 - - def __getSummaryLines(self, docstringContext): - """ - Private method to extract the summary lines. - - @param docstringContext docstring context (Pep257Context) - @return summary lines (list of string) and the line it was found on - (integer) - """ - summaries = [] - lines = docstringContext.source() - - line0 = (lines[0] - .replace('r"""', "", 1) - .replace('u"""', "", 1) - .replace('"""', "") - .replace("r'''", "", 1) - .replace("u'''", "", 1) - .replace("'''", "") - .strip()) - if len(lines) > 1: - line1 = lines[1].strip().replace('"""', "").replace("'''", "") - else: - line1 = "" - if len(lines) > 2: - line2 = lines[2].strip().replace('"""', "").replace("'''", "") - else: - line2 = "" - if line0: - lineno = 0 - summaries.append(line0) - if not line0.endswith(".") and line1: - # two line summary - summaries.append(line1) - elif line1: - lineno = 1 - summaries.append(line1) - if not line1.endswith(".") and line2: - # two line summary - summaries.append(line2) - else: - lineno = 2 - summaries.append(line2) - return summaries, lineno - - if sys.version_info[0] < 3: - def __getArgNames(self, node): - """ - Private method to get the argument names of a function node. - - @param node AST node to extract arguments names from - @return tuple of two list of argument names, one for arguments - and one for keyword arguments (tuple of list of string) - """ - def unpackArgs(args): - """ - Local helper function to unpack function argument names. - - @param args list of AST node arguments - @return list of argument names (list of string) - """ - ret = [] - for arg in args: - if isinstance(arg, ast.Tuple): - ret.extend(unpackArgs(arg.elts)) - else: - ret.append(arg.id) - return ret - - arguments = unpackArgs(node.args.args) - if node.args.vararg is not None: - arguments.append(node.args.vararg) - kwarguments = [] - if node.args.kwarg is not None: - kwarguments.append(node.args.kwarg) - return arguments, kwarguments - else: - def __getArgNames(self, node): # __IGNORE_WARNING__ - """ - Private method to get the argument names of a function node. - - @param node AST node to extract arguments names from - @return tuple of two list of argument names, one for arguments - and one for keyword arguments (tuple of list of string) - """ - arguments = [] - arguments.extend([arg.arg for arg in node.args.args]) - if node.args.vararg is not None: - arguments.append(node.args.vararg) - - kwarguments = [] - kwarguments.extend([arg.arg for arg in node.args.kwonlyargs]) - if node.args.kwarg is not None: - kwarguments.append(node.args.kwarg) - return arguments, kwarguments - - ################################################################## - ## Parsing functionality below - ################################################################## - - def __parseModuleDocstring(self, source): - """ - Private method to extract a docstring given a module source. - - @param source source to parse (list of string) - @return context of extracted docstring (Pep257Context) - """ - for kind, value, (line, char), _, _ in tokenize.generate_tokens( - StringIO("".join(source)).readline): - if kind in [tokenize.COMMENT, tokenize.NEWLINE, tokenize.NL]: - continue - elif kind == tokenize.STRING: # first STRING should be docstring - return Pep257Context(value, line - 1, "docstring") - else: - return None - - def __parseDocstring(self, context, what=''): - """ - Private method to extract a docstring given `def` or `class` source. - - @param context context data to get the docstring from (Pep257Context) - @param what string denoting what is being parsed (string) - @return context of extracted docstring (Pep257Context) - """ - moduleDocstring = self.__parseModuleDocstring(context.source()) - if what.startswith('module') or context.contextType() == "module": - return moduleDocstring - if moduleDocstring: - return moduleDocstring - - tokenGenerator = tokenize.generate_tokens( - StringIO(context.ssource()).readline) - try: - kind = None - while kind != tokenize.INDENT: - kind, _, _, _, _ = next(tokenGenerator) - kind, value, (line, char), _, _ = next(tokenGenerator) - if kind == tokenize.STRING: # STRING after INDENT is a docstring - return Pep257Context( - value, context.start() + line - 1, "docstring") - except StopIteration: - pass - - return None - - def __parseTopLevel(self, keyword): - """ - Private method to extract top-level functions or classes. - - @param keyword keyword signaling what to extract (string) - @return extracted function or class contexts (list of Pep257Context) - """ - self.__resetReadline() - tokenGenerator = tokenize.generate_tokens(self.__readline) - kind, value, char = None, None, None - contexts = [] - try: - while True: - start, end = None, None - while not (kind == tokenize.NAME and - value == keyword and - char == 0): - kind, value, (line, char), _, _ = next(tokenGenerator) - start = line - 1, char - while not (kind == tokenize.DEDENT and - value == '' and - char == 0): - kind, value, (line, char), _, _ = next(tokenGenerator) - end = line - 1, char - contexts.append(Pep257Context( - self.__source[start[0]:end[0]], start[0], keyword)) - except StopIteration: - return contexts - - def __parseFunctions(self): - """ - Private method to extract top-level functions. - - @return extracted function contexts (list of Pep257Context) - """ - if not self.__functionsCache: - self.__functionsCache = self.__parseTopLevel('def') - return self.__functionsCache - - def __parseClasses(self): - """ - Private method to extract top-level classes. - - @return extracted class contexts (list of Pep257Context) - """ - if not self.__classesCache: - self.__classesCache = self.__parseTopLevel('class') - return self.__classesCache - - def __skipIndentedBlock(self, tokenGenerator): - """ - Private method to skip over an indented block of source code. - - @param tokenGenerator token generator - @return last token of the indented block - """ - kind, value, start, end, raw = next(tokenGenerator) - while kind != tokenize.INDENT: - kind, value, start, end, raw = next(tokenGenerator) - indent = 1 - for kind, value, start, end, raw in tokenGenerator: - if kind == tokenize.INDENT: - indent += 1 - elif kind == tokenize.DEDENT: - indent -= 1 - if indent == 0: - return kind, value, start, end, raw - - def __parseMethods(self): - """ - Private method to extract methods of all classes. - - @return extracted method contexts (list of Pep257Context) - """ - if not self.__methodsCache: - contexts = [] - for classContext in self.__parseClasses(): - tokenGenerator = tokenize.generate_tokens( - StringIO(classContext.ssource()).readline) - kind, value, char = None, None, None - try: - while True: - start, end = None, None - while not (kind == tokenize.NAME and value == 'def'): - kind, value, (line, char), _, _ = \ - next(tokenGenerator) - start = line - 1, char - kind, value, (line, char), _, _ = \ - self.__skipIndentedBlock(tokenGenerator) - end = line - 1, char - startLine = classContext.start() + start[0] - endLine = classContext.start() + end[0] - contexts.append( - Pep257Context(self.__source[startLine:endLine], - startLine, "def")) - except StopIteration: - pass - self.__methodsCache = contexts - - return self.__methodsCache - - def __parseContexts(self, kind): - """ - Private method to extract a context from the source. - - @param kind kind of context to extract (string) - @return requested contexts (list of Pep257Context) - """ - if kind == 'moduleDocstring': - return [Pep257Context(self.__source, 0, "module")] - if kind == 'functionDocstring': - return self.__parseFunctions() - if kind == 'classDocstring': - return self.__parseClasses() - if kind == 'methodDocstring': - return self.__parseMethods() - if kind == 'defDocstring': - return self.__parseFunctions() + self.__parseMethods() - if kind == 'docstring': - return ([Pep257Context(self.__source, 0, "module")] + - self.__parseFunctions() + - self.__parseClasses() + - self.__parseMethods()) - return [] # fall back - - ################################################################## - ## Checking functionality below (PEP-257) - ################################################################## - - def __checkModulesDocstrings(self, docstringContext, context): - """ - Private method to check, if the module has a docstring. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - self.__error(context.start(), 0, "D101") - return - - docstring = docstringContext.ssource() - if (not docstring or not docstring.strip() or - not docstring.strip('\'"')): - self.__error(context.start(), 0, "D101") - - def __checkFunctionDocstring(self, docstringContext, context): - """ - Private method to check, that all public functions and methods - have a docstring. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - functionName = context.source()[0].lstrip().split()[1].split("(")[0] - if functionName.startswith('_') and not functionName.endswith('__'): - if self.__docType == "eric": - code = "D203" - else: - code = "D103" - else: - code = "D102" - - if docstringContext is None: - self.__error(context.start(), 0, code) - return - - docstring = docstringContext.ssource() - if (not docstring or not docstring.strip() or - not docstring.strip('\'"')): - self.__error(context.start(), 0, code) - - def __checkClassDocstring(self, docstringContext, context): - """ - Private method to check, that all public functions and methods - have a docstring. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - className = context.source()[0].lstrip().split()[1].split("(")[0] - if className.startswith('_'): - if self.__docType == "eric": - code = "D205" - else: - code = "D105" - else: - code = "D104" - - if docstringContext is None: - self.__error(context.start(), 0, code) - return - - docstring = docstringContext.ssource() - if (not docstring or not docstring.strip() or - not docstring.strip('\'"')): - self.__error(context.start(), 0, code) - - def __checkTripleDoubleQuotes(self, docstringContext, context): - """ - Private method to check, that all docstrings are surrounded - by triple double quotes. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - docstring = docstringContext.ssource().strip() - if not docstring.startswith(('"""', 'r"""', 'u"""')): - self.__error(docstringContext.start(), 0, "D111") - - def __checkBackslashes(self, docstringContext, context): - """ - Private method to check, that all docstrings containing - backslashes are surrounded by raw triple double quotes. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - docstring = docstringContext.ssource().strip() - if "\\" in docstring and not docstring.startswith('r"""'): - self.__error(docstringContext.start(), 0, "D112") - - def __checkUnicode(self, docstringContext, context): - """ - Private method to check, that all docstrings containing unicode - characters are surrounded by unicode triple double quotes. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - docstring = docstringContext.ssource().strip() - if not docstring.startswith('u"""') and \ - any(ord(char) > 127 for char in docstring): - self.__error(docstringContext.start(), 0, "D113") - - def __checkOneLiner(self, docstringContext, context): - """ - Private method to check, that one-liner docstrings fit on - one line with quotes. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - lines = docstringContext.source() - if len(lines) > 1: - nonEmptyLines = [l for l in lines if l.strip().strip('\'"')] - if len(nonEmptyLines) == 1: - modLen = len(context.indent() + '"""' + - nonEmptyLines[0].strip() + '"""') - if context.contextType() != "module": - modLen += 4 - if not nonEmptyLines[0].strip().endswith("."): - # account for a trailing dot - modLen += 1 - if modLen <= self.__maxLineLength: - self.__error(docstringContext.start(), 0, "D121") - - def __checkIndent(self, docstringContext, context): - """ - Private method to check, that docstrings are properly indented. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - lines = docstringContext.source() - if len(lines) == 1: - return - - nonEmptyLines = [l.rstrip() for l in lines[1:] if l.strip()] - if not nonEmptyLines: - return - - indent = min([len(l) - len(l.strip()) for l in nonEmptyLines]) - if context.contextType() == "module": - expectedIndent = 0 - else: - expectedIndent = len(context.indent()) + 4 - if indent != expectedIndent: - self.__error(docstringContext.start(), 0, "D122") - - def __checkEndsWithPeriod(self, docstringContext, context): - """ - Private method to check, that docstring summaries end with a period. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - summary, lineNumber = self.__getSummaryLine(docstringContext) - if not summary.endswith("."): - self.__error(docstringContext.start() + lineNumber, 0, "D131") - - def __checkImperativeMood(self, docstringContext, context): - """ - Private method to check, that docstring summaries are in - imperative mood. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - summary, lineNumber = self.__getSummaryLine(docstringContext) - firstWord = summary.strip().split()[0] - if firstWord.endswith("s") and not firstWord.endswith("ss"): - self.__error(docstringContext.start() + lineNumber, 0, "D132") - - def __checkNoSignature(self, docstringContext, context): - """ - Private method to check, that docstring summaries don't repeat - the function's signature. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - functionName = context.source()[0].lstrip().split()[1].split("(")[0] - summary, lineNumber = self.__getSummaryLine(docstringContext) - if functionName + "(" in summary.replace(" ", "") and \ - not functionName + "()" in summary.replace(" ", ""): - # report only, if it is not an abbreviated form (i.e. function() ) - self.__error(docstringContext.start() + lineNumber, 0, "D133") - - def __checkReturnType(self, docstringContext, context): - """ - Private method to check, that docstrings mention the return value type. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - if "return" not in docstringContext.ssource().lower(): - tokens = list( - tokenize.generate_tokens(StringIO(context.ssource()).readline)) - return_ = [tokens[i + 1][0] for i, token in enumerate(tokens) - if token[1] == "return"] - if (set(return_) - - set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) != - set([])): - self.__error(docstringContext.end(), 0, "D134") - - def __checkNoBlankLineBefore(self, docstringContext, context): - """ - Private method to check, that function/method docstrings are not - preceded by a blank line. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - contextLines = context.source() - cti = 0 - while cti < len(contextLines) and \ - not contextLines[cti].strip().startswith( - ('"""', 'r"""', 'u"""', "'''", "r'''", "u'''")): - cti += 1 - if cti == len(contextLines): - return - - if not contextLines[cti - 1].strip(): - self.__error(docstringContext.start(), 0, "D141") - - def __checkBlankBeforeAndAfterClass(self, docstringContext, context): - """ - Private method to check, that class docstrings have one - blank line around them. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - contextLines = context.source() - cti = 0 - while cti < len(contextLines) and \ - not contextLines[cti].strip().startswith( - ('"""', 'r"""', 'u"""', "'''", "r'''", "u'''")): - cti += 1 - if cti == len(contextLines): - return - - start = cti - if contextLines[cti].strip() in ( - '"""', 'r"""', 'u"""', "'''", "r'''", "u'''"): - # it is a multi line docstring - cti += 1 - - while cti < len(contextLines) and \ - not contextLines[cti].strip().endswith(('"""', "'''")): - cti += 1 - end = cti - if cti >= len(contextLines) - 1: - return - - if contextLines[start - 1].strip(): - self.__error(docstringContext.start(), 0, "D142") - if contextLines[end + 1].strip(): - self.__error(docstringContext.end(), 0, "D143") - - def __checkBlankAfterSummary(self, docstringContext, context): - """ - Private method to check, that docstring summaries are followed - by a blank line. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - docstrings = docstringContext.source() - if len(docstrings) <= 3: - # correct/invalid one-liner - return - - summary, lineNumber = self.__getSummaryLine(docstringContext) - if len(docstrings) > 2: - if docstrings[lineNumber + 1].strip(): - self.__error(docstringContext.start() + lineNumber, 0, "D144") - - def __checkBlankAfterLastParagraph(self, docstringContext, context): - """ - Private method to check, that the last paragraph of docstrings is - followed by a blank line. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - docstrings = docstringContext.source() - if len(docstrings) <= 3: - # correct/invalid one-liner - return - - if docstrings[-2].strip(): - self.__error(docstringContext.end(), 0, "D145") - - ################################################################## - ## Checking functionality below (eric specific ones) - ################################################################## - - def __checkEricQuotesOnSeparateLines(self, docstringContext, context): - """ - Private method to check, that leading and trailing quotes are on - a line by themselves. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - lines = docstringContext.source() - if lines[0].strip().strip('ru"\''): - self.__error(docstringContext.start(), 0, "D221") - if lines[-1].strip().strip('"\''): - self.__error(docstringContext.end(), 0, "D222") - - def __checkEricEndsWithPeriod(self, docstringContext, context): - """ - Private method to check, that docstring summaries end with a period. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - summaryLines, lineNumber = self.__getSummaryLines(docstringContext) - if summaryLines[-1].lstrip().startswith("@"): - summaryLines.pop(-1) - summary = " ".join([s.strip() for s in summaryLines if s]) - if not summary.endswith(".") and \ - not summary.split(None, 1)[0].lower() == "constructor": - self.__error( - docstringContext.start() + lineNumber + len(summaryLines) - 1, - 0, "D231") - - def __checkEricReturn(self, docstringContext, context): - """ - Private method to check, that docstrings contain an @return line - if they return anything and don't otherwise. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - tokens = list( - tokenize.generate_tokens(StringIO(context.ssource()).readline)) - return_ = [tokens[i + 1][0] for i, token in enumerate(tokens) - if token[1] in ("return", "yield")] - if "@return" not in docstringContext.ssource(): - if (set(return_) - - set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) != - set([])): - self.__error(docstringContext.end(), 0, "D234") - else: - if (set(return_) - - set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) == - set([])): - self.__error(docstringContext.end(), 0, "D235") - - def __checkEricFunctionArguments(self, docstringContext, context): - """ - Private method to check, that docstrings contain an @param and/or - @keyparam line for each argument. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - try: - tree = ast.parse(context.ssource()) - except (SyntaxError, TypeError): - return - if (isinstance(tree, ast.Module) and len(tree.body) == 1 and - isinstance(tree.body[0], ast.FunctionDef)): - functionDef = tree.body[0] - argNames, kwNames = self.__getArgNames(functionDef) - if "self" in argNames: - argNames.remove("self") - if "cls" in argNames: - argNames.remove("cls") - - docstring = docstringContext.ssource() - if (docstring.count("@param") + docstring.count("@keyparam") < - len(argNames + kwNames)): - self.__error(docstringContext.end(), 0, "D236") - elif (docstring.count("@param") + docstring.count("@keyparam") > - len(argNames + kwNames)): - self.__error(docstringContext.end(), 0, "D237") - else: - # extract @param and @keyparam from docstring - args = [] - kwargs = [] - for line in docstringContext.source(): - if line.strip().startswith(("@param", "@keyparam")): - at, name = line.strip().split(None, 2)[:2] - if at == "@keyparam": - kwargs.append(name.lstrip("*")) - args.append(name.lstrip("*")) - - # do the checks - for name in kwNames: - if name not in kwargs: - self.__error(docstringContext.end(), 0, "D238") - return - if argNames + kwNames != args: - self.__error(docstringContext.end(), 0, "D239") - - def __checkEricException(self, docstringContext, context): - """ - Private method to check, that docstrings contain an @exception line - if they raise an exception and don't otherwise. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - tokens = list( - tokenize.generate_tokens(StringIO(context.ssource()).readline)) - exception = [tokens[i + 1][0] for i, token in enumerate(tokens) - if token[1] == "raise"] - if "@exception" not in docstringContext.ssource() and \ - "@throws" not in docstringContext.ssource() and \ - "@raise" not in docstringContext.ssource(): - if (set(exception) - - set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) != - set([])): - self.__error(docstringContext.end(), 0, "D250") - else: - if (set(exception) - - set([tokenize.COMMENT, tokenize.NL, tokenize.NEWLINE]) == - set([])): - self.__error(docstringContext.end(), 0, "D251") - - def __checkEricBlankAfterSummary(self, docstringContext, context): - """ - Private method to check, that docstring summaries are followed - by a blank line. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - docstrings = docstringContext.source() - if len(docstrings) <= 3: - # correct/invalid one-liner - return - - summaryLines, lineNumber = self.__getSummaryLines(docstringContext) - if len(docstrings) - 2 > lineNumber + len(summaryLines) - 1: - if docstrings[lineNumber + len(summaryLines)].strip(): - self.__error(docstringContext.start() + lineNumber, 0, "D246") - - def __checkEricNoBlankBeforeAndAfterClassOrFunction( - self, docstringContext, context): - """ - Private method to check, that class and function/method docstrings - have no blank line around them. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - contextLines = context.source() - isClassContext = contextLines[0].lstrip().startswith("class ") - cti = 0 - while cti < len(contextLines) and \ - not contextLines[cti].strip().startswith( - ('"""', 'r"""', 'u"""', "'''", "r'''", "u'''")): - cti += 1 - if cti == len(contextLines): - return - - start = cti - if contextLines[cti].strip() in ( - '"""', 'r"""', 'u"""', "'''", "r'''", "u'''"): - # it is a multi line docstring - cti += 1 - - while cti < len(contextLines) and \ - not contextLines[cti].strip().endswith(('"""', "'''")): - cti += 1 - end = cti - if cti >= len(contextLines) - 1: - return - - if isClassContext: - if not contextLines[start - 1].strip(): - self.__error(docstringContext.start(), 0, "D242") - if not contextLines[end + 1].strip(): - self.__error(docstringContext.end(), 0, "D243") - else: - if not contextLines[start - 1].strip(): - self.__error(docstringContext.start(), 0, "D244") - if not contextLines[end + 1].strip(): - self.__error(docstringContext.end(), 0, "D245") - - def __checkEricNBlankAfterLastParagraph(self, docstringContext, context): - """ - Private method to check, that the last paragraph of docstrings is - not followed by a blank line. - - @param docstringContext docstring context (Pep257Context) - @param context context of the docstring (Pep257Context) - """ - if docstringContext is None: - return - - docstrings = docstringContext.source() - if len(docstrings) <= 3: - # correct/invalid one-liner - return - - if not docstrings[-2].strip(): - self.__error(docstringContext.end(), 0, "D247")
--- a/Plugins/CheckerPlugins/Pep8/Pep8Checker.py Sun Sep 29 19:24:27 2013 +0200 +++ b/Plugins/CheckerPlugins/Pep8/Pep8Checker.py Mon Sep 30 19:06:37 2013 +0200 @@ -13,7 +13,7 @@ from . import pep8 from .Pep8NamingChecker import Pep8NamingChecker -from .Pep257Checker import Pep257Checker +from .DocStyleChecker import DocStyleChecker import Preferences import Utilities @@ -113,8 +113,8 @@ if code in Pep8NamingChecker.Codes: text = Pep8NamingChecker.getMessage(code, *args) - elif code in Pep257Checker.Codes: - text = Pep257Checker.getMessage(code, *args) + elif code in DocStyleChecker.Codes: + text = DocStyleChecker.getMessage(code, *args) else: text = pep8.getMessage(code, *args) self.errors.append((fname, lineno, position, text))
--- a/Plugins/CheckerPlugins/Pep8/Pep8CodeSelectionDialog.py Sun Sep 29 19:24:27 2013 +0200 +++ b/Plugins/CheckerPlugins/Pep8/Pep8CodeSelectionDialog.py Mon Sep 30 19:06:37 2013 +0200 @@ -12,7 +12,7 @@ from . import pep8 from .Pep8NamingChecker import Pep8NamingChecker -from .Pep257Checker import Pep257Checker +from .DocStyleChecker import DocStyleChecker from .Ui_Pep8CodeSelectionDialog import Ui_Pep8CodeSelectionDialog @@ -43,7 +43,7 @@ else: selectableCodes = list(pep8.pep8_messages.keys()) selectableCodes.extend(Pep8NamingChecker.Messages.keys()) - selectableCodes.extend(Pep257Checker.Messages.keys()) + selectableCodes.extend(DocStyleChecker.Messages.keys()) for code in sorted(selectableCodes): if code in pep8.pep8_messages_sample_args: message = QCoreApplication.translate( @@ -56,9 +56,9 @@ message = QCoreApplication.translate( "Pep8NamingChecker", Pep8NamingChecker.Messages[code]) - elif code in Pep257Checker.Messages: + elif code in DocStyleChecker.Messages: message = QCoreApplication.translate( - "Pep257Checker", Pep257Checker.Messages[code]) + "DocStyleChecker", DocStyleChecker.Messages[code]) else: continue itm = QTreeWidgetItem(self.codeTable, [code, message])
--- a/Plugins/CheckerPlugins/Pep8/Pep8Dialog.py Sun Sep 29 19:24:27 2013 +0200 +++ b/Plugins/CheckerPlugins/Pep8/Pep8Dialog.py Mon Sep 30 19:06:37 2013 +0200 @@ -28,7 +28,7 @@ # register the name checker pep8.register_check(Pep8NamingChecker, Pep8NamingChecker.Codes) -from .Pep257Checker import Pep257Checker +from .DocStyleChecker import DocStyleChecker class Pep8Report(pep8.BaseReport): @@ -456,7 +456,7 @@ stats.update(report.counters) # check PEP-257 - pep257Checker = Pep257Checker( + pep257Checker = DocStyleChecker( source, file, select, ignore, [], repeatMessages, maxLineLength=maxLineLength, docType=docType) pep257Checker.run()
--- a/Plugins/CheckerPlugins/Pep8/Pep8StatisticsDialog.py Sun Sep 29 19:24:27 2013 +0200 +++ b/Plugins/CheckerPlugins/Pep8/Pep8StatisticsDialog.py Mon Sep 30 19:06:37 2013 +0200 @@ -13,7 +13,7 @@ from . import pep8 from .Pep8NamingChecker import Pep8NamingChecker -from .Pep257Checker import Pep257Checker +from .DocStyleChecker import DocStyleChecker from .Ui_Pep8StatisticsDialog import Ui_Pep8StatisticsDialog @@ -56,9 +56,9 @@ elif code in Pep8NamingChecker.Messages: message = QCoreApplication.translate( "Pep8NamingChecker", Pep8NamingChecker.Messages[code]) - elif code in Pep257Checker.Messages: + elif code in DocStyleChecker.Messages: message = QCoreApplication.translate( - "Pep257Checker", Pep257Checker.Messages[code]) + "DocStyleChecker", DocStyleChecker.Messages[code]) else: continue self.__createItem(stats[code], code, message)
--- a/eric5.e4p Sun Sep 29 19:24:27 2013 +0200 +++ b/eric5.e4p Mon Sep 30 19:06:37 2013 +0200 @@ -1108,8 +1108,8 @@ <Source>Plugins/VcsPlugins/vcsMercurial/HgArchiveDialog.py</Source> <Source>Plugins/CheckerPlugins/Pep8/Pep8NamingChecker.py</Source> <Source>UtilitiesPython2/Pep8NamingCheckerPy2.py</Source> - <Source>Plugins/CheckerPlugins/Pep8/Pep257Checker.py</Source> <Source>UtilitiesPython2/Pep257CheckerPy2.py</Source> + <Source>Plugins/CheckerPlugins/Pep8/DocStyleChecker.py</Source> </Sources> <Forms> <Form>PyUnit/UnittestDialog.ui</Form>
