pymend package

Subpackages

pymend.docstring_parser package

Submodules

pymend.file_parser module

Module for parsing input file and walking ast.

class pymend.file_parser.AstAnalyzer(file_content: str, *, settings: FixerSettings)[source]

Bases: object

Walk ast and extract module, class and function information.

static func_decorators(node: FunctionDef | AsyncFunctionDef) → Iterator[str][source]: Get the names of the decorators of a function node.

get_docstring_info(node: FunctionDef | AsyncFunctionDef | ClassDef | Module) → DocstringInfo | None[source]

Get docstring and line number if available.

Parameters:: node (NodeOfInterest) – Get general information about the docstring of any node if interest.
Returns:: Information about the docstring if the element contains one. Or None if there was no docstring at all.
Return type:: Optional[DocstringInfo]
Raises:: ValueError – If the first element of the body is not a docstring after ast.get_docstring() returned one.

static get_ids_from_returns(values: list[expr]) → tuple[str, ...][source]

Get the ids/names for all the expressions in the list.

Parameters:: values (list[ast.expr]) – List of expressions to extract the ids from.
Returns:: Tuple of ids of the original expressions.
Return type:: tuple[str, …]

get_padded_args_defaults(func: FunctionDef | AsyncFunctionDef) → list[str | None][source]

Left-Pad the general args defaults to the length of the args.

Parameters:: func (Union[ast.FunctionDef, ast.AsyncFunctionDef]) – Node representing a function definition
Returns:: Left padded (with None) list of function arguments.
Return type:: list[Optional[str]]

get_parameters_sig(func: FunctionDef | AsyncFunctionDef) → list[Parameter][source]

Get information about function parameters.

Parameters:: func (Union[ast.FunctionDef, ast.AsyncFunctionDef]) – Node representing a function definition
Returns:: Parameter information from the function signature.
Return type:: list[Parameter]

get_return_value_sig(func: FunctionDef | AsyncFunctionDef) → ReturnValue[source]

Get information about return value from signature.

Parameters:: func (Union[ast.FunctionDef, ast.AsyncFunctionDef]) – Node representing a function definition
Returns:: Return information extracted from the function signature.
Return type:: ReturnValue

handle_class(cls: ClassDef) → ClassDocstring[source]

Extract information about class docstring.

Parameters:: cls (ast.ClassDef) – Node representing a class definition.
Returns:: Docstring representation for a class.
Return type:: ClassDocstring

handle_class_body(cls: ClassDef) → tuple[list[Parameter], list[str]][source]

Extract attributes and methods from class body.

Will walk the AST of the ClassDef node and add each function encountered as a method.

If the __init__ method is encountered walk its body for attribute definitions.

Parameters:

cls (ast.ClassDef) – Node representing a class definition.

Returns:

attributes (list[Parameter]) – List of the parameters that make up the classes attributes.
methods (list[str]) – List of the method names in the class.

handle_elem_docstring(elem: FunctionDef | AsyncFunctionDef | ClassDef) → DocstringInfo[source]

Extract information about the docstring of the function.

Parameters:

elem (Union[ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef]) – Element representing a function or class definition.

Returns:

Return general information about the docstring of the element.

Return type:

DocstringInfo

Raises:

ValueError – If the element did not have a body at all. This should not happen for valid functions or classes.
ValueError – If the indent of the function body is not one level deeper than the definition.

handle_function(func: FunctionDef | AsyncFunctionDef) → FunctionDocstring[source]

Extract information from signature and docstring.

Parameters:: func (Union[ast.FunctionDef, ast.AsyncFunctionDef]) – Node representing a function definition.
Returns:: Docstring representation of a function.
Return type:: FunctionDocstring

handle_function_body(func: FunctionDef | AsyncFunctionDef) → FunctionBody[source]

Check the function body for yields, raises and value returns.

Parameters:: func (Union[ast.FunctionDef, ast.AsyncFunctionDef]) – Node representing a function definition
Returns:: Information extracted from the function body.
Return type:: FunctionBody

handle_function_signature(func: FunctionDef | AsyncFunctionDef) → FunctionSignature[source]

Extract information about the signature of the function.

Parameters:: func (Union[ast.FunctionDef, ast.AsyncFunctionDef]) – Node representing a function definition
Returns:: Information extracted from the function signature
Return type:: FunctionSignature

handle_module(module: Module) → ModuleDocstring[source]

Extract information about module.

Parameters:: module (ast.Module) – Node representing the full module.
Returns:: Docstring representation for the module.
Return type:: ModuleDocstring

static is_shebang_or_pragma(line: str) → bool[source]

Check if a given line contains encoding or shebang.

Parameters:: line (str) – Line to check
Returns:: Whether the given line contains encoding or shebang
Return type:: bool

