API Reference¶
git module¶
This module includes all calls to the git wrapper.
-
passpy.git.
_git_commit
(repo, msg, verbose=False)[source]¶ 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.
- repo (
-
passpy.git.
get_git_repository
(path)[source]¶ 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)[source]¶ Add a file or directory to the git repository and commit.
Parameters: - repo (
git.repo.base.Repo
) – The git repository. IfNone
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.
- repo (
-
passpy.git.
git_config
(repo, *args)[source]¶ Change the configuration of a git repository.
Parameters: repo ( git.Repo
) – The git repository to change the configuration for.
-
passpy.git.
git_init
(path)[source]¶ 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)[source]¶ Remove the file or directory at path from the repository and commit.
Parameters: - repo (
git.repo.base.Repo
) – The git repository. IfNone
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.
- repo (
gpg module¶
This module includes all calls to the gnupg wrapper.
-
passpy.gpg.
_get_gpg_recipients
(path)[source]¶ 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)[source]¶ Reencrypt a single key.
Gets called from
passpy.gpg._reencrypt_path()
.Parameters:
-
passpy.gpg.
read_key
(path, gpg_bin, gpg_opts)[source]¶ Read and decrypt a single key file.
Parameters: Return type: Returns: The unencrypted content of the file at path.
-
passpy.gpg.
reencrypt_path
(path, gpg_bin, gpg_opts)[source]¶ Reencrypt a single or multiple keys.
If path is a directory all keys inside that directory and it’s subdirectories will be reencrypted.
Parameters: Raises: FileNotFoundError – if path does not exist.
store module¶
-
class
passpy.store.
Store
(gpg_bin='gpg2', git_bin='git', store_dir='~/.password-store', use_agent=True, interactive=False, verbose=False)[source]¶ 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)[source]¶ 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. Will use the value of the PASSWORD_STORE_DIR environment variable by default, or ~/.password-store, if not set.
- 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)[source]¶ 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. IfFalse
the key or directory will be copied instead.
-
_get_store_name
(path)[source]¶ 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)[source]¶ Copies a key or directory within the password store.
Parameters:
-
find
(names)[source]¶ 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)[source]¶ 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)[source]¶ 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
()[source]¶ Initialise git for the password store.
Silently fails if
passpy.store.Store.repo
is notNone
.
-
init_store
(gpg_ids, path=None)[source]¶ 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)[source]¶ 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)[source]¶ Moves a key or directory within the password store.
Parameters:
-
remove_path
(path, recursive=False, force=False)[source]¶ 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 ifpasspy.store.Store.interactive
is set.
-
search
(term)[source]¶ 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)[source]¶ Add a key to the store or update an existing one.
Parameters: 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)[source]¶ 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 alsoTrue
. - 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)[source]¶ Generates a random string.
Uses
random.SystemRandom
if available andrandom.Random
otherwise.Parameters: Return type: Returns: A random string of length length.
-
passpy.util.
initialised
(func)[source]¶ 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)[source]¶ 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.