API Reference¶

git module¶

This module includes all calls to the git wrapper.

passpy.git._git_commit(repo, msg, verbose=False)¶

Commit the current changes.

Parameters:	repo (`git.repo.base.Repo`) – The repository to use. msg (str) – The commit message. verbose (bool) – (optional) If `True` git’s standard output will be printed.

passpy.git.get_git_repository(path)¶

Get the git repository at path.

Parameters:	path (str) – The path of a git repository to return.
Return type:	`git.repo.base.Repo`
Returns:	The git repository at path or None if no repository exists.

passpy.git.git_add_path(repo, path, msg, commit=True, verbose=False)¶

Add a file or directory to the git repository and commit.

Parameters:

repo (git.repo.base.Repo) – The git repository. If None the function will silently fail.
path (str or list) – The path of the file or directory to commit relative to passpy.store.Store.store_dir.
msg (str) – The commit message.
commit (bool) – (optional) If True the added file will also be commited.
verbose (bool) – (optional) If True git’s standard output will be printed.

Raises:

OSError – if something went wrong with adding the files.

passpy.git.git_config(repo, *args)¶

Change the configuration of a git repository.

Parameters:	repo (`git.Repo`) – The git repository to change the configuration for.

passpy.git.git_init(path)¶

Create a new git repository.

Parameters:	path (str) – The absolute path directory to create a git repository in.
Return type:	`git.Repo`
Returns:	The newly initialised git repository.

passpy.git.git_remove_path(repo, path, msg, recursive=False, commit=True, verbose=False)¶

Remove the file or directory at path from the repository and commit.

Parameters:

repo (git.repo.base.Repo) – The git repository. If None the function will silently fail.
path (str or list) – The file or directory to remove.
msg (str) – The commit message.
recursive (bool) – (optional) Set to True if directories should be removed from the repository recursively.
verbose (bool) – (optional) If True git’s standard output will be printed.

gpg module¶

This module includes all calls to the gnupg wrapper.

passpy.gpg._get_gpg_recipients(path)¶

Get the GPG recipients for the given path.

Parameters:	path (str) – The directory to get the GPG recipients for.
Raises:	FileNotFoundError – if there is not valid .gpg-id file for path.
Return type:	list
Returns:	The list of IDs of the GPG recipients for the given path.

passpy.gpg._reencrypt_key(path, gpg, gpg_recipients)¶

Reencrypt a single key.

Gets called from passpy.gpg._reencrypt_path().

Parameters:	path (str) – The path to a gpg encrypted file. gpg (`gnupg.GPG`) – The gpg object. gpg_recipients (list) – The list of GPG Ids to encrypt the key with.

passpy.gpg.read_key(path, gpg_bin, gpg_opts)¶

Read and decrypt a single key file.

Parameters:	path (str) – The path to the key to decrypt. gpg_bin (str) – The path to the gpg binary. gpg_opts (list) – The options for gpg.
Return type:	str
Returns:	The unencrypted content of the file at path.

passpy.gpg.reencrypt_path(path, gpg_bin, gpg_opts)¶

Reencrypt a single or multiple keys.

If path is a directory all keys inside that directory and it’s subdirectories will be reencrypted.

Parameters:	path (str) – The key or directory to reencrypt. If `None` the function will silently fail. gpg_bin (str) – The path to the gpg binary. gpg_opts (list) – The gpg options.
Raises:	FileNotFoundError – if path does not exist.

passpy.gpg.write_key(path, key_data, gpg_bin, gpg_opts)¶

Encrypt and write a single key file.

Parameters:	path (str) – The path to the key to decrypt. gpg_bin (str) – The path to the gpg binary. gpg_opts (list) – The options for gpg.

store module¶

class passpy.store.Store(gpg_bin='gpg2', git_bin='git', store_dir='~/.password-store', use_agent=True, interactive=False, verbose=False)¶

Python implementation of ZX2C4’s password store.

__init__(gpg_bin='gpg2', git_bin='git', store_dir='~/.password-store', use_agent=True, interactive=False, verbose=False)¶

Creates a new Store object.

Parameters:

gpg_bin (str) – (optional) The path to the gpg binary.
git_bin (str) – (optional) The path to the git binary. CURRENTLY DOES NOTHING You will need to set the environmental variable GIT_PYTHON_GIT_EXECUTABLE to your path to git binary if your git binary not in your PATH already.
store_dir (str) – (optional) The path to the password store.
use_agent (bool) – (optional) Set to True if you are using a gpg agent.
interactive (bool) – (optional) If True the user will be prompted before overwriting/deleting files.
verbose (bool) – (optional) If True additional information will be printed to the standard out.

__weakref__¶: list of weak references to the object (if defined)

_copy_move_path(old_path, new_path, force=False, move=False)¶

Copies or moves a key or directory within the password store.

Parameters:

old_path (str) – The current path of the key or directory.
new_path (str) – The new path of the key or directory. If new_path ends in a trailing ‘/’ it will always be treated as a directory.
force (bool) – If True any existing key or directory at new_path will be overwritten.
move (bool) – If True the key or directory will be moved. If False the key or directory will be copied instead.

_get_store_name(path)¶

Returns the path relative to the store.

Parameters:	path (str) – The absolute path to an entry in the store.
Return type:	str
Returns:	path relative to `passpy.store.Store.store_dir` without a leading ‘/’ and trailing ‘.gpg’ if any.

