_docsweeper.docsweeper#

Main module for docsweeper functionality.

class _docsweeper.docsweeper.DocumentedToken#

Bases: NamedTuple

Data class for a python code token.

Note

This class is exported publicly as docsweeper.DocumentedToken.

docstring: str#

docstring of the code token

end_lineno: int#

ending line number

lineno: int#

beginning line number

name: str#

name of the code token

text: str#

code of the token, with the docstring removed

class _docsweeper.docsweeper.DocumentedTokenStatistic#

Bases: NamedTuple

Statistics about the docstring history of a DocumentedToken.

Note

This class is exported publicly as docsweeper.DocumentedTokenStatistic.

code_changes: int#

How often the body of the token was changed since last_docstring_change.

last_docstring_change: Optional[Tuple[str, int]]#

A tuple consisting of the revision the docstring was last changed, and an integer depicting how many commits ago that was. None if the docstring has not ever been changed.

_docsweeper.docsweeper.analyze_file(vcs_command_set_type, vcs_command_set_config, path)#

Analyzes code file at path and return its documented token statistics.

Parameters

  • vcs_command_set_type (Type[VCSCommandSet]) – type of the version control system to use

  • vcs_command_set_config (VCSCommandSetConfig) – version control configuration

  • path (Path) – points to the code file in the file system

Raises

  • VCSExecutableError – if there is an unexpected error with the executable set in vcs_command_set_config

  • ParserError – if there is an unexpected error parsing path

Returns

each entry of the list consists of the documented token, and its docstring history statistic

Return type

List[Tuple[DocumentedToken, DocumentedTokenStatistic]]

Note

This function is exported publicly as docsweeper.analyze_file.

class _docsweeper.docsweeper.ParserError#

Raised when a code file could not be parsed.

__init__(file_, error)#

file_ was not parseable due to underlying parser error error.

Parameters
Return type

None