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[pathlib.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.