copy_path(old_path, new_path, force=False)¶

Copies a key or directory within the password store.

Parameters:	old_path (str) – The current path of the key or directory. new_path (str) – The new path of the key or directory. If new_path ends in a trailing ‘/’ it will always be treated as a directory. force (bool) – If `True` any existing key or directory at new_path will be overwritten.

find(names)¶

Find keys by name.

Finds any keys in the password store that contain any one entry in names.

Parameters:	names (str or list) – The name or names to find keys for.
Return type:	list
Returns:	A list of keys whose name contain any one entry in names.

gen_key(path, length, symbols=True, force=False, inplace=False)¶

Generate a new password for a key.

Parameters:

path (str) – The path of the key.
length (int) – The length of the new password.
symbols (bool) – (optional) If True non alphanumeric characters will also be used in the new password.
force (bool) – (optional) If True an existing key at path will be overwritten.
inplace (bool) – (optional) If True only the first line of an existing key at path will be overwritten with the new password.

get_key(path)¶

Reads the data of the key at path.

Parameters:	path (str) – The path to the key (without ‘.gpg’ ending) relative to `passpy.store.Store.store_dir`.
Return type:	str
Returns:	The key data as a string or `None`, if the key does not exist.
Raises:	FileNotFoundError – if path is not a file.

init_git()¶

Initialise git for the password store.

Silently fails if passpy.store.Store.repo is not None.

init_store(gpg_ids, path=None)¶

Initialise the password store or a subdirectory with the gpg ids.

Parameters:	gpg_ids (list) – The list of gpg ids to encrypt the password store with. If the list is empty, the current gpg id will be removed from the directory in path or root, if path is None. path (str) – (optional) If given, the gpg ids will only be set for the given directory. The path is relative to `passpy.store.Store.store_dir`.
Raises:	ValueError – if the there is a problem with path. FileExistsError – if `passpy.store.Store.store_dir` already exists and is a file. FileNotFoundError – if the current gpg id should be deleted, but none exists. OSError – if the directories in path do not exist and can’t be created.

list_dir(path)¶

Returns all directory and key entries for the given path.

Parameters:	path (str) – The directory to list relative to `passpy.store.Store.store_dir`
Return type:	(list, list)
Returns:	Two lists, the first for directories, the second for keys. `None` if path is not a directory.
Raises:	FileNotFoundError – if path is not a directory in the password store.

move_path(old_path, new_path, force=False)¶

Moves a key or directory within the password store.

Parameters:	old_path (str) – The current path of the key or directory. new_path (str) – The new path of the key or directory. If new_path ends in a trailing ‘/’ it will always be treated as a directory. force (bool) – If `True` any existing key or directory at new_path will be overwritten.

remove_path(path, recursive=False, force=False)¶

Removes the given key or directory from the store.

Parameters:	path (str) – The key or directory to remove. Use ‘’ to delete the whole store. recursive (bool) – (optional) Set to `True` if nonempty directories should be removed. force (bool) – (optional) If `True` the user will never be prompted for deleting a file or directory, even if `passpy.store.Store.interactive` is set.

search(term)¶

Search through all keys.

Parameters:	term (str) – The term to search for. The term will be compiled as a regular expression.
Return type:	dict
Returns:	The dictionary has an entry for each key, that matched the given term. The entry for that key then contains a list of tuples with the line the term was found on and the match object.

set_key(path, key_data, force=False)¶

Add a key to the store or update an existing one.

Parameters:	path (str) – The key to write. key_data (str) – The data of the key. foce (bool) – (optional) If `True` path will be overwritten if it exists.
Raises:	FileExistsError – if a key already exists for path and overwrite is `False`.

util module¶

passpy.util.copy_move(src, dst, force=False, move=False, interactive=False, verbose=False)¶

Copies/moves a file or directory recursively.

This function is partially based on the cp function from the pycoreutils package written by Hans van Leeuwen and licensed under the MIT license.

Parameters:

src (str) – The file or directory to be copied.
dst (str) – The file or directory to be copied to.
force (bool) – If True existing files at the destination will be silently overwritten.
interactive (bool) – If True the user will be prompted for every file to be overwritten. Has no effect if force is also True.
verbose (bool) – If True print the old and new filename for every copied/moved file.

Raises:

FileNotFoundError – if there exists no key or directory for src.
FileExistsError – if a key at dst already exists and force is set to False.

passpy.util.gen_password(length, symbols=True)¶

Generates a random string.

Uses random.SystemRandom if available and random.Random otherwise.

Parameters:	length (int) – The length of the random string. symbols (bool) – (optional) If `True` `string.punctuation` will also be used to generate the output.
Return type:	str
Returns:	A random string of length length.

passpy.util.initialised(func)¶

Check that the store is initialised before running.

Used as a decorator in methods for passpy.store.Store.

Parameters:	func – A method of `passpy.store.Store`.
Return type:	function
Returns:	The method if the store is initialised.
Raises:	passpy.exceptions.StoreNotInitialisedError – if the store is not initialised.

passpy.util.trap(path_index)¶

Prevent accessing files and directories outside the password store.

path_index is necessary as the functions that need to be trapped have different argument lists. This way we can indicate which argument contains the paths that are to be checked.

Parameters:	path_index (int or str) – The index for the path variable in either args or kwargs.
Return type:	func
Returns:	The trapped function.