parse_from_ast() → list[ModuleDocstring | ClassDocstring | FunctionDocstring][source]

Walk AST of the input file extract info about module, classes and functions.

For the module and classes, the raw docstring and its line numbers are extracted.

For functions the raw docstring and its line numbers are extracted. Additionally the signature is parsed for parameters and return value.

Returns:: List of information about module, classes and functions.
Return type:: list[ElementDocstring]
Raises:: AssertionError – If the source file content could not be parsed into an ast.

class pymend.file_parser.FunctionNodeVisitor(start_node: FunctionDef | AsyncFunctionDef)[source]

Bases: object

Visit all subnodes of the function.

pymend.file_parser.ast_unparse(node: None) → None[source]

pymend.file_parser.ast_unparse(node: AST) → str

Convert the AST node to source code as a string.

Parameters:: node (Optional[ast.AST]) – Node to unparse.
Returns:: None if node was None. Otherwise the unparsed node.
Return type:: Optional[str]

pymend.pymend module

Module for general management of writing docstrings of multiple files.

class pymend.pymend.FileContentRepresentation(lst: list[str], lines: str)[source]

Bases: object

Container for str and list representation of file contents.

lines: str

lst: list[str]

class pymend.pymend.PyComment(input_file: Path, *, fixer_settings: FixerSettings, output_style: DocstringStyle = DocstringStyle.NUMPYDOC, input_style: DocstringStyle = DocstringStyle.AUTO, proceed_directly: bool = True)[source]

Bases: object

Manage several python scripts docstrings.

It is used to parse and rewrite in a Pythonic way all the functions’, methods’ and classes’ docstrings. The changes are then provided in a patch file.

assert_equality(src_lines: str, dst_lines: str) → None[source]

Assert that running pymend does not change functional ast.

Done by comparing the asts for the original and produced outputs while ignoring the docstrings themselves.

Parameters:

src_lines (str) – Lines from the input file.
dst_lines (str) – Lines that pymend produced.

Raises:

AssertionError – If the content of the input file could not be parsed into an ast.
AssertionError – If the output from pymend could not be parsed into an ast.
AssertionError – If the output from pymend produces a different (reduced) ast than the input.

assert_stability(src: list[str], dst: list[str]) → None[source]

Assert that running pymend on its own output does not change anything.

Parameters:

src (list[str]) – List of lines from the input file.
dst (list[str]) – List of lines that pymend produced.

Raises:

AssertionError – If a second run of pymend produces a different output than the first.

dump_to_file(*output: str, ensure_final_newline: bool = True) → str[source]

Dump output to a temporary file. Return path to the file.

Parameters:

*output (str) – List of strings to dump into the output.
ensure_final_newline (bool) – Whether to make sure that every dumped string ends in a new line. (Default value = True)

Returns:

Path to the produced temp file.

Return type:

str

output_fix() → Changed[source]

Output the fixed file. Either to stdout or the file.

Returns:: Whether there were any changes.
Return type:: Changed
Raises:: AssertionError – If the input and output lines are identical but pymend reports some elements to have changed.

output_patch() → Changed[source]

Output the patch. Either to stdout or a file depending on input file.

Returns:: Whether there were any changes.
Return type:: Changed

proceed() → None[source]: Parse file and generates/converts the docstrings.

report_issues() → tuple[int, str][source]

Produce a report of all found issues with the docstrings in the file.

Returns:: The number of elements that had issues as well as a string representation of those.
Return type:: tuple[int, str]

class pymend.pymend.Styles(input_style: DocstringStyle, output_style: DocstringStyle)[source]

Bases: NamedTuple

Container for input and output style.

input_style: DocstringStyle: Alias for field number 0

output_style: DocstringStyle: Alias for field number 1

pymend.pymendapp module

Command line interface for pymend.

pymend.pymendapp.path_is_excluded(normalized_path: str, pattern: Pattern[str] | None) → bool[source]

Check if a path is excluded because it matches and exclusion regex.

Parameters:

normalized_path (str) – Normalized path to check
pattern (Optional[Pattern[str]]) – Optionally a regex pattern to check against

Returns:

True if the path is excluded by the regex.

Return type:

bool

pymend.pymendapp.re_compile_maybe_verbose(regex: str) → Pattern[str][source]

Compile a regular expression string in regex.

If it contains newlines, use verbose mode.

Parameters:: regex (str) – Regex to compile.
Returns:: Compiled regex.
Return type:: Pattern[str]

pymend.pymendapp.read_pyproject_toml(ctx: Context, _param: Parameter, value: str | None) → str | None[source]

Inject Pymend configuration from “pyproject.toml” into defaults in ctx.

