_docsweeper.version_control#

Module for version control functions.

class _docsweeper.version_control.VCSCommandSetConfig#

Bases: NamedTuple

Configuration values for VCSCommandSet.

Holds configuration values that are customizable by clients.

Note

This class is exported publicly as docsweeper.VCSCommandSetConfig.

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

class _docsweeper.version_control.FileRenamedError#

Bases: ValueError

Raised when a file was unexpectedly detected to have been renamed.

class _docsweeper.version_control.VCSCommandSet#

Bases: ABC

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

Note

This class is exported publicly as docsweeper.VCSCommandSet.

class _docsweeper.version_control.GitCommandSet#

Bases: VCSCommandSet

An implementation of a version control command set for git.

Note

This class is exported publicly as docsweeper.GitCommandSet.

class _docsweeper.version_control.MercurialCommandSet#

Bases: VCSCommandSet

An implementation of a version control command set for mercurial.

Note

This class is exported publicly as docsweeper.MercurialCommandSet.

class _docsweeper.version_control.VCSShim#

A shim between the output of a version control command set and clients.

Encapsulates the low-level commands of a VCSCommandSet into a more user-friendly interface.

__init__(vcs_command_set, vcs_command_set_config)#

Instantiate a VCSShim.

Parameters
Return type

None

get_all_revisions(path)#

Return a list of revision identifiers in which the file path was changed.

Parameters

path (Path) – the path of a file in the repository

Returns

a list of revision identifiers

Raises

ValueError – if path is not under version control

Return type

List[str]

get_file_from_repo(path, revision)#

Return the contents of path under revision.

Parameters

  • path (Path) – the path of a file in the repository

  • revision (str) – an identifier for a specific revision, eg a commit hash

Raises

  • RuntimeError – if the underlying version control command fails unexpectedly

  • ValueError – if path or revision is the empty string

Returns

the file content

Return type

str

get_old_name(path, revision)#

If a file has been renamed to path in revision, return this files’ old name.

Parameters

  • path (Path) – a path in the repository

  • revision (str) – a revision identifier

Returns

The old name of path in revision revision if it has been renamed in this revision. Returns ‘None’ otherwise.

Return type

Optional[Path]

vcs_root(path)#

Return the repository root directory of path.

This does not check whether path is actually under version control.

Parameters

path (Path) – the path of a file

Returns

The repository root of path

Return type

Path

_docsweeper.version_control.command_sets: Dict[str, Tuple[Type[_docsweeper.version_control.VCSCommandSet], _docsweeper.version_control.VCSCommandSetConfig]] = {'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.

Note

This object is exported publicly as docsweeper.command_sets.

class _docsweeper.version_control.VCSExecutableError#

Raised when there is an issue with the chosen version control executable.

For example, if the executable does not exist or is otherwise not executable.

__init__(vcs, executable)#

Raise an exception with executable for version control system vcs.

Parameters

  • vcs (str) –

  • executable (str) –

Return type

None