Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified	Actions
📁 ..	-	2026-03-27 02:38
📄 __init__.py from ._version import __version__ # Temporary hotfix for flake8-docstrings from .checker import ConventionChecker, check from .parser import AllError from .violations import Error, conventions	194 B	2026-01-20 12:58
📄 __main__.py #! /usr/bin/env python """Static analysis tool for checking docstring conventions and style. The repository is located at: http://github.com/PyCQA/pydocstyle """ __all__ = () def main() -> None: from pydocstyle import cli cli.main() if __name__ == '__main__': main()	288 B	2026-01-20 12:58
📁 __pycache__	-	2026-03-21 15:45
📄 _version.py import sys if sys.version_info[:2] >= (3, 8): from importlib import metadata else: import importlib_metadata as metadata # pragma: no cover # Used to automatically set version number from github actions # as well as not break when being tested locally try: __version__ = metadata.version(__package__) except metadata.PackageNotFoundError: # pragma: no cover __version__ = "0.0.0"	400 B	2026-01-20 12:58
📄 checker.py """Parsed source code checkers for docstring violations.""" import ast import string import tokenize as tk from collections import namedtuple from itertools import chain, takewhile from re import compile as re from textwrap import dedent from . import violations from .config import IllegalConfiguration from .parser import ( AllError, Class, Definition, Function, Method, Module, NestedClass, NestedFunction, Package, ParseError, Parser, StringIO, ) from .utils import ( common_prefix_length, is_blank, log, pairwise, strip_non_alphanumeric, ) from .wordlists import IMPERATIVE_BLACKLIST, IMPERATIVE_VERBS, stem __all__ = ('check',) def check_for(kind, terminal=False): def decorator(f): f._check_for = kind f._terminal = terminal return f return decorator class ConventionChecker: """Checker for PEP 257, NumPy and Google conventions. D10x: Missing docstrings D20x: Whitespace issues D30x: Docstring formatting D40x: Docstring content issues """ NUMPY_SECTION_NAMES = ( 'Short Summary', 'Extended Summary', 'Parameters', 'Returns', 'Yields', 'Other Parameters', 'Raises', 'See Also', 'Notes', 'References', 'Examples', 'Attributes', 'Methods', ) GOOGLE_SECTION_NAMES = ( 'Args', 'Arguments', 'Attention', 'Attributes', 'Caution', 'Danger', 'Error', 'Example', 'Examples', 'Hint', 'Important', 'Keyword Args', 'Keyword Arguments', 'Methods', 'Note', 'Notes', 'Return', 'Returns', 'Raises', 'References', 'See Also', 'Tip', 'Todo', 'Warning', 'Warnings', 'Warns', 'Yield', 'Yields', ) # Examples that will be matched - # " random: Test" where random will be captured as the param # " random : test" where random will be captured as the param # " random_t (Test) : test " where random_t will be captured as the param # Matches anything that fulfills all the following conditions: GOOGLE_ARGS_REGEX = re( # Begins with 0 or more whitespace characters r"^\s" # Followed by 1 or more unicode chars, numbers or underscores # The above is captured as the first group as this is the paramater name. r"(\w+)" # Followed by 0 or more whitespace characters r"\s" # Matches patterns contained within round brackets. # The `.?`matches any sequence of characters in a non-greedy # way (denoted by the `?`) r"(\(.?\))?" # Followed by 0 or more whitespace chars r"\s" # Followed by a colon r":" # Might have a new line and leading whitespace r"\n?\s" # Followed by 1 or more characters - which is the docstring for the parameter ".+" ) def check_source( self, source, filename, ignore_decorators=None, property_decorators=None, ignore_inline_noqa=False, ignore_self_only_init=False, ): self.property_decorators = ( {} if property_decorators is None else property_decorators ) self.ignore_self_only_init = ignore_self_only_init module = parse(StringIO(source), filename) for definition in module: for this_check in self.checks: terminate = False if isinstance(definition, this_check._check_for): skipping_all = definition.skipped_error_codes == 'all' decorator_skip = ignore_decorators is not None and any( len(ignore_decorators.findall(dec.name)) > 0 for dec in definition.decorators ) if ( ignore_inline_noqa or not skipping_all ) and not decorator_skip: error = this_check( self, definition, definition.docstring ) else: error = None errors = error if hasattr(error, '__iter__') else [error] for error in errors: if error is not None and ( ignore_inline_noqa or error.code not in definition.skipped_error_codes ): partition = this_check.__doc__.partition('.\n') message, _, explanation = partition error.set_context( explanation=explanation, definition=definition ) yield error if this_check._terminal: terminate = True break if terminate: break @property def checks(self): all = [ this_check for this_check in vars(type(self)).values() if hasattr(this_check, '_check_for') ] return sorted(all, key=lambda this_check: not this_check._terminal) @check_for(Definition, terminal=True) def check_docstring_missing(self, definition, docstring): """D10{0,1,2,3}: Public definitions should have docstrings. All modules should normally have docstrings. [...] all functions and classes exported by a module should also have docstrings. Public methods (including the __init__ constructor) should also have docstrings. Note: Public (exported) definitions are either those with names listed in __all__ variable (if present), or those that do not start with a single underscore. """ def method_violation(): if definition.is_magic: return violations.D105() if definition.is_init: if ( self.ignore_self_only_init and len(definition.param_names) == 1 ): return None return violations.D107() if not definition.is_overload: return violations.D102() return None if not docstring and definition.is_public: codes = { Module: violations.D100, Class: violations.D101, NestedClass: violations.D106, Method: method_violation, NestedFunction: violations.D103, Function: ( lambda: violations.D103() if not definition.is_overload else None ), Package: violations.D104, } return codes[type(definition)]() @check_for(Definition, terminal=True) def check_docstring_empty(self, definition, docstring): """D419: Docstring is empty. If the user provided a docstring but it was empty, it is like they never provided one. NOTE: This used to report as D10X errors. """ if docstring and is_blank(ast.literal_eval(docstring)): return violations.D419() @check_for(Definition) def check_one_liners(self, definition, docstring): """D200: One-liner docstrings should fit on one line with quotes. The closing quotes are on the same line as the opening quotes. This looks better for one-liners. """ if docstring: lines = ast.literal_eval(docstring).split('\n') if len(lines) > 1: non_empty_lines = sum(1 for l in lines if not is_blank(l)) if non_empty_lines == 1: return violations.D200(len(lines)) @check_for(Function) def check_no_blank_before(self, function, docstring): # def """D20{1,2}: No blank lines allowed around function/method docstring. There's no blank line either before or after the docstring unless directly followed by an inner function or class. """ if docstring: before, _, after = function.source.partition(docstring) blanks_before = list(map(is_blank, before.split('\n')[:-1])) blanks_after = list(map(is_blank, after.split('\n')[1:])) blanks_before_count = sum(takewhile(bool, reversed(blanks_before))) blanks_after_count = sum(takewhile(bool, blanks_after)) if blanks_before_count != 0: yield violations.D201(blanks_before_count) if not all(blanks_after) and blanks_after_count != 0: # Report a D202 violation if the docstring is followed by a blank line # and the blank line is not itself followed by an inner function or # class. if not ( blanks_after_count == 1 and re(r"\s+(?:(?:class\|def\|async def)\s\|@)").match(after) ): yield violations.D202(blanks_after_count) @check_for(Class) def check_blank_before_after_class(self, class_, docstring): """D20{3,4}: Class docstring should have 1 blank line around them. Insert a blank line before and after all docstrings (one-line or multi-line) that document a class -- generally speaking, the class's methods are separated from each other by a single blank line, and the docstring needs to be offset from the first method by a blank line; for symmetry, put a blank line between the class header and the docstring. """ # NOTE: this gives false-positive in this case # class Foo: # # """Docstring.""" # # # # comment here # def foo(): pass if docstring: before, _, after = class_.source.partition(docstring) blanks_before = list(map(is_blank, before.split('\n')[:-1])) blanks_after = list(map(is_blank, after.split('\n')[1:])) blanks_before_count = sum(takewhile(bool, reversed(blanks_before))) blanks_after_count = sum(takewhile(bool, blanks_after)) if blanks_before_count != 0: yield violations.D211(blanks_before_count) if blanks_before_count != 1: yield violations.D203(blanks_before_count) if not all(blanks_after) and blanks_after_count != 1: yield violations.D204(blanks_after_count) @check_for(Definition) def check_blank_after_summary(self, definition, docstring): """D205: Put one blank line between summary line and description. Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line. """ if docstring: lines = ast.literal_eval(docstring).strip().split('\n') if len(lines) > 1: post_summary_blanks = list(map(is_blank, lines[1:])) blanks_count = sum(takewhile(bool, post_summary_blanks)) if blanks_count != 1: return violations.D205(blanks_count) @staticmethod def _get_docstring_indent(definition, docstring): """Return the indentation of the docstring's opening quotes.""" before_docstring, _, _ = definition.source.partition(docstring) _, _, indent = before_docstring.rpartition('\n') return indent @check_for(Definition) def check_indent(self, definition, docstring): """D20{6,7,8}: The entire docstring should be indented same as code. The entire docstring is indented the same as the quotes at its first line. """ if docstring: indent = self._get_docstring_indent(definition, docstring) lines = docstring.split('\n') if len(lines) > 1: # First line and line continuations need no indent. lines = [ line for i, line in enumerate(lines) if i and not lines[i - 1].endswith('\\') ] indents = [leading_space(l) for l in lines if not is_blank(l)] if set(' \t') == set(''.join(indents) + indent): yield violations.D206() if (len(indents) > 1 and min(indents[:-1]) > indent) or ( len(indents) > 0 and indents[-1] > indent ): yield violations.D208() if len(indents) > 0 and min(indents) < indent: yield violations.D207() @check_for(Definition) def check_newline_after_last_paragraph(self, definition, docstring): """D209: Put multi-line docstring closing quotes on separate line. Unless the entire docstring fits on a line, place the closing quotes on a line by themselves. """ if docstring: lines = [ l for l in ast.literal_eval(docstring).split('\n') if not is_blank(l) ] if len(lines) > 1: if docstring.split("\n")[-1].strip() not in ['"""', "'''"]: return violations.D209() @check_for(Definition) def check_surrounding_whitespaces(self, definition, docstring): """D210: No whitespaces allowed surrounding docstring text.""" if docstring: lines = ast.literal_eval(docstring).split('\n') if ( lines[0].startswith(' ') or len(lines) == 1 and lines[0].endswith(' ') ): return violations.D210() @check_for(Definition) def check_multi_line_summary_start(self, definition, docstring): """D21{2,3}: Multi-line docstring summary style check. A multi-line docstring summary should start either at the first, or separately at the second line of a docstring. """ if docstring: start_triple = [ '"""', "'''", 'u"""', "u'''", 'r"""', "r'''", 'ur"""', "ur'''", ] lines = ast.literal_eval(docstring).split('\n') if len(lines) > 1: first = docstring.split("\n")[0].strip().lower() if first in start_triple: return violations.D212() else: return violations.D213() @check_for(Definition) def check_triple_double_quotes(self, definition, docstring): r'''D300: Use """triple double quotes""". For consistency, always use """triple double quotes""" around docstrings. Use r"""raw triple double quotes""" if you use any backslashes in your docstrings. For Unicode docstrings, use u"""Unicode triple-quoted strings""". Note: Exception to this is made if the docstring contains """ quotes in its body. ''' if docstring: if '"""' in ast.literal_eval(docstring): # Allow ''' quotes if docstring contains """, because # otherwise """ quotes could not be expressed inside # docstring. Not in PEP 257. regex = re(r"[uU]?[rR]?'''[^'].") else: regex = re(r'[uU]?[rR]?"""[^"].') if not regex.match(docstring): illegal_matcher = re(r"""[uU]?[rR]?("+\|'+).""") illegal_quotes = illegal_matcher.match(docstring).group(1) return violations.D300(illegal_quotes) @check_for(Definition) def check_backslashes(self, definition, docstring): r'''D301: Use r""" if any backslashes in a docstring. Use r"""raw triple double quotes""" if you use any backslashes (\) in your docstrings. Exceptions are backslashes for line-continuation and unicode escape sequences \N... and \u... These are considered intended unescaped content in docstrings. ''' # Just check that docstring is raw, check_triple_double_quotes # ensures the correct quotes. if ( docstring and re(r'\\[^\nuN]').search(docstring) and not docstring.startswith(('r', 'ur')) ): return violations.D301() @staticmethod def _check_ends_with(docstring, chars, violation): """First line ends with one of `chars`. First line of the docstring should end with one of the characters in `chars`. `chars` supports either a `str` or an `Iterable[str]`. If the condition is evaluated to be false, it raises `violation`. """ if docstring: summary_line = ast.literal_eval(docstring).strip().split('\n')[0] if not summary_line.endswith(chars): return violation(summary_line[-1]) @check_for(Definition) def check_ends_with_period(self, definition, docstring): """D400: First line should end with a period. The [first line of a] docstring is a phrase ending in a period. """ return self._check_ends_with(docstring, '.', violations.D400) @check_for(Definition) def check_ends_with_punctuation(self, definition, docstring): """D415: should end with proper punctuation. The [first line of a] docstring is a phrase ending in a period, question mark, or exclamation point """ return self._check_ends_with( docstring, ('.', '!', '?'), violations.D415 ) @check_for(Function) def check_imperative_mood(self, function, docstring): # def context """D401: First line should be in imperative mood: 'Do', not 'Does'. [Docstring] prescribes the function or method's effect as a command: ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...". """ if ( docstring and not function.is_test and not function.is_property(self.property_decorators) ): stripped = ast.literal_eval(docstring).strip() if stripped: first_word = strip_non_alphanumeric(stripped.split()[0]) check_word = first_word.lower() if check_word in IMPERATIVE_BLACKLIST: return violations.D401b(first_word) correct_forms = IMPERATIVE_VERBS.get(stem(check_word)) if correct_forms and check_word not in correct_forms: best = max( correct_forms, key=lambda f: common_prefix_length(check_word, f), ) return violations.D401(best.capitalize(), first_word) @check_for(Function) def check_no_signature(self, function, docstring): # def context """D402: First line should not be function's or method's "signature". The one-line docstring should NOT be a "signature" reiterating the function/method parameters (which can be obtained by introspection). """ if docstring: first_line = ast.literal_eval(docstring).strip().split('\n')[0] if function.name + '(' in first_line.replace(' ', ''): return violations.D402() @check_for(Function) def check_capitalized(self, function, docstring): """D403: First word of the first line should be properly capitalized. The [first line of a] docstring is a phrase ending in a period. """ if docstring: first_word = ast.literal_eval(docstring).split()[0] if first_word == first_word.upper(): return for char in first_word: if char not in string.ascii_letters and char != "'": return if first_word != first_word.capitalize(): return violations.D403(first_word.capitalize(), first_word) @check_for(Function) def check_if_needed(self, function, docstring): """D418: Function decorated with @overload shouldn't contain a docstring. Functions that are decorated with @overload are definitions, and are for the benefit of the type checker only, since they will be overwritten by the non-@overload-decorated definition. """ if docstring and function.is_overload: return violations.D418() @check_for(Definition) def check_starts_with_this(self, function, docstring): """D404: First word of the docstring should not be `This`. Docstrings should use short, simple language. They should not begin with "This class is [..]" or "This module contains [..]". """ if not docstring: return stripped = ast.literal_eval(docstring).strip() if not stripped: return first_word = strip_non_alphanumeric(stripped.split()[0]) if first_word.lower() == 'this': return violations.D404() @staticmethod def _is_docstring_section(context): """Check if the suspected context is really a section header. Lets have a look at the following example docstring: '''Title. Some part of the docstring that specifies what the function returns. <----- Not a real section name. It has a suffix and the previous line is not empty and does not end with a punctuation sign. This is another line in the docstring. It describes stuff, but we forgot to add a blank line between it and the section name. Parameters <-- A real section name. The previous line ends with ---------- a period, therefore it is in a new grammatical context. param : int examples : list <------- Not a section - previous line doesn't end A list of examples. with punctuation. notes : list <---------- Not a section - there's text after the A list of notes. colon. Notes: <--- Suspected as a context because there's a suffix to the ----- section, but it's a colon so it's probably a mistake. Bla. ''' To make sure this is really a section we check these conditions: * There's no suffix to the section name or it's just a colon AND * The previous line is empty OR it ends with punctuation. If one of the conditions is true, we will consider the line as a section name. """ section_name_suffix = ( context.line.strip().lstrip(context.section_name.strip()).strip() ) section_suffix_is_only_colon = section_name_suffix == ':' punctuation = [',', ';', '.', '-', '\\', '/', ']', '}', ')'] prev_line_ends_with_punctuation = any( context.previous_line.strip().endswith(x) for x in punctuation ) this_line_looks_like_a_section_name = ( is_blank(section_name_suffix) or section_suffix_is_only_colon ) prev_line_looks_like_end_of_paragraph = ( prev_line_ends_with_punctuation or is_blank(context.previous_line) ) return ( this_line_looks_like_a_section_name and prev_line_looks_like_end_of_paragraph ) @classmethod def _check_blanks_and_section_underline( cls, section_name, context, indentation ): """D4{07,08,09,12,14}, D215: Section underline checks. Check for correct formatting for docstring sections. Checks that: * The line that follows the section name contains dashes (D40{7,8}). * The amount of dashes is equal to the length of the section name (D409). * The section's content does not begin in the line that follows the section header (D412). * The section has no content (D414). * The indentation of the dashed line is equal to the docstring's indentation (D215). """ blank_lines_after_header = 0 for line in context.following_lines: if not is_blank(line): break blank_lines_after_header += 1 else: # There are only blank lines after the header. yield violations.D407(section_name) yield violations.D414(section_name) return non_empty_line = context.following_lines[blank_lines_after_header] dash_line_found = ''.join(set(non_empty_line.strip())) == '-' if not dash_line_found: yield violations.D407(section_name) if blank_lines_after_header > 0: yield violations.D412(section_name) else: if blank_lines_after_header > 0: yield violations.D408(section_name) if non_empty_line.strip() != "-" * len(section_name): yield violations.D409( len(section_name), section_name, len(non_empty_line.strip()), ) if leading_space(non_empty_line) > indentation: yield violations.D215(section_name) line_after_dashes_index = blank_lines_after_header + 1 # If the line index after the dashes is in range (perhaps we have # a header + underline followed by another section header). if line_after_dashes_index < len(context.following_lines): line_after_dashes = context.following_lines[ line_after_dashes_index ] if is_blank(line_after_dashes): rest_of_lines = context.following_lines[ line_after_dashes_index: ] if not is_blank(''.join(rest_of_lines)): yield violations.D412(section_name) else: yield violations.D414(section_name) else: yield violations.D414(section_name) @classmethod def _check_common_section( cls, docstring, definition, context, valid_section_names ): """D4{05,10,11,13}, D214: Section name checks. Check for valid section names. Checks that: * The section name is properly capitalized (D405). * The section is not over-indented (D214). * There's a blank line after the section (D410, D413). * There's a blank line before the section (D411). Also yields all the errors from `_check_blanks_and_section_underline`. """ indentation = cls._get_docstring_indent(definition, docstring) capitalized_section = context.section_name.title() if ( context.section_name not in valid_section_names and capitalized_section in valid_section_names ): yield violations.D405(capitalized_section, context.section_name) if leading_space(context.line) > indentation: yield violations.D214(capitalized_section) if not context.following_lines or not is_blank( context.following_lines[-1] ): if context.is_last_section: yield violations.D413(capitalized_section) else: yield violations.D410(capitalized_section) if not is_blank(context.previous_line): yield violations.D411(capitalized_section) yield from cls._check_blanks_and_section_underline( capitalized_section, context, indentation ) @classmethod def _check_numpy_section(cls, docstring, definition, context): """D406: NumPy-style section name checks. Check for valid section names. Checks that: * The section name has no superfluous suffix to it (D406). Additionally, also yield all violations from `_check_common_section` which are style-agnostic section checks. """ indentation = cls._get_docstring_indent(definition, docstring) capitalized_section = context.section_name.title() yield from cls._check_common_section( docstring, definition, context, cls.NUMPY_SECTION_NAMES ) suffix = context.line.strip().lstrip(context.section_name) if suffix: yield violations.D406(capitalized_section, context.line.strip()) if capitalized_section == "Parameters": yield from cls._check_parameters_section( docstring, definition, context ) @staticmethod def _check_parameters_section(docstring, definition, context): """D417: `Parameters` section check for numpy style. Check for a valid `Parameters` section. Checks that: * The section documents all function arguments (D417) except `self` or `cls` if it is a method. """ docstring_args = set() section_level_indent = leading_space(context.line) # Join line continuations, then resplit by line. content = ( '\n'.join(context.following_lines).replace('\\\n', '').split('\n') ) for current_line, next_line in zip(content, content[1:]): # All parameter definitions in the Numpy parameters # section must be at the same indent level as the section # name. # Also, we ensure that the following line is indented, # and has some string, to ensure that the parameter actually # has a description. # This means, this is a parameter doc with some description if ( (leading_space(current_line) == section_level_indent) and ( len(leading_space(next_line)) > len(leading_space(current_line)) ) and next_line.strip() ): # In case the parameter has type definitions, it # will have a colon if ":" in current_line: parameters, parameter_type = current_line.split(":", 1) # Else, we simply have the list of parameters defined # on the current line. else: parameters = current_line.strip() # Numpy allows grouping of multiple parameters of same # type in the same line. They are comma separated. parameter_list = parameters.split(",") for parameter in parameter_list: docstring_args.add(parameter.strip()) yield from ConventionChecker._check_missing_args( docstring_args, definition ) @staticmethod def _check_args_section(docstring, definition, context): """D417: `Args` section checks. Check for a valid `Args` or `Argument` section. Checks that: * The section documents all function arguments (D417) except `self` or `cls` if it is a method. Documentation for each arg should start at the same indentation level. For example, in this case x and y are distinguishable:: Args: x: Lorem ipsum dolor sit amet y: Ut enim ad minim veniam In the case below, we only recognize x as a documented parameter because the rest of the content is indented as if it belongs to the description for x:: Args: x: Lorem ipsum dolor sit amet y: Ut enim ad minim veniam """ docstring_args = set() # normalize leading whitespace if context.following_lines: # any lines with shorter indent than the first one should be disregarded first_line = context.following_lines[0] leading_whitespaces = first_line[: -len(first_line.lstrip())] args_content = dedent( "\n".join( [ line for line in context.following_lines if line.startswith(leading_whitespaces) or line == "" ] ) ).strip() args_sections = [] for line in args_content.splitlines(keepends=True): if not line[:1].isspace(): # This line is the start of documentation for the next # parameter because it doesn't start with any whitespace. args_sections.append(line) else: # This is a continuation of documentation for the last # parameter because it does start with whitespace. args_sections[-1] += line for section in args_sections: match = ConventionChecker.GOOGLE_ARGS_REGEX.match(section) if match: docstring_args.add(match.group(1)) yield from ConventionChecker._check_missing_args( docstring_args, definition ) @staticmethod def _check_missing_args(docstring_args, definition): """D417: Yield error for missing arguments in docstring. Given a list of arguments found in the docstring and the callable definition, it checks if all the arguments of the callable are present in the docstring, else it yields a D417 with a list of missing arguments. """ if isinstance(definition, Function): function_args = get_function_args(definition.source) # If the method isn't static, then we skip the first # positional argument as it is `cls` or `self` if definition.kind == 'method' and not definition.is_static: function_args = function_args[1:] # Filtering out any arguments prefixed with `_` marking them # as private. function_args = [ arg_name for arg_name in function_args if not is_def_arg_private(arg_name) ] missing_args = set(function_args) - docstring_args if missing_args: yield violations.D417( ", ".join(sorted(missing_args)), definition.name ) @classmethod def _check_google_section(cls, docstring, definition, context): """D416: Google-style section name checks. Check for valid section names. Checks that: * The section does not contain any blank line between its name and content (D412). * The section is not empty (D414). * The section name has colon as a suffix (D416). Additionally, also yield all violations from `_check_common_section` which are style-agnostic section checks. """ capitalized_section = context.section_name.title() yield from cls._check_common_section( docstring, definition, context, cls.GOOGLE_SECTION_NAMES ) suffix = context.line.strip().lstrip(context.section_name) if suffix != ":": yield violations.D416( capitalized_section + ":", context.line.strip() ) if capitalized_section in ("Args", "Arguments"): yield from cls._check_args_section(docstring, definition, context) @staticmethod def _get_section_contexts(lines, valid_section_names): """Generate `SectionContext` objects for valid sections. Given a list of `valid_section_names`, generate an `Iterable[SectionContext]` which provides: * Section Name * String value of the previous line * The section line * Following lines till the next section * Line index of the beginning of the section in the docstring * Boolean indicating whether the section is the last section. for each valid section. """ lower_section_names = [s.lower() for s in valid_section_names] def _suspected_as_section(_line): result = get_leading_words(_line.lower()) return result in lower_section_names # Finding our suspects. suspected_section_indices = [ i for i, line in enumerate(lines) if _suspected_as_section(line) ] SectionContext = namedtuple( 'SectionContext', ( 'section_name', 'previous_line', 'line', 'following_lines', 'original_index', 'is_last_section', ), ) # First - create a list of possible contexts. Note that the # `following_lines` member is until the end of the docstring. contexts = ( SectionContext( get_leading_words(lines[i].strip()), lines[i - 1], lines[i], lines[i + 1 :], i, False, ) for i in suspected_section_indices ) # Now that we have manageable objects - rule out false positives. contexts = ( c for c in contexts if ConventionChecker._is_docstring_section(c) ) # Now we shall trim the `following lines` field to only reach the # next section name. for a, b in pairwise(contexts, None): end = -1 if b is None else b.original_index yield SectionContext( a.section_name, a.previous_line, a.line, lines[a.original_index + 1 : end], a.original_index, b is None, ) def _check_numpy_sections(self, lines, definition, docstring): """NumPy-style docstring sections checks. Check the general format of a sectioned docstring: '''This is my one-liner. Short Summary ------------- This is my summary. Returns ------- None. ''' Section names appear in `NUMPY_SECTION_NAMES`. Yields all violation from `_check_numpy_section` for each valid Numpy-style section. """ found_any_numpy_section = False for ctx in self._get_section_contexts(lines, self.NUMPY_SECTION_NAMES): found_any_numpy_section = True yield from self._check_numpy_section(docstring, definition, ctx) return found_any_numpy_section def _check_google_sections(self, lines, definition, docstring): """Google-style docstring section checks. Check the general format of a sectioned docstring: '''This is my one-liner. Note: This is my summary. Returns: None. ''' Section names appear in `GOOGLE_SECTION_NAMES`. Yields all violation from `_check_google_section` for each valid Google-style section. """ for ctx in self._get_section_contexts( lines, self.GOOGLE_SECTION_NAMES ): yield from self._check_google_section(docstring, definition, ctx) @check_for(Definition) def check_docstring_sections(self, definition, docstring): """Check for docstring sections.""" if not docstring: return lines = docstring.split("\n") if len(lines) < 2: return found_numpy = yield from self._check_numpy_sections( lines, definition, docstring ) if not found_numpy: yield from self._check_google_sections( lines, definition, docstring ) parse = Parser() def check( filenames, select=None, ignore=None, ignore_decorators=None, property_decorators=None, ignore_inline_noqa=False, ignore_self_only_init=False, ): """Generate docstring errors that exist in `filenames` iterable. By default, the PEP-257 convention is checked. To specifically define the set of error codes to check for, supply either `select` or `ignore` (but not both). In either case, the parameter should be a collection of error code strings, e.g., {'D100', 'D404'}. When supplying `select`, only specified error codes will be reported. When supplying `ignore`, all error codes which were not specified will be reported. Note that ignored error code refer to the entire set of possible error codes, which is larger than just the PEP-257 convention. To your convenience, you may use `pydocstyle.violations.conventions.pep257` as a base set to add or remove errors from. `ignore_inline_noqa` controls if `# noqa` comments are respected or not. `ignore_self_only_init` controls if D107 is reported on __init__ only containing `self`. Examples --------- >>> check(['pydocstyle.py']) <generator object check at 0x...> >>> check(['pydocstyle.py'], select=['D100']) <generator object check at 0x...> >>> check(['pydocstyle.py'], ignore=conventions.pep257 - {'D100'}) <generator object check at 0x...> """ if select is not None and ignore is not None: raise IllegalConfiguration( 'Cannot pass both select and ignore. ' 'They are mutually exclusive.' ) elif select is not None: checked_codes = select elif ignore is not None: checked_codes = list( set(violations.ErrorRegistry.get_error_codes()) - set(ignore) ) else: checked_codes = violations.conventions.pep257 for filename in filenames: log.info('Checking file %s.', filename) try: with tk.open(filename) as file: source = file.read() for error in ConventionChecker().check_source( source, filename, ignore_decorators, property_decorators, ignore_inline_noqa, ignore_self_only_init, ): code = getattr(error, 'code', None) if code in checked_codes: yield error except (OSError, AllError, ParseError) as error: log.warning('Error in file %s: %s', filename, error) yield error except tk.TokenError: yield SyntaxError('invalid syntax in file %s' % filename) def is_ascii(string): """Return a boolean indicating if `string` only has ascii characters.""" return all(ord(char) < 128 for char in string) def leading_space(string): """Return any leading space from `string`.""" return re(r'\s*').match(string).group() def get_leading_words(line): """Return any leading set of words from `line`. For example, if `line` is " Hello world!!!", returns "Hello world". """ result = re(r"[\w ]+").match(line.strip()) if result is not None: return result.group() def is_def_arg_private(arg_name): """Return a boolean indicating if the argument name is private.""" return arg_name.startswith("_") def get_function_args(function_source): """Return the function arguments given the source-code string.""" # We are stripping the whitespace from the left of the # function source. # This is so that if the docstring has incorrectly # indented lines, which are at a lower indent than the # function source, we still dedent the source correctly # and the AST parser doesn't throw an error. try: function_arg_node = ast.parse(function_source.lstrip()).body[0].args except SyntaxError: # If we still get a syntax error, we don't want the # the checker to crash. Instead we just return a blank list. return [] arg_nodes = function_arg_node.args kwonly_arg_nodes = function_arg_node.kwonlyargs return [arg_node.arg for arg_node in chain(arg_nodes, kwonly_arg_nodes)]	43.83 KB	2026-01-20 12:58
📄 cli.py """Command line interface for pydocstyle.""" import logging import sys from .checker import check from .config import ConfigurationParser, IllegalConfiguration from .utils import log from .violations import Error __all__ = ('main',) class ReturnCode: no_violations_found = 0 violations_found = 1 invalid_options = 2 def run_pydocstyle(): log.setLevel(logging.DEBUG) conf = ConfigurationParser() setup_stream_handlers(conf.get_default_run_configuration()) try: conf.parse() except IllegalConfiguration: return ReturnCode.invalid_options run_conf = conf.get_user_run_configuration() # Reset the logger according to the command line arguments setup_stream_handlers(run_conf) log.debug("starting in debug mode.") Error.explain = run_conf.explain Error.source = run_conf.source errors = [] try: for ( filename, checked_codes, ignore_decorators, property_decorators, ignore_self_only_init, ) in conf.get_files_to_check(): errors.extend( check( (filename,), select=checked_codes, ignore_decorators=ignore_decorators, property_decorators=property_decorators, ignore_self_only_init=ignore_self_only_init, ) ) except IllegalConfiguration as error: # An illegal configuration file was found during file generation. log.error(error.args[0]) return ReturnCode.invalid_options count = 0 for error in errors: # type: ignore if hasattr(error, 'code'): sys.stdout.write('%s\n' % error) count += 1 if count == 0: exit_code = ReturnCode.no_violations_found else: exit_code = ReturnCode.violations_found if run_conf.count: print(count) return exit_code def main(): """Run pydocstyle as a script.""" try: sys.exit(run_pydocstyle()) except KeyboardInterrupt: pass def setup_stream_handlers(conf): """Set up logging stream handlers according to the options.""" class StdoutFilter(logging.Filter): def filter(self, record): return record.levelno in (logging.DEBUG, logging.INFO) log.handlers = [] stdout_handler = logging.StreamHandler(sys.stdout) stdout_handler.setLevel(logging.WARNING) stdout_handler.addFilter(StdoutFilter()) if conf.debug: stdout_handler.setLevel(logging.DEBUG) elif conf.verbose: stdout_handler.setLevel(logging.INFO) else: stdout_handler.setLevel(logging.WARNING) log.addHandler(stdout_handler) stderr_handler = logging.StreamHandler(sys.stderr) msg_format = "%(levelname)s: %(message)s" stderr_handler.setFormatter(logging.Formatter(fmt=msg_format)) stderr_handler.setLevel(logging.WARNING) log.addHandler(stderr_handler)	2.92 KB	2026-01-20 12:58
📄 config.py """Configuration file parsing and utilities.""" import copy import itertools import operator import os import sys from collections import namedtuple from collections.abc import Set from configparser import NoOptionError, NoSectionError, RawConfigParser from functools import reduce from re import compile as re from ._version import __version__ from .utils import log from .violations import ErrorRegistry, conventions if sys.version_info >= (3, 11): import tomllib else: try: import tomli as tomllib except ImportError: # pragma: no cover tomllib = None # type: ignore def check_initialized(method): """Check that the configuration object was initialized.""" def _decorator(self, args, kwargs): if self._arguments is None or self._options is None: raise RuntimeError('using an uninitialized configuration') return method(self, args, *kwargs) return _decorator class TomlParser: """ConfigParser that partially mimics RawConfigParser but for toml files. See RawConfigParser for more info. Also, please note that not all RawConfigParser functionality is implemented, but only the subset that is currently used by pydocstyle. """ def __init__(self): """Create a toml parser.""" self._config = {} def read(self, filenames, encoding=None): """Read and parse a filename or an iterable of filenames. Files that cannot be opened are silently ignored; this is designed so that you can specify an iterable of potential configuration file locations (e.g. current directory, user's home directory, systemwide directory), and all existing configuration files in the iterable will be read. A single filename may also be given. Return list of successfully read files. """ if isinstance(filenames, (str, bytes, os.PathLike)): filenames = [filenames] read_ok = [] for filename in filenames: try: with open(filename, "rb") as fp: if not tomllib: log.warning( "The %s configuration file was ignored, " "because the `tomli` package is not installed.", filename, ) continue self._config.update(tomllib.load(fp)) except OSError: continue if isinstance(filename, os.PathLike): filename = os.fspath(filename) read_ok.append(filename) return read_ok def _get_section(self, section, allow_none=False): try: current = reduce( operator.getitem, section.split('.'), self._config['tool'], ) except KeyError: current = None if isinstance(current, dict): return current elif allow_none: return None else: raise NoSectionError(section) def has_section(self, section): """Indicate whether the named section is present in the configuration.""" return self._get_section(section, allow_none=True) is not None def options(self, section): """Return a list of option names for the given section name.""" current = self._get_section(section) return list(current.keys()) def get(self, section, option, , _conv=None): """Get an option value for a given section.""" d = self._get_section(section) option = option.lower() try: value = d[option] except KeyError: raise NoOptionError(option, section) if isinstance(value, dict): raise TypeError( f"Expected {section}.{option} to be an option, not a section." ) # toml should convert types automatically # don't manually convert, just check, that the type is correct if _conv is not None and not isinstance(value, _conv): raise TypeError( f"The type of {section}.{option} should be {_conv}" ) return value def getboolean(self, section, option): """Get a boolean option value for a given section.""" return self.get(section, option, _conv=bool) def getint(self, section, option): """Get an integer option value for a given section.""" return self.get(section, option, _conv=int) class ConfigurationParser: """Responsible for parsing configuration from files and CLI. There are 2 types of configurations: Run configurations and Check configurations. Run Configurations: ------------------ Responsible for deciding things that are related to the user interface and configuration discovery, e.g. verbosity, debug options, etc. All run configurations default to `False` or `None` and are decided only by CLI. Check Configurations: -------------------- Configurations that are related to which files and errors will be checked. These are configurable in 2 ways: using the CLI, and using configuration files. Configuration files are nested within the file system, meaning that the closer a configuration file is to a checked file, the more relevant it will be. For instance, imagine this directory structure: A +-- tox.ini: sets `select=D100` +-- B +-- foo.py +-- tox.ini: sets `add-ignore=D100` Then `foo.py` will not be checked for `D100`. The configuration build algorithm is described in `self._get_config`. Note: If any of `BASE_ERROR_SELECTION_OPTIONS` was selected in the CLI, all configuration files will be ignored and each file will be checked for the error codes supplied in the CLI. """ CONFIG_FILE_OPTIONS = ( 'convention', 'select', 'ignore', 'add-select', 'add-ignore', 'match', 'match-dir', 'ignore-decorators', 'ignore-self-only-init', ) BASE_ERROR_SELECTION_OPTIONS = ('ignore', 'select', 'convention') DEFAULT_MATCH_RE = r'(?!test_).\.py' DEFAULT_MATCH_DIR_RE = r'[^\.].' DEFAULT_IGNORE_DECORATORS_RE = '' DEFAULT_PROPERTY_DECORATORS = ( "property,cached_property,functools.cached_property" ) DEFAULT_CONVENTION = conventions.pep257 DEFAULT_IGNORE_SELF_ONLY_INIT = False PROJECT_CONFIG_FILES = ( 'setup.cfg', 'tox.ini', '.pydocstyle', '.pydocstyle.ini', '.pydocstylerc', '.pydocstylerc.ini', 'pyproject.toml', # The following is deprecated, but remains for backwards compatibility. '.pep257', ) POSSIBLE_SECTION_NAMES = ('pydocstyle', 'pep257') def __init__(self): """Create a configuration parser.""" self._cache = {} self._override_by_cli = None self._options = self._arguments = self._run_conf = None self._parser = self._create_option_parser() # ---------------------------- Public Methods ----------------------------- def get_default_run_configuration(self): """Return a `RunConfiguration` object set with default values.""" options, _ = self._parse_args([]) return self._create_run_config(options) def parse(self): """Parse the configuration. If one of `BASE_ERROR_SELECTION_OPTIONS` was selected, overrides all error codes to check and disregards any error code related configurations from the configuration files. """ self._options, self._arguments = self._parse_args() self._arguments = self._arguments or ['.'] if not self._validate_options(self._options): raise IllegalConfiguration() self._run_conf = self._create_run_config(self._options) config = self._create_check_config(self._options, use_defaults=False) self._override_by_cli = config @check_initialized def get_user_run_configuration(self): """Return the run configuration for the script.""" return self._run_conf @check_initialized def get_files_to_check(self): """Generate files and error codes to check on each one. Walk dir trees under `self._arguments` and yield file names that `match` under each directory that `match_dir`. The method locates the configuration for each file name and yields a tuple of (filename, [error_codes]). With every discovery of a new configuration file `IllegalConfiguration` might be raised. """ def _get_matches(conf): """Return the `match` and `match_dir` functions for `config`.""" match_func = re(conf.match + '$').match match_dir_func = re(conf.match_dir + '$').match return match_func, match_dir_func def _get_ignore_decorators(conf): """Return the `ignore_decorators` as None or regex.""" return ( re(conf.ignore_decorators) if conf.ignore_decorators else None ) def _get_property_decorators(conf): """Return the `property_decorators` as None or set.""" return ( set(conf.property_decorators.split(",")) if conf.property_decorators else None ) for name in self._arguments: if os.path.isdir(name): for root, dirs, filenames in os.walk(name): config = self._get_config(os.path.abspath(root)) match, match_dir = _get_matches(config) ignore_decorators = _get_ignore_decorators(config) property_decorators = _get_property_decorators(config) # Skip any dirs that do not match match_dir dirs[:] = [d for d in dirs if match_dir(d)] for filename in map(os.path.basename, filenames): if match(filename): full_path = os.path.join(root, filename) yield ( full_path, list(config.checked_codes), ignore_decorators, property_decorators, config.ignore_self_only_init, ) else: config = self._get_config(os.path.abspath(name)) match, _ = _get_matches(config) ignore_decorators = _get_ignore_decorators(config) property_decorators = _get_property_decorators(config) if match(os.path.basename(name)): yield ( name, list(config.checked_codes), ignore_decorators, property_decorators, config.ignore_self_only_init, ) # --------------------------- Private Methods ----------------------------- def _get_config_by_discovery(self, node): """Get a configuration for checking `node` by config discovery. Config discovery happens when no explicit config file is specified. The file system is searched for config files starting from the directory containing the file being checked, and up until the root directory of the project. See `_get_config` for further details. """ path = self._get_node_dir(node) if path in self._cache: return self._cache[path] config_file = self._get_config_file_in_folder(path) if config_file is None: parent_dir, tail = os.path.split(path) if tail: # No configuration file, simply take the parent's. config = self._get_config(parent_dir) else: # There's no configuration file and no parent directory. # Use the default configuration or the one given in the CLI. config = self._create_check_config(self._options) else: # There's a config file! Read it and merge if necessary. options, inherit = self._read_configuration_file(config_file) parent_dir, tail = os.path.split(path) if tail and inherit: # There is a parent dir and we should try to merge. parent_config = self._get_config(parent_dir) config = self._merge_configuration(parent_config, options) else: # No need to merge or parent dir does not exist. config = self._create_check_config(options) return config def _get_config(self, node): """Get and cache the run configuration for `node`. If no configuration exists (not local and not for the parent node), returns and caches a default configuration. The algorithm: ------------- * If the current directory's configuration exists in `self._cache` - return it. * If a configuration file does not exist in this directory: * If the directory is not a root directory: * Cache its configuration as this directory's and return it. * Else: * Cache a default configuration and return it. * Else: * Read the configuration file. * If a parent directory exists AND the configuration file allows inheritance: * Read the parent configuration by calling this function with the parent directory as `node`. * Merge the parent configuration with the current one and cache it. * If the user has specified one of `BASE_ERROR_SELECTION_OPTIONS` in the CLI - return the CLI configuration with the configuration match clauses * Set the `--add-select` and `--add-ignore` CLI configurations. """ if self._run_conf.config is None: log.debug('No config file specified, discovering.') config = self._get_config_by_discovery(node) else: log.debug('Using config file %r', self._run_conf.config) if not os.path.exists(self._run_conf.config): raise IllegalConfiguration( 'Configuration file {!r} specified ' 'via --config was not found.'.format(self._run_conf.config) ) if None in self._cache: return self._cache[None] options, _ = self._read_configuration_file(self._run_conf.config) if options is None: log.warning( 'Configuration file does not contain a ' 'pydocstyle section. Using default configuration.' ) config = self._create_check_config(self._options) else: config = self._create_check_config(options) # Make the CLI always win final_config = {} for attr in CheckConfiguration._fields: cli_val = getattr(self._override_by_cli, attr) conf_val = getattr(config, attr) final_config[attr] = cli_val if cli_val is not None else conf_val config = CheckConfiguration(final_config) self._set_add_options(config.checked_codes, self._options) # Handle caching if self._run_conf.config is not None: self._cache[None] = config else: self._cache[self._get_node_dir(node)] = config return config @staticmethod def _get_node_dir(node): """Return the absolute path of the directory of a filesystem node.""" path = os.path.abspath(node) return path if os.path.isdir(path) else os.path.dirname(path) def _read_configuration_file(self, path): """Try to read and parse `path` as a configuration file. If the configurations were illegal (checked with `self._validate_options`), raises `IllegalConfiguration`. Returns (options, should_inherit). """ if path.endswith('.toml'): parser = TomlParser() else: parser = RawConfigParser(inline_comment_prefixes=('#', ';')) options = None should_inherit = True if parser.read(path) and self._get_section_name(parser): all_options = self._parser.option_list[:] for group in self._parser.option_groups: all_options.extend(group.option_list) option_list = {o.dest: o.type or o.action for o in all_options} # First, read the default values new_options, _ = self._parse_args([]) # Second, parse the configuration section_name = self._get_section_name(parser) for opt in parser.options(section_name): if opt == 'inherit': should_inherit = parser.getboolean(section_name, opt) continue if opt.replace('_', '-') not in self.CONFIG_FILE_OPTIONS: log.warning(f"Unknown option '{opt}' ignored") continue normalized_opt = opt.replace('-', '_') opt_type = option_list[normalized_opt] if opt_type in ('int', 'count'): value = parser.getint(section_name, opt) elif opt_type == 'string': value = parser.get(section_name, opt) else: assert opt_type in ('store_true', 'store_false') value = parser.getboolean(section_name, opt) setattr(new_options, normalized_opt, value) # Third, fix the set-options options = self._fix_set_options(new_options) if options is not None: if not self._validate_options(options): raise IllegalConfiguration(f'in file: {path}') return options, should_inherit def _merge_configuration(self, parent_config, child_options): """Merge parent config into the child options. The migration process requires an `options` object for the child in order to distinguish between mutually exclusive codes, add-select and add-ignore error codes. """ # Copy the parent error codes so we won't override them error_codes = copy.deepcopy(parent_config.checked_codes) if self._has_exclusive_option(child_options): error_codes = self._get_exclusive_error_codes(child_options) self._set_add_options(error_codes, child_options) kwargs = dict(checked_codes=error_codes) for key in ( 'match', 'match_dir', 'ignore_decorators', 'property_decorators', 'ignore_self_only_init', ): child_value = getattr(child_options, key) kwargs[key] = ( child_value if child_value is not None else getattr(parent_config, key) ) return CheckConfiguration(kwargs) def _parse_args(self, args=None, values=None): """Parse the options using `self._parser` and reformat the options.""" options, arguments = self._parser.parse_args(args, values) return self._fix_set_options(options), arguments @staticmethod def _create_run_config(options): """Create a `RunConfiguration` object from `options`.""" values = { opt: getattr(options, opt) for opt in RunConfiguration._fields } return RunConfiguration(values) @classmethod def _create_check_config(cls, options, use_defaults=True): """Create a `CheckConfiguration` object from `options`. If `use_defaults`, any of the match options that are `None` will be replaced with their default value and the default convention will be set for the checked codes. """ checked_codes = None if cls._has_exclusive_option(options) or use_defaults: checked_codes = cls._get_checked_errors(options) kwargs = dict(checked_codes=checked_codes) defaults = { 'match': "MATCH_RE", 'match_dir': "MATCH_DIR_RE", 'ignore_decorators': "IGNORE_DECORATORS_RE", 'property_decorators': "PROPERTY_DECORATORS", 'ignore_self_only_init': "IGNORE_SELF_ONLY_INIT", } for key, default in defaults.items(): kwargs[key] = ( getattr(cls, f"DEFAULT_{default}") if getattr(options, key) is None and use_defaults else getattr(options, key) ) return CheckConfiguration(kwargs) @classmethod def _get_section_name(cls, parser): """Parse options from relevant section.""" for section_name in cls.POSSIBLE_SECTION_NAMES: if parser.has_section(section_name): return section_name return None @classmethod def _get_config_file_in_folder(cls, path): """Look for a configuration file in `path`. If exists return its full path, otherwise None. """ if os.path.isfile(path): path = os.path.dirname(path) for fn in cls.PROJECT_CONFIG_FILES: if fn.endswith('.toml'): config = TomlParser() else: config = RawConfigParser(inline_comment_prefixes=('#', ';')) full_path = os.path.join(path, fn) if config.read(full_path) and cls._get_section_name(config): return full_path @classmethod def _get_exclusive_error_codes(cls, options): """Extract the error codes from the selected exclusive option.""" codes = set(ErrorRegistry.get_error_codes()) checked_codes = None if options.ignore is not None: ignored = cls._expand_error_codes(options.ignore) checked_codes = codes - ignored elif options.select is not None: checked_codes = cls._expand_error_codes(options.select) elif options.convention is not None: checked_codes = getattr(conventions, options.convention) # To not override the conventions nor the options - copy them. return copy.deepcopy(checked_codes) @classmethod def _set_add_options(cls, checked_codes, options): """Set `checked_codes` by the `add_ignore` or `add_select` options.""" checked_codes \|= cls._expand_error_codes(options.add_select) checked_codes -= cls._expand_error_codes(options.add_ignore) @staticmethod def _expand_error_codes(code_parts): """Return an expanded set of error codes to ignore.""" codes = set(ErrorRegistry.get_error_codes()) expanded_codes = set() try: for part in code_parts: # Dealing with split-lined configurations; The part might begin # with a whitespace due to the newline character. part = part.strip() if not part: continue codes_to_add = { code for code in codes if code.startswith(part) } if not codes_to_add: log.warning( 'Error code passed is not a prefix of any ' 'known errors: %s', part, ) expanded_codes.update(codes_to_add) except TypeError as e: raise IllegalConfiguration(e) from e return expanded_codes @classmethod def _get_checked_errors(cls, options): """Extract the codes needed to be checked from `options`.""" checked_codes = cls._get_exclusive_error_codes(options) if checked_codes is None: checked_codes = cls.DEFAULT_CONVENTION cls._set_add_options(checked_codes, options) return checked_codes @classmethod def _validate_options(cls, options): """Validate the mutually exclusive options. Return `True` iff only zero or one of `BASE_ERROR_SELECTION_OPTIONS` was selected. """ for opt1, opt2 in itertools.permutations( cls.BASE_ERROR_SELECTION_OPTIONS, 2 ): if getattr(options, opt1) and getattr(options, opt2): log.error( 'Cannot pass both {} and {}. They are ' 'mutually exclusive.'.format(opt1, opt2) ) return False if options.convention and options.convention not in conventions: log.error( "Illegal convention '{}'. Possible conventions: {}".format( options.convention, ', '.join(conventions.keys()) ) ) return False return True @classmethod def _has_exclusive_option(cls, options): """Return `True` iff one or more exclusive options were selected.""" return any( [ getattr(options, opt) is not None for opt in cls.BASE_ERROR_SELECTION_OPTIONS ] ) @classmethod def _fix_set_options(cls, options): """Alter the set options from None/strings to sets in place.""" optional_set_options = ('ignore', 'select') mandatory_set_options = ('add_ignore', 'add_select') def _get_set(value_str): """Split `value_str` by the delimiter `,` and return a set. Removes empty values ('') and strips whitespace. Also expands error code prefixes, to avoid doing this for every file. """ if isinstance(value_str, str): value_str = value_str.split(",") return cls._expand_error_codes( {x.strip() for x in value_str} - {""} ) for opt in optional_set_options: value = getattr(options, opt) if value is not None: setattr(options, opt, _get_set(value)) for opt in mandatory_set_options: value = getattr(options, opt) if value is None: value = '' if not isinstance(value, Set): value = _get_set(value) setattr(options, opt, value) return options @classmethod def _create_option_parser(cls): """Return an option parser to parse the command line arguments.""" from optparse import OptionGroup, OptionParser parser = OptionParser( version=__version__, usage='Usage: pydocstyle [options] [<file\|dir>...]', ) option = parser.add_option # Run configuration options option( '-e', '--explain', action='store_true', default=False, help='show explanation of each error', ) option( '-s', '--source', action='store_true', default=False, help='show source for each error', ) option( '-d', '--debug', action='store_true', default=False, help='print debug information', ) option( '-v', '--verbose', action='store_true', default=False, help='print status information', ) option( '--count', action='store_true', default=False, help='print total number of errors to stdout', ) option( '--config', metavar='<path>', default=None, help='use given config file and disable config discovery', ) parser.add_option_group( OptionGroup( parser, 'Note', 'When using --match, --match-dir or --ignore-decorators consider ' 'whether you should use a single quote (\') or a double quote ("), ' 'depending on your OS, Shell, etc.', ) ) check_group = OptionGroup( parser, 'Error Check Options', 'Only one of --select, --ignore or --convention can be ' 'specified. If none is specified, defaults to ' '`--convention=pep257`. These three options select the "basic ' 'list" of error codes to check. If you wish to change that list ' '(for example, if you selected a known convention but wish to ' 'ignore a specific error from it or add a new one) you can ' 'use `--add-[ignore/select]` in order to do so.', ) add_check = check_group.add_option # Error check options add_check( '--select', metavar='<codes>', default=None, help='choose the basic list of checked errors by ' 'specifying which errors to check for (with a list of ' 'comma-separated error codes or prefixes). ' 'for example: --select=D101,D2', ) add_check( '--ignore', metavar='<codes>', default=None, help='choose the basic list of checked errors by ' 'specifying which errors to ignore out of all of the ' 'available error codes (with a list of ' 'comma-separated error codes or prefixes). ' 'for example: --ignore=D101,D2', ) add_check( '--convention', metavar='<name>', default=None, help='choose the basic list of checked errors by specifying ' 'an existing convention. Possible conventions: {}.'.format( ', '.join(conventions) ), ) add_check( '--add-select', metavar='<codes>', default=None, help='add extra error codes to check to the basic list of ' 'errors previously set by --select, --ignore or ' '--convention.', ) add_check( '--add-ignore', metavar='<codes>', default=None, help='ignore extra error codes by removing them from the ' 'basic list previously set by --select, --ignore ' 'or --convention.', ) add_check( '--ignore-self-only-init', default=None, action='store_true', help='ignore __init__ methods which only have a self param.', ) parser.add_option_group(check_group) # Match clauses option( '--match', metavar='<pattern>', default=None, help=( "check only files that exactly match <pattern> regular " "expression; default is --match='{}' which matches " "files that don't start with 'test_' but end with " "'.py'" ).format(cls.DEFAULT_MATCH_RE), ) option( '--match-dir', metavar='<pattern>', default=None, help=( "search only dirs that exactly match <pattern> regular " "expression; default is --match-dir='{}', which " "matches all dirs that don't start with " "a dot" ).format(cls.DEFAULT_MATCH_DIR_RE), ) # Decorators option( '--ignore-decorators', metavar='<decorators>', default=None, help=( "ignore any functions or methods that are decorated " "by a function with a name fitting the <decorators> " "regular expression; default is --ignore-decorators='{}'" " which does not ignore any decorated functions.".format( cls.DEFAULT_IGNORE_DECORATORS_RE ) ), ) option( '--property-decorators', metavar='<property-decorators>', default=None, help=( "consider any method decorated with one of these " "decorators as a property, and consequently allow " "a docstring which is not in imperative mood; default " "is --property-decorators='{}'".format( cls.DEFAULT_PROPERTY_DECORATORS ) ), ) return parser # Check configuration - used by the ConfigurationParser class. CheckConfiguration = namedtuple( 'CheckConfiguration', ( 'checked_codes', 'match', 'match_dir', 'ignore_decorators', 'property_decorators', 'ignore_self_only_init', ), ) class IllegalConfiguration(Exception): """An exception for illegal configurations.""" pass # General configurations for pydocstyle run. RunConfiguration = namedtuple( 'RunConfiguration', ('explain', 'source', 'debug', 'verbose', 'count', 'config'), )	32.7 KB	2026-01-20 12:58
📁 data	-	2026-03-21 15:45
📄 parser.py """Python code parser.""" import sys import textwrap import tokenize as tk from io import StringIO from itertools import chain, dropwhile from pathlib import Path from re import compile as re from typing import Tuple from .utils import log __all__ = ( 'Parser', 'Definition', 'Module', 'Package', 'Function', 'NestedFunction', 'Method', 'Class', 'NestedClass', 'AllError', 'StringIO', 'ParseError', ) class ParseError(Exception): """An error parsing contents of a Python file.""" def __str__(self): return "Cannot parse file." class UnexpectedTokenError(ParseError): def __init__(self, token, expected_kind): self.token = token self.expected_kind = expected_kind def __str__(self): return "Unexpected token {}, expected {}".format( self.token, self.expected_kind ) def humanize(string): return re(r'(.)([A-Z]+)').sub(r'\1 \2', string).lower() class Value: """A generic object with a list of preset fields.""" def __init__(self, args): if len(self._fields) != len(args): raise ValueError( 'got {} arguments for {} fields for {}: {}'.format( len(args), len(self._fields), self.__class__.__name__, self._fields, ) ) vars(self).update(zip(self._fields, args)) def __hash__(self): return hash(repr(self)) def __eq__(self, other): return other and vars(self) == vars(other) def __repr__(self): kwargs = ', '.join( '{}={!r}'.format(field, getattr(self, field)) for field in self._fields ) return f'{self.__class__.__name__}({kwargs})' class Definition(Value): """A Python source code definition (could be class, function, etc).""" _fields = ( 'name', '_source', 'start', 'end', 'decorators', 'docstring', 'children', 'callable_args', 'parent', 'skipped_error_codes', ) # type: Tuple[str, ...] _human = property(lambda self: humanize(type(self).__name__)) kind = property(lambda self: self._human.split()[-1]) module = property(lambda self: self.parent.module) dunder_all = property(lambda self: self.module.dunder_all) _slice = property(lambda self: slice(self.start - 1, self.end)) is_class = False def __iter__(self): return chain([self], self.children) @property def error_lineno(self): """Get the line number with which to report violations.""" if isinstance(self.docstring, Docstring): return self.docstring.start return self.start @property def _publicity(self): return {True: 'public', False: 'private'}[self.is_public] @property def source(self): """Return the source code for the definition.""" full_src = self._source[self._slice] def is_empty_or_comment(line): return line.strip() == '' or line.strip().startswith('#') filtered_src = dropwhile(is_empty_or_comment, reversed(full_src)) return ''.join(reversed(list(filtered_src))) def __str__(self): out = f'in {self._publicity} {self._human} `{self.name}`' if self.skipped_error_codes: out += f' (skipping {self.skipped_error_codes})' return out class Module(Definition): """A Python source code module.""" _fields = ( 'name', '_source', 'start', 'end', 'decorators', 'docstring', 'children', 'parent', '_dunder_all', 'dunder_all_error', 'future_imports', 'skipped_error_codes', ) _nest = staticmethod(lambda s: {'def': Function, 'class': Class}[s]) module = property(lambda self: self) dunder_all = property(lambda self: self._dunder_all) @property def is_public(self): """Return True iff the module is considered public. This helps determine if it requires a docstring. """ module_name = Path(self.name).stem return not self._is_inside_private_package() and self._is_public_name( module_name ) def _is_inside_private_package(self): """Return True if the module is inside a private package.""" path = Path(self.name).parent # Ignore the actual module's name. syspath = [Path(p) for p in sys.path] # Convert to pathlib.Path. # Bail if we are at the root directory or in `PYTHONPATH`. while path != path.parent and path not in syspath: if self._is_private_name(path.name): return True path = path.parent return False def _is_public_name(self, module_name): """Determine whether a "module name" (i.e. module or package name) is public.""" return not module_name.startswith('_') or ( module_name.startswith('__') and module_name.endswith('__') ) def _is_private_name(self, module_name): """Determine whether a "module name" (i.e. module or package name) is private.""" return not self._is_public_name(module_name) def __str__(self): return 'at module level' class Package(Module): """A package is a __init__.py module.""" class Function(Definition): """A Python source code function.""" _nest = staticmethod( lambda s: {'def': NestedFunction, 'class': NestedClass}[s] ) @property def is_public(self): """Return True iff this function should be considered public.""" if self.dunder_all is not None: return self.name in self.dunder_all else: return not self.name.startswith('_') @property def is_overload(self): """Return True iff the method decorated with overload.""" return any( decorator.name == "overload" for decorator in self.decorators ) def is_property(self, property_decorator_names): """Return True if the method is decorated with any property decorator.""" return any( decorator.name in property_decorator_names for decorator in self.decorators ) @property def is_test(self): """Return True if this function is a test function/method. We exclude tests from the imperative mood check, because to phrase their docstring in the imperative mood, they would have to start with a highly redundant "Test that ...". """ return self.name.startswith('test') or self.name == 'runTest' @property def param_names(self): """Return the parameter names.""" return self.callable_args class NestedFunction(Function): """A Python source code nested function.""" is_public = False class Method(Function): """A Python source code method.""" @property def is_magic(self): """Return True iff this method is a magic method (e.g., `__str__`).""" return ( self.name.startswith('__') and self.name.endswith('__') and self.name not in VARIADIC_MAGIC_METHODS ) @property def is_init(self): """Return True iff this method is `__init__`.""" return self.name == '__init__' @property def is_public(self): """Return True iff this method should be considered public.""" # Check if we are a setter/deleter method, and mark as private if so. for decorator in self.decorators: # Given 'foo', match 'foo.bar' but not 'foobar' or 'sfoo' if re(fr"^{self.name}\.").match(decorator.name): return False name_is_public = ( not self.name.startswith('_') or self.name in VARIADIC_MAGIC_METHODS or self.is_magic ) return self.parent.is_public and name_is_public @property def is_static(self): """Return True iff the method is static.""" for decorator in self.decorators: if decorator.name == "staticmethod": return True return False class Class(Definition): """A Python source code class.""" _nest = staticmethod(lambda s: {'def': Method, 'class': NestedClass}[s]) is_public = Function.is_public is_class = True class NestedClass(Class): """A Python source code nested class.""" @property def is_public(self): """Return True iff this class should be considered public.""" return ( not self.name.startswith('_') and self.parent.is_class and self.parent.is_public ) class Decorator(Value): """A decorator for function, method or class.""" _fields = 'name arguments'.split() class Docstring(str): """Represent a docstring. This is a string, but has additional start/end attributes representing the start and end of the token. """ def __new__(cls, v, start, end): return str.__new__(cls, v) def __init__(self, v, start, end): self.start = start self.end = end VARIADIC_MAGIC_METHODS = ('__init__', '__call__', '__new__') class AllError(Exception): """Raised when there is a problem with __all__ when parsing.""" def __init__(self, message): """Initialize the error with a more specific message.""" Exception.__init__( self, message + textwrap.dedent( """ That means pydocstyle cannot decide which definitions are public. Variable __all__ should be present at most once in each file, in form `__all__ = ('a_public_function', 'APublicClass', ...)`. More info on __all__: http://stackoverflow.com/q/44834/. ') """ ), ) class TokenStream: # A logical newline is where a new expression or statement begins. When # there is a physical new line, but not a logical one, for example: # (x + # y) # The token will be tk.NL, not tk.NEWLINE. LOGICAL_NEWLINES = {tk.NEWLINE, tk.INDENT, tk.DEDENT} def __init__(self, filelike): self._generator = tk.generate_tokens(filelike.readline) self.current = Token(next(self._generator, None)) self.line = self.current.start[0] self.log = log self.got_logical_newline = True def move(self): previous = self.current current = self._next_from_generator() self.current = None if current is None else Token(current) self.line = self.current.start[0] if self.current else self.line is_logical_blank = previous.kind in (tk.NL, tk.COMMENT) self.got_logical_newline = ( previous.kind in self.LOGICAL_NEWLINES # Retain logical_newline status if last line was logically blank or (self.got_logical_newline and is_logical_blank) ) return previous def _next_from_generator(self): try: return next(self._generator, None) except (SyntaxError, tk.TokenError): self.log.warning('error generating tokens', exc_info=True) return None def __iter__(self): while True: if self.current is not None: yield self.current else: return self.move() class TokenKind(int): def __repr__(self): return "tk.{}".format(tk.tok_name[self]) class Token(Value): _fields = 'kind value start end source'.split() def __init__(self, args): super().__init__(args) self.kind = TokenKind(self.kind) def __str__(self): return f"{self.kind!r} ({self.value})" class Parser: """A Python source code parser.""" def parse(self, filelike, filename): """Parse the given file-like object and return its Module object.""" self.log = log self.source = filelike.readlines() src = ''.join(self.source) try: compile(src, filename, 'exec') except SyntaxError as error: raise ParseError() from error self.stream = TokenStream(StringIO(src)) self.filename = filename self.dunder_all = None self.dunder_all_error = None self.future_imports = set() self._accumulated_decorators = [] return self.parse_module() # TODO: remove def __call__(self, args, kwargs): """Call the parse method.""" return self.parse(args, **kwargs) current = property(lambda self: self.stream.current) line = property(lambda self: self.stream.line) def consume(self, kind): """Consume one token and verify it is of the expected kind.""" next_token = self.stream.move() if next_token.kind != kind: raise UnexpectedTokenError(token=next_token, expected_kind=kind) def leapfrog(self, kind, value=None): """Skip tokens in the stream until a certain token kind is reached. If `value` is specified, tokens whose values are different will also be skipped. """ while self.current is not None: if self.current.kind == kind and ( value is None or self.current.value == value ): self.consume(kind) return self.stream.move() def parse_docstring(self): """Parse a single docstring and return its value.""" self.log.debug("parsing docstring, token is %s", self.current) while self.current.kind in (tk.COMMENT, tk.NEWLINE, tk.NL): self.stream.move() self.log.debug( "parsing docstring, token is %r (%s)", self.current.kind, self.current.value, ) if self.current.kind == tk.STRING: docstring = Docstring( self.current.value, self.current.start[0], self.current.end[0] ) self.stream.move() return docstring return None def parse_decorators(self): """Parse decorators into self._accumulated_decorators. Called after first @ is found. Continue to do so until encountering the 'def' or 'class' start token. """ name = [] arguments = [] at_arguments = False while self.current is not None: self.log.debug( "parsing decorators, current token is %r (%s)", self.current.kind, self.current.value, ) if self.current.kind == tk.NAME and self.current.value in [ 'async', 'def', 'class', ]: # Done with decorators - found function or class proper break elif self.current.kind == tk.OP and self.current.value == '@': # New decorator found. Store the decorator accumulated so far: self._accumulated_decorators.append( Decorator(''.join(name), ''.join(arguments)) ) # Now reset to begin accumulating the new decorator: name = [] arguments = [] at_arguments = False elif self.current.kind == tk.OP and self.current.value == '(': at_arguments = True elif self.current.kind == tk.OP and self.current.value == ')': # Ignore close parenthesis pass elif self.current.kind == tk.NEWLINE or self.current.kind == tk.NL: # Ignore newlines pass else: # Keep accumulating current decorator's name or argument. if not at_arguments: name.append(self.current.value) else: arguments.append(self.current.value) self.stream.move() # Add decorator accumulated so far self._accumulated_decorators.append( Decorator(''.join(name), ''.join(arguments)) ) def parse_definitions(self, class_, dunder_all=False): """Parse multiple definitions and yield them.""" while self.current is not None: self.log.debug( "parsing definition list, current token is %r (%s)", self.current.kind, self.current.value, ) self.log.debug('got_newline: %s', self.stream.got_logical_newline) if dunder_all and self.current.value == '__all__': self.parse_dunder_all() elif ( self.current.kind == tk.OP and self.current.value == '@' and self.stream.got_logical_newline ): self.consume(tk.OP) self.parse_decorators() elif self.current.value in ['def', 'class']: yield self.parse_definition(class_._nest(self.current.value)) elif self.current.kind == tk.INDENT: self.consume(tk.INDENT) yield from self.parse_definitions(class_) elif self.current.kind == tk.DEDENT: self.consume(tk.DEDENT) return elif self.current.value == 'from': self.parse_from_import_statement() else: self.stream.move() def parse_dunder_all(self): """Parse the __all__ definition in a module.""" assert self.current.value == '__all__' self.consume(tk.NAME) # More than one __all__ definition means we ignore all __all__. if self.dunder_all is not None or self.dunder_all_error is not None: self.dunder_all = None self.dunder_all_error = 'Could not evaluate contents of __all__. ' return if self.current.value != '=': self.dunder_all_error = 'Could not evaluate contents of __all__. ' return self.consume(tk.OP) is_surrounded = False if self.current.value in '([': is_surrounded = True self.consume(tk.OP) dunder_all_content = "(" while True: if is_surrounded and self.current.value in ")]": break if self.current.kind in (tk.NEWLINE, tk.ENDMARKER): break if self.current.kind in (tk.NL, tk.COMMENT): pass elif self.current.kind == tk.STRING or self.current.value == ',': dunder_all_content += self.current.value else: self.dunder_all_error = ( 'Could not evaluate contents of __all__.' ) return self.stream.move() if is_surrounded: self.consume(tk.OP) if not is_surrounded and ',' not in dunder_all_content: self.dunder_all_error = ( 'Unexpected token kind in __all__: {!r}. '.format( self.current.kind ) ) return dunder_all_content += ")" try: self.dunder_all = eval(dunder_all_content, {}) except BaseException as e: self.dunder_all_error = ( 'Could not evaluate contents of __all__.' '\bThe value was {}. The exception was:\n{}'.format( dunder_all_content, e ) ) while ( self.current.kind not in self.stream.LOGICAL_NEWLINES and self.current.kind != tk.ENDMARKER ): if self.current.kind != tk.COMMENT: self.dunder_all = None self.dunder_all_error = ( 'Could not evaluate contents of __all__. ' ) return self.stream.move() def parse_module(self): """Parse a module (and its children) and return a Module object.""" self.log.debug("parsing module.") start = self.line skipped_error_codes = self.parse_skip_comment() docstring = self.parse_docstring() children = list(self.parse_definitions(Module, dunder_all=True)) assert self.current is None, self.current end = self.line cls = Module if self.filename.endswith('__init__.py'): cls = Package module = cls( self.filename, self.source, start, end, [], docstring, children, None, self.dunder_all, self.dunder_all_error, None, skipped_error_codes, ) for child in module.children: child.parent = module module.future_imports = self.future_imports self.log.debug("finished parsing module.") return module def parse_definition(self, class_): """Parse a definition and return its value in a `class_` object.""" start = self.line self.consume(tk.NAME) name = self.current.value self.log.debug("parsing %s '%s'", class_.__name__, name) self.stream.move() callable_args = [] if self.current.kind == tk.OP and self.current.value == '(': parenthesis_level = 0 in_default_arg = False while True: if self.current.kind == tk.OP: if self.current.value == '(': parenthesis_level += 1 elif self.current.value == ')': parenthesis_level -= 1 if parenthesis_level == 0: break elif self.current.value == ',': in_default_arg = False elif ( parenthesis_level == 1 and self.current.kind == tk.NAME and not in_default_arg ): callable_args.append(self.current.value) in_default_arg = True self.stream.move() if self.current.kind != tk.OP or self.current.value != ':': self.leapfrog(tk.OP, value=":") else: self.consume(tk.OP) if self.current.kind in (tk.NEWLINE, tk.COMMENT): skipped_error_codes = self.parse_skip_comment() self.leapfrog(tk.INDENT) assert self.current.kind != tk.INDENT docstring = self.parse_docstring() decorators = self._accumulated_decorators self.log.debug("current accumulated decorators: %s", decorators) self._accumulated_decorators = [] self.log.debug("parsing nested definitions.") children = list(self.parse_definitions(class_)) self.log.debug( "finished parsing nested definitions for '%s'", name ) end = self.line - 1 else: # one-liner definition skipped_error_codes = '' docstring = self.parse_docstring() decorators = self._accumulated_decorators self.log.debug("current accumulated decorators: %s", decorators) self._accumulated_decorators = [] children = [] end = self.line self.leapfrog(tk.NEWLINE) definition = class_( name, self.source, start, end, decorators, docstring, children, callable_args, None, # parent skipped_error_codes, ) for child in definition.children: child.parent = definition self.log.debug( "finished parsing %s '%s'. Next token is %r", class_.__name__, name, self.current, ) return definition def parse_skip_comment(self): """Parse a definition comment for noqa skips.""" skipped_error_codes = '' while self.current.kind in (tk.COMMENT, tk.NEWLINE, tk.NL): if self.current.kind == tk.COMMENT: if 'noqa: ' in self.current.value: skipped_error_codes = ''.join( self.current.value.split('noqa: ')[1:] ) elif self.current.value.startswith('# noqa'): skipped_error_codes = 'all' self.stream.move() self.log.debug( "parsing comments before docstring, token is %r (%s)", self.current.kind, self.current.value, ) if skipped_error_codes: break return skipped_error_codes def check_current(self, kind=None, value=None): """Verify the current token is of type `kind` and equals `value`.""" msg = textwrap.dedent( """ Unexpected token at line {self.line}: In file: {self.filename} Got kind {self.current.kind!r} Got value {self.current.value} """.format( self=self ) ) kind_valid = self.current.kind == kind if kind else True value_valid = self.current.value == value if value else True assert kind_valid and value_valid, msg def parse_from_import_statement(self): """Parse a 'from x import y' statement. The purpose is to find __future__ statements. """ self.log.debug('parsing from/import statement.') is_future_import = self._parse_from_import_source() self._parse_from_import_names(is_future_import) def _parse_from_import_source(self): """Parse the 'from x import' part in a 'from x import y' statement. Return true iff `x` is __future__. """ assert self.current.value == 'from', self.current.value self.stream.move() is_future_import = self.current.value == '__future__' self.stream.move() while ( self.current is not None and self.current.kind in (tk.DOT, tk.NAME, tk.OP) and self.current.value != 'import' ): self.stream.move() if self.current is None or self.current.value != 'import': return False self.check_current(value='import') assert self.current.value == 'import', self.current.value self.stream.move() return is_future_import def _parse_from_import_names(self, is_future_import): """Parse the 'y' part in a 'from x import y' statement.""" if self.current.value == '(': self.consume(tk.OP) expected_end_kinds = (tk.OP,) else: expected_end_kinds = (tk.NEWLINE, tk.ENDMARKER) while self.current.kind not in expected_end_kinds and not ( self.current.kind == tk.OP and self.current.value == ';' ): if self.current.kind != tk.NAME: self.stream.move() continue self.log.debug( "parsing import, token is %r (%s)", self.current.kind, self.current.value, ) if is_future_import: self.log.debug('found future import: %s', self.current.value) self.future_imports.add(self.current.value) self.consume(tk.NAME) self.log.debug( "parsing import, token is %r (%s)", self.current.kind, self.current.value, ) if self.current.kind == tk.NAME and self.current.value == 'as': self.consume(tk.NAME) # as if self.current.kind == tk.NAME: self.consume(tk.NAME) # new name, irrelevant if self.current.value == ',': self.consume(tk.OP) self.log.debug( "parsing import, token is %r (%s)", self.current.kind, self.current.value, )	27.63 KB	2026-01-20 12:58
📄 utils.py """General shared utilities.""" import logging import re from itertools import tee, zip_longest from typing import Any, Iterable, Tuple # Do not update the version manually - it is managed by `bumpversion`. log = logging.getLogger(__name__) #: Regular expression for stripping non-alphanumeric characters NON_ALPHANUMERIC_STRIP_RE = re.compile(r'[\W_]+') def is_blank(string: str) -> bool: """Return True iff the string contains only whitespaces.""" return not string.strip() def pairwise( iterable: Iterable, default_value: Any, ) -> Iterable[Tuple[Any, Any]]: """Return pairs of items from `iterable`. pairwise([1, 2, 3], default_value=None) -> (1, 2) (2, 3), (3, None) """ a, b = tee(iterable) _ = next(b, default_value) return zip_longest(a, b, fillvalue=default_value) def common_prefix_length(a: str, b: str) -> int: """Return the length of the longest common prefix of a and b. >>> common_prefix_length('abcd', 'abce') 3 """ for common, (ca, cb) in enumerate(zip(a, b)): if ca != cb: return common return min(len(a), len(b)) def strip_non_alphanumeric(string: str) -> str: """Strip string from any non-alphanumeric characters.""" return NON_ALPHANUMERIC_STRIP_RE.sub('', string)	1.26 KB	2026-01-20 12:58
📄 violations.py """Docstring violation definition.""" from collections import namedtuple from functools import partial from itertools import dropwhile from typing import Any, Callable, Iterable, List, Optional from .parser import Definition from .utils import is_blank __all__ = ('Error', 'ErrorRegistry', 'conventions') ErrorParams = namedtuple('ErrorParams', ['code', 'short_desc', 'context']) class Error: """Error in docstring style.""" # Options that define how errors are printed: explain = False source = False def __init__( self, code: str, short_desc: str, context: str, parameters: Iterable[str], ) -> None: """Initialize the object. `parameters` are specific to the created error. """ self.code = code self.short_desc = short_desc self.context = context self.parameters = parameters self.definition = None # type: Optional[Definition] self.explanation = None # type: Optional[str] def set_context(self, definition: Definition, explanation: str) -> None: """Set the source code context for this error.""" self.definition = definition self.explanation = explanation filename = property(lambda self: self.definition.module.name) line = property(lambda self: self.definition.error_lineno) @property def message(self) -> str: """Return the message to print to the user.""" ret = f'{self.code}: {self.short_desc}' if self.context is not None: specific_error_msg = self.context.format(self.parameters) ret += f' ({specific_error_msg})' return ret @property def lines(self) -> str: """Return the source code lines for this error.""" if self.definition is None: return '' source = '' lines = self.definition.source.splitlines(keepends=True) offset = self.definition.start # type: ignore lines_stripped = list( reversed(list(dropwhile(is_blank, reversed(lines)))) ) numbers_width = len(str(offset + len(lines_stripped))) line_format = f'{{:{numbers_width}}}:{{}}' for n, line in enumerate(lines_stripped): if line: line = ' ' + line source += line_format.format(n + offset, line) if n > 5: source += ' ...\n' break return source def __str__(self) -> str: if self.explanation: self.explanation = '\n'.join( l for l in self.explanation.split('\n') if not is_blank(l) ) template = '{filename}:{line} {definition}:\n {message}' if self.source and self.explain: template += '\n\n{explanation}\n\n{lines}\n' elif self.source and not self.explain: template += '\n\n{lines}\n' elif self.explain and not self.source: template += '\n\n{explanation}\n\n' return template.format( *{ name: getattr(self, name) for name in [ 'filename', 'line', 'definition', 'message', 'explanation', 'lines', ] } ) def __repr__(self) -> str: return str(self) def __lt__(self, other: 'Error') -> bool: return (self.filename, self.line) < (other.filename, other.line) class ErrorRegistry: """A registry of all error codes, divided to groups.""" groups = [] # type: ignore class ErrorGroup: """A group of similarly themed errors.""" def __init__(self, prefix: str, name: str) -> None: """Initialize the object. `Prefix` should be the common prefix for errors in this group, e.g., "D1". `name` is the name of the group (its subject). """ self.prefix = prefix self.name = name self.errors = [] # type: List[ErrorParams] def create_error( self, error_code: str, error_desc: str, error_context: Optional[str] = None, ) -> Callable[[Iterable[str]], Error]: """Create an error, register it to this group and return it.""" # TODO: check prefix error_params = ErrorParams(error_code, error_desc, error_context) factory = partial(Error, error_params) self.errors.append(error_params) return factory @classmethod def create_group(cls, prefix: str, name: str) -> ErrorGroup: """Create a new error group and return it.""" group = cls.ErrorGroup(prefix, name) cls.groups.append(group) return group @classmethod def get_error_codes(cls) -> Iterable[str]: """Yield all registered codes.""" for group in cls.groups: for error in group.errors: yield error.code @classmethod def to_rst(cls) -> str: """Output the registry as reStructuredText, for documentation.""" max_len = max( len(error.short_desc) for group in cls.groups for error in group.errors ) sep_line = '+' + 6 * '-' + '+' + '-' * (max_len + 2) + '+\n' blank_line = '\|' + (max_len + 9) * ' ' + '\|\n' table = '' for group in cls.groups: table += sep_line table += blank_line table += '\|' + f'{group.name}'.center(max_len + 9) + '\|\n' table += blank_line for error in group.errors: table += sep_line table += ( '\|' + error.code.center(6) + '\| ' + error.short_desc.ljust(max_len + 1) + '\|\n' ) table += sep_line return table D1xx = ErrorRegistry.create_group('D1', 'Missing Docstrings') D100 = D1xx.create_error( 'D100', 'Missing docstring in public module', ) D101 = D1xx.create_error( 'D101', 'Missing docstring in public class', ) D102 = D1xx.create_error( 'D102', 'Missing docstring in public method', ) D103 = D1xx.create_error( 'D103', 'Missing docstring in public function', ) D104 = D1xx.create_error( 'D104', 'Missing docstring in public package', ) D105 = D1xx.create_error( 'D105', 'Missing docstring in magic method', ) D106 = D1xx.create_error( 'D106', 'Missing docstring in public nested class', ) D107 = D1xx.create_error( 'D107', 'Missing docstring in __init__', ) D2xx = ErrorRegistry.create_group('D2', 'Whitespace Issues') D200 = D2xx.create_error( 'D200', 'One-line docstring should fit on one line ' 'with quotes', 'found {0}', ) D201 = D2xx.create_error( 'D201', 'No blank lines allowed before function docstring', 'found {0}', ) D202 = D2xx.create_error( 'D202', 'No blank lines allowed after function docstring', 'found {0}', ) D203 = D2xx.create_error( 'D203', '1 blank line required before class docstring', 'found {0}', ) D204 = D2xx.create_error( 'D204', '1 blank line required after class docstring', 'found {0}', ) D205 = D2xx.create_error( 'D205', '1 blank line required between summary line and description', 'found {0}', ) D206 = D2xx.create_error( 'D206', 'Docstring should be indented with spaces, not tabs', ) D207 = D2xx.create_error( 'D207', 'Docstring is under-indented', ) D208 = D2xx.create_error( 'D208', 'Docstring is over-indented', ) D209 = D2xx.create_error( 'D209', 'Multi-line docstring closing quotes should be on a separate line', ) D210 = D2xx.create_error( 'D210', 'No whitespaces allowed surrounding docstring text', ) D211 = D2xx.create_error( 'D211', 'No blank lines allowed before class docstring', 'found {0}', ) D212 = D2xx.create_error( 'D212', 'Multi-line docstring summary should start at the first line', ) D213 = D2xx.create_error( 'D213', 'Multi-line docstring summary should start at the second line', ) D214 = D2xx.create_error( 'D214', 'Section is over-indented', '{0!r}', ) D215 = D2xx.create_error( 'D215', 'Section underline is over-indented', 'in section {0!r}', ) D3xx = ErrorRegistry.create_group('D3', 'Quotes Issues') D300 = D3xx.create_error( 'D300', 'Use """triple double quotes"""', 'found {0}-quotes', ) D301 = D3xx.create_error( 'D301', 'Use r""" if any backslashes in a docstring', ) D302 = D3xx.create_error( 'D302', 'Deprecated: Use u""" for Unicode docstrings', ) D4xx = ErrorRegistry.create_group('D4', 'Docstring Content Issues') D400 = D4xx.create_error( 'D400', 'First line should end with a period', 'not {0!r}', ) D401 = D4xx.create_error( 'D401', 'First line should be in imperative mood', "perhaps '{0}', not '{1}'", ) D401b = D4xx.create_error( 'D401', 'First line should be in imperative mood; try rephrasing', "found '{0}'", ) D402 = D4xx.create_error( 'D402', 'First line should not be the function\'s "signature"', ) D403 = D4xx.create_error( 'D403', 'First word of the first line should be properly capitalized', '{0!r}, not {1!r}', ) D404 = D4xx.create_error( 'D404', 'First word of the docstring should not be `This`', ) D405 = D4xx.create_error( 'D405', 'Section name should be properly capitalized', '{0!r}, not {1!r}', ) D406 = D4xx.create_error( 'D406', 'Section name should end with a newline', '{0!r}, not {1!r}', ) D407 = D4xx.create_error( 'D407', 'Missing dashed underline after section', '{0!r}', ) D408 = D4xx.create_error( 'D408', 'Section underline should be in the line following the section\'s name', '{0!r}', ) D409 = D4xx.create_error( 'D409', 'Section underline should match the length of its name', 'Expected {0!r} dashes in section {1!r}, got {2!r}', ) D410 = D4xx.create_error( 'D410', 'Missing blank line after section', '{0!r}', ) D411 = D4xx.create_error( 'D411', 'Missing blank line before section', '{0!r}', ) D412 = D4xx.create_error( 'D412', 'No blank lines allowed between a section header and its content', '{0!r}', ) D413 = D4xx.create_error( 'D413', 'Missing blank line after last section', '{0!r}', ) D414 = D4xx.create_error( 'D414', 'Section has no content', '{0!r}', ) D415 = D4xx.create_error( 'D415', ( 'First line should end with a period, question ' 'mark, or exclamation point' ), 'not {0!r}', ) D416 = D4xx.create_error( 'D416', 'Section name should end with a colon', '{0!r}, not {1!r}', ) D417 = D4xx.create_error( 'D417', 'Missing argument descriptions in the docstring', 'argument(s) {0} are missing descriptions in {1!r} docstring', ) D418 = D4xx.create_error( 'D418', 'Function/ Method decorated with @overload shouldn\'t contain a docstring', ) D419 = D4xx.create_error( 'D419', 'Docstring is empty', ) class AttrDict(dict): def __getattr__(self, item: str) -> Any: return self[item] all_errors = set(ErrorRegistry.get_error_codes()) conventions = AttrDict( { 'pep257': all_errors - { 'D203', 'D212', 'D213', 'D214', 'D215', 'D404', 'D405', 'D406', 'D407', 'D408', 'D409', 'D410', 'D411', 'D413', 'D415', 'D416', 'D417', 'D418', }, 'numpy': all_errors - { 'D107', 'D203', 'D212', 'D213', 'D402', 'D413', 'D415', 'D416', 'D417', }, 'google': all_errors - { 'D203', 'D204', 'D213', 'D215', 'D400', 'D401', 'D404', 'D406', 'D407', 'D408', 'D409', 'D413', }, } )	12.12 KB	2026-01-20 12:58
📄 wordlists.py """Wordlists loaded from package data. We can treat them as part of the code for the imperative mood check, and therefore we load them at import time, rather than on-demand. """ import pkgutil import re from typing import Dict, Iterator, Set import snowballstemmer #: Regular expression for stripping comments from the wordlists COMMENT_RE = re.compile(r'\s#.') #: Stemmer function for stemming words in English stem = snowballstemmer.stemmer('english').stemWord def load_wordlist(name: str) -> Iterator[str]: """Iterate over lines of a wordlist data file. `name` should be the name of a package data file within the data/ directory. Whitespace and #-prefixed comments are stripped from each line. """ data = pkgutil.get_data('pydocstyle', 'data/' + name) if data is not None: text = data.decode('utf8') for line in text.splitlines(): line = COMMENT_RE.sub('', line).strip() if line: yield line def make_imperative_verbs_dict(wordlist: Iterator[str]) -> Dict[str, Set[str]]: """Create a dictionary mapping stemmed verbs to the imperative form.""" imperative_verbs = {} # type: Dict[str, Set[str]] for word in wordlist: imperative_verbs.setdefault(stem(word), set()).add(word) return imperative_verbs IMPERATIVE_VERBS = make_imperative_verbs_dict(load_wordlist('imperatives.txt')) #: Words that are forbidden to appear as the first word in a docstring IMPERATIVE_BLACKLIST = set(load_wordlist('imperatives_blacklist.txt'))	1.51 KB	2026-01-20 12:58

Terminal