Returns the path to a successfully found and read configuration file, None otherwise.

Parameters:

ctx (click.Context) – Context containing preexisting default values.
value (Optional[str]) – Optionally path to the config file.

Returns:

Path to the config file if one was found or specified.

Return type:

Optional[str]

Raises:

click.FileError – If there was a problem reading the configuration file.
click.BadOptionUsage – If the value passed for exclude was not a string.
click.BadOptionUsage – If the value passed for extended_exclude was not a string.

pymend.pymendapp.run(files: tuple[str, ...], *, overwrite: bool = False, output_style: DocstringStyle = DocstringStyle.NUMPYDOC, input_style: DocstringStyle = DocstringStyle.AUTO, exclude: Pattern[str], extend_exclude: Pattern[str] | None, report: Report, fixer_settings: FixerSettings) → None[source]

Run pymend over the list of files..

Parameters:

files (tuple[str, ...]) – List of files to analyze and fix.
overwrite (bool) – Whether to overwrite the source file directly instead of creating a patch. (Default value = False)
output_style (dsp.DocstringStyle) – Output style to use for the modified docstrings. (Default value = dsp.DocstringStyle.NUMPYDOC)
input_style (dsp.DocstringStyle) – Input docstring style. Auto means that the style is detected automatically. Can cause issues when styles are mixed in examples or descriptions.” (Default value = dsp.DocstringStyle.AUTO)
exclude (Pattern[str]) – Optional regex pattern to use to exclude files from reformatting.
extend_exclude (Optional[Pattern[str]]) – Additional regexes to add onto the exclude pattern. Useful if one just wants to add some to the existing default.
report (Report) – Reporter for pretty communication with the user.
fixer_settings (FixerSettings) – Settings for which fixes should be performed.

Raises:

AssertionError – If the input and output lines are identical but pymend reports some elements to have changed.

pymend.pymendapp.style_option_callback(_c: Context, _p: Option | Parameter, style: str) → DocstringStyle[source]

Compute the output style from a –output_stye flag.

Parameters:: style (str) – String representation of the style to use.
Returns:: Style to use.
Return type:: dsp.DocstringStyle

pymend.pymendapp.validate_regex(_ctx: Context, _param: Parameter, value: str | None) → Pattern[str] | None[source]

Validate the regex from command line.

Parameters:: value (Optional[str]) – Regex pattern to validate.
Returns:: Compiled regex pattern or None if the input was None.
Return type:: Optional[Pattern[str]]
Raises:: click.BadParameter – If the value is not a valid regex.

pymend.types module

Module for defining commonly used types.

class pymend.types.ClassDocstring(name: str, docstring: str, lines: tuple[int, int | None], modifier: str, issues: list[str], had_docstring: bool, attributes: list[Parameter], methods: list[str])[source]

Bases: DocstringInfo

Information about a module.

attributes: list[Parameter]

methods: list[str]

class pymend.types.DocstringInfo(name: str, docstring: str, lines: tuple[int, int | None], modifier: str, issues: list[str], had_docstring: bool)[source]

Bases: object

Wrapper around raw docstring.

docstring: str

had_docstring: bool

issues: list[str]

lines: tuple[int, int | None]

modifier: str

name: str

output_docstring(*, settings: FixerSettings, output_style: DocstringStyle = DocstringStyle.NUMPYDOC, input_style: DocstringStyle = DocstringStyle.AUTO) → str[source]

Parse and fix input docstrings, then compose output docstring.

Parameters:

settings (FixerSettings) – Settings for what to fix and when.
output_style (dsp.DocstringStyle) – Output style to use for the docstring. (Default value = dsp.DocstringStyle.NUMPYDOC)
input_style (dsp.DocstringStyle) – Input style to assume for the docstring. (Default value = dsp.DocstringStyle.AUTO)

Returns:

String representing the updated docstring.

Return type:

str

Raises:

AssertionError – If the docstring could not be parsed.

report_issues() → tuple[int, str][source]

Report all issues that were found in this docstring.

Returns:: The number of issues found and a string representing a summary of those.
Return type:: tuple[int, str]

class pymend.types.FixerSettings(force_docstrings: bool = True, force_params: bool = True, force_return: bool = True, force_raises: bool = True, force_methods: bool = False, force_attributes: bool = False, force_params_min_n_params: int = 0, force_meta_min_func_length: int = 0, ignore_privates: bool = True, ignore_unused_arguments: bool = True, ignored_decorators: list[str] = <factory>, ignored_functions: list[str] = <factory>, ignored_classes: list[str] = <factory>, force_defaults: bool = True, force_return_type: bool = True, force_arg_types: bool = True, force_attribute_types: bool = True, indent: int = 4)[source]

Bases: object

