Current File : //opt/cloudlinux/venv/lib/python3.11/site-packages/pydocstyle/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,
)
Mini Shell