docsweeper — Public API#

In this part we describe the public python API of Docsweeper, and show how to use it in code.

Example Usage#

The following code snippet shows how Docsweeper can be employed in code:

import docsweeper
from pathlib import Path

file_ = Path("code.py")

# create configuration object:
config = VCSCommandSetConfig(
    executable="/usr/bin/git",
    follow_rename=True
)

# choose version control system:
vcs = docsweeper.GitCommandSet

# run analysis and obtain results:
results = docsweeper.analyze(vcs, config, file_)

Running docsweeper.analyze_file() will parse and analyze the input file. See the full API below for more information on the data types used for the results.

API#

This is the public Python API of Docsweeper.

Client Entry Points#

Use docsweeper.analyze_file() to retrieve statistics about the docstrings of all the tokens in a file:

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]]

New in version 0.3.0.

Result Data Types#

These are the types used in the return value of docsweeper.analyze_file():

class docsweeper.DocumentedToken#

Bases: NamedTuple

Data class for a python code token.

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.DocumentedTokenStatistic#

Bases: NamedTuple

Statistics about the docstring history of a DocumentedToken.

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.

Version Control#

These classes are concerned with the interaction with the Version control system, and are passed as parameters to docsweeper.analyze_file(). docsweeper.GitCommandSet and docsweeper.MercurialCommandSet define the kind of version control system used, while docsweeper.VCSCommandSetConfig provides user-defined parameters to customize version control behavior.

class docsweeper.VCSCommandSet#

Bases: ABC

Encapsulates all commands needed for a complete version control command set.

New in version 0.4.0.

class docsweeper.GitCommandSet#

Bases: VCSCommandSet

An implementation of a version control command set for git.

class docsweeper.MercurialCommandSet#

Bases: VCSCommandSet

An implementation of a version control command set for mercurial.

class docsweeper.VCSCommandSetConfig#

Bases: NamedTuple

Configuration values for VCSCommandSet.

Holds configuration values that are customizable by clients.

executable: Optional[Path]#

The path of the executable of the version used.

follow_rename: Optional[bool]#

Whether the version control system shall follow renamed files.

is_complete()#

Return whether all entries of this config have a value.

Return type:

bool

merge(other)#

Return a new config with merged values of this config and other.

Parameters:

other (VCSCommandSetConfig) – entries that are not None in this config are merged into the new one

Returns:

the merged config

Return type:

VCSCommandSetConfig

docsweeper.command_sets = {'git': (<class '_docsweeper.version_control.GitCommandSet'>, VCSCommandSetConfig(executable=PosixPath('/usr/bin/git'), follow_rename=True)), 'hg': (<class '_docsweeper.version_control.MercurialCommandSet'>, VCSCommandSetConfig(executable=PosixPath('/usr/bin/hg'), follow_rename=True))}#

Dictionary of all supported command sets and their default configuration.

New in version 0.3.0.