Settings to influence which sections are required and when.

force_arg_types: bool = True

force_attribute_types: bool = True

force_attributes: bool = False

force_defaults: bool = True

force_docstrings: bool = True

force_meta_min_func_length: int = 0

force_methods: bool = False

force_params: bool = True

force_params_min_n_params: int = 0

force_raises: bool = True

force_return: bool = True

force_return_type: bool = True

ignore_privates: bool = True

ignore_unused_arguments: bool = True

ignored_classes: list[str]

ignored_decorators: list[str]

ignored_functions: list[str]

indent: int = 4

class pymend.types.FunctionBody(raises: list[str], returns: set[tuple[str, ...]], returns_value: bool, yields: set[tuple[str, ...]], yields_value: bool)[source]

Bases: object

Information about a function from its body.

raises: list[str]

returns: set[tuple[str, ...]]

returns_value: bool

yields: set[tuple[str, ...]]

yields_value: bool

class pymend.types.FunctionDocstring(name: str, docstring: str, lines: tuple[int, int | None], modifier: str, issues: list[str], had_docstring: bool, signature: FunctionSignature, body: FunctionBody, length: int)[source]

Bases: DocstringInfo

Information about a function from docstring.

body: FunctionBody

length: int

signature: FunctionSignature

class pymend.types.FunctionSignature(params: list[Parameter], returns: ReturnValue)[source]

Bases: object

Information about a function signature.

params: list[Parameter]

returns: ReturnValue

class pymend.types.ModuleDocstring(name: str, docstring: str, lines: tuple[int, int | None], modifier: str, issues: list[str], had_docstring: bool)[source]

Bases: DocstringInfo

Information about a module.

class pymend.types.Parameter(arg_name: str, type_name: str | None = None, default: str | None = None)[source]

Bases: object

Info for parameter from signature.

arg_name: str

custom_hash() → int[source]

Implement custom has function for uniquefying.

Returns:: Hash value of the instance.
Return type:: int

default: str | None = None

type_name: str | None = None

static uniquefy(lst: Iterable[Parameter]) → Iterator[Parameter][source]

Remove duplicates while keeping order.

Parameters:: lst (Iterable['Parameter']) – Iterable of parameters that should be uniqueified.
Yields:: ‘Parameter’ – Uniqueified parameters.

class pymend.types.ReturnValue(type_name: str | None = None)[source]

Bases: object

Info about return value from signature.

type_name: str | None = None

Module contents

Main pymend module.

class pymend.PyComment(input_file: Path, *, fixer_settings: FixerSettings, output_style: DocstringStyle = DocstringStyle.NUMPYDOC, input_style: DocstringStyle = DocstringStyle.AUTO, proceed_directly: bool = True)[source]

Bases: object

Manage several python scripts docstrings.

It is used to parse and rewrite in a Pythonic way all the functions’, methods’ and classes’ docstrings. The changes are then provided in a patch file.

assert_equality(src_lines: str, dst_lines: str) → None[source]

Assert that running pymend does not change functional ast.

Done by comparing the asts for the original and produced outputs while ignoring the docstrings themselves.

Parameters:

src_lines (str) – Lines from the input file.
dst_lines (str) – Lines that pymend produced.

Raises:

AssertionError – If the content of the input file could not be parsed into an ast.
AssertionError – If the output from pymend could not be parsed into an ast.
AssertionError – If the output from pymend produces a different (reduced) ast than the input.

assert_stability(src: list[str], dst: list[str]) → None[source]

Assert that running pymend on its own output does not change anything.

Parameters:

src (list[str]) – List of lines from the input file.
dst (list[str]) – List of lines that pymend produced.

Raises:

AssertionError – If a second run of pymend produces a different output than the first.

dump_to_file(*output: str, ensure_final_newline: bool = True) → str[source]

Dump output to a temporary file. Return path to the file.

Parameters:

*output (str) – List of strings to dump into the output.
ensure_final_newline (bool) – Whether to make sure that every dumped string ends in a new line. (Default value = True)

Returns:

Path to the produced temp file.

Return type:

str

output_fix() → Changed[source]

Output the fixed file. Either to stdout or the file.

Returns:: Whether there were any changes.
Return type:: Changed
Raises:: AssertionError – If the input and output lines are identical but pymend reports some elements to have changed.

output_patch() → Changed[source]

Output the patch. Either to stdout or a file depending on input file.

Returns:: Whether there were any changes.
Return type:: Changed

proceed() → None[source]: Parse file and generates/converts the docstrings.

report_issues() → tuple[int, str][source]

Produce a report of all found issues with the docstrings in the file.

Returns:: The number of elements that had issues as well as a string representation of those.
Return type:: tuple[int, str]