_docsweeper.util

General utility functions.

_docsweeper.util.call_subprocess(command, cwd=None)

Wrap calls to subprocess.run().

The parameters command and cwd are passed on to subprocess.run() and must adhere to the preconditions described there.

Parameters

• command (List[str]) – The command as specified by the interface of subprocess.run().

• cwd (Optional[Path]) – The directory to change to for executing the command. If None, then the current directory is used.

Raises

• subprocess.CalledProcessError – The underlying process has exited with a non-zero exit code.

• ExecutableError – when the command passed to subprocess.run() is not found or is otherwise not executable

Returns

The text that was written to standard output by running the command.

Return type

str

_docsweeper.util.read_file(path)

Read the file path to memory and return its contents.

Parameters

path (Path) – path of the file

Raises

• OSError – There has been an issue opening the file.

• ValueError – There is an encoding issue with the file.

Returns

The contents of path.

Return type

str

class _docsweeper.util.K

Generic type variable for a type that supports typing.Hashable.

class _docsweeper.util.V

Generic type variable for any object.

class _docsweeper.util.Cache

A generic key-value cache for any object type.

The key must be hashable, as a dictionary is used as the underlying data type.

__init__()

Instantiate the cache.

Return type

None

get(key)

Return item with key key.

Parameters

key (K) – key of the desired item

Returns

the item or None if there is no item with key key in the cache

Return type

Optional[V]

put(key, value)

Put object value to cache with key key.

Parameters

• key (K) – the key

• value (V) – the value

Return type

None

class _docsweeper.util.ExecutableError

Raised when the executable is not found or is not executable.

__init__(executable)

Raise an error that denotes a problem with executable.

Parameters

executable (str) –