API documentation¶
The following documentation is based on the source code of version 2.3 of the qpass package.
qpass
¶
Frontend for pass, the standard unix password manager.
-
qpass.
DEFAULT_DIRECTORY
= '~/.password-store'¶ The default password storage directory (a string).
The value of
DEFAULT_DIRECTORY
is normalized usingparse_path()
.
-
qpass.
DIRECTORY_VARIABLE
= 'PASSWORD_STORE_DIR'¶ The environment variable that sets the password storage directory (a string).
-
class
qpass.
AbstractPasswordStore
(**kw)[source]¶ Abstract Python API to query passwords managed by pass.
This abstract base class has two concrete subclasses:
- The
QuickPass
class manages multiple password stores as one. - The
PasswordStore
class manages a single password store.
-
entries
¶ A list of
PasswordEntry
objects.
-
exclude_list
[source]¶ A list of strings with filename patterns to ignore.
The
fnmatch
module is used for pattern matching. Filenames as well as patterns are normalized to lowercase before pattern matching is attempted.Note
The
exclude_list
property is acustom_property
. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
filtered_entries
[source]¶ A list of
PasswordEntry
objects that don’t match the exclude list.Note
The
filtered_entries
property is acached_property
. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
fuzzy_search
(*filters)[source]¶ Perform a “fuzzy” search that matches the given characters in the given order.
Parameters: filters – The pattern(s) to search for. Returns: The matched password names (a list of strings).
-
select_entry
(*arguments)[source]¶ Select a password from the available choices.
Parameters: arguments – Refer to smart_search()
.Returns: The name of a password (a string) or None
(when no password matched the given arguments).
-
simple_search
(*keywords)[source]¶ Perform a simple search for case insensitive substring matches.
Parameters: keywords – The string(s) to search for. Returns: The matched password names (a generator of strings). Only passwords whose names matches all of the given keywords are returned.
-
smart_search
(*arguments)[source]¶ Perform a smart search on the given keywords or patterns.
Parameters: arguments – The keywords or patterns to search for.
Returns: The matched password names (a list of strings).
Raises: The following exceptions can be raised:
NoMatchingPasswordError
when no matching passwords are found.EmptyPasswordStoreError
when the password store is empty.
This method first tries
simple_search()
and if that doesn’t produce any matches it will fall back tofuzzy_search()
. If no matches are found an exception is raised (see above).
- The
-
class
qpass.
QuickPass
(**kw)[source]¶ Python API to query multiple password stores as if they are one.
See also: The PasswordStore
class to query a single password store.-
entries
[source]¶ A list of
PasswordEntry
objects.Note
The
entries
property is acached_property
. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
stores
[source]¶ A list of
PasswordStore
objects.Note
The
stores
property is acustom_property
. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
-
class
qpass.
PasswordStore
(**kw)[source]¶ Python API to query a single password store.
See also: The QuickPass
class to query multiple password stores.-
context
[source]¶ An execution context created using
executor.contexts
.The value of
context
defaults to aLocalContext
object with the following characteristics:- The working directory of the execution context is set to the
value of
directory
. - The environment variable given by
DIRECTORY_VARIABLE
is set to the value ofdirectory
.
Raises: MissingPasswordStoreError
whendirectory
doesn’t exist.Note
The
context
property is acustom_property
. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.- The working directory of the execution context is set to the
value of
-
directory
[source]¶ The pathname of the password storage directory (a string).
When the environment variable given by
DIRECTORY_VARIABLE
is set the value of that environment variable is used, otherwiseDEFAULT_DIRECTORY
is used. In either case the resulting directory pathname is normalized usingparse_path()
.When you set the
directory
property, the value you set will be normalized usingparse_path()
and the computed value of thecontext
property is cleared.Note
The
directory
property is acustom_property
. You can change the value of this property using normal attribute assignment syntax. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
entries
[source]¶ A list of
PasswordEntry
objects.Note
The
entries
property is acached_property
. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
ensure_directory_exists
()[source]¶ Make sure
directory
exists.Raises: MissingPasswordStoreError
when the password storage directory doesn’t exist.
-
-
class
qpass.
PasswordEntry
(**kw)[source]¶ PasswordEntry
objects bind the name of a password to the store that contains the password.-
name
[source]¶ The name of the password store entry (a string).
Note
The
name
property is arequired_property
. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named name (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.
-
password
[source]¶ The password identified by
name
(a string).Note
The
password
property is acached_property
. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
store
[source]¶ The
PasswordStore
that contains the entry.Note
The
store
property is arequired_property
. You are required to provide a value for this property by calling the constructor of the class that defines the property with a keyword argument named store (unless a custom constructor is defined, in this case please refer to the documentation of that constructor). You can change the value of this property using normal attribute assignment syntax.
-
text
[source]¶ The full text of the entry (a string).
Note
The
text
property is acached_property
. This property’s value is computed once (the first time it is accessed) and the result is cached. To clear the cached value you can usedel
ordelattr()
.
-
format_text
(include_password=True, use_colors=None, padding=True, filters=())[source]¶ Format
text
for viewing on a terminal.Parameters: - include_password –
True
to include the password in the formatted text,False
to exclude the password from the formatted text. - use_colors –
True
to use ANSI escape sequences,False
otherwise. When this isNone
terminal_supports_colors()
will be used to detect whether ANSI escape sequences are supported. - padding –
True
to add empty lines before and after the entry and indent the entry’s text with two spaces,False
to skip the padding. - filters – An iterable of regular expression patterns (defaults to an empty tuple). If a line in the entry’s text matches one of these patterns it won’t be shown on the terminal.
Returns: The formatted entry (a string).
- include_password –
-
-
qpass.
create_fuzzy_pattern
(pattern)[source]¶ Convert a string into a fuzzy regular expression pattern.
Parameters: pattern – The input pattern (a string). Returns: A compiled regular expression object. This function works by adding
.*
between each of the characters in the input pattern and compiling the resulting expression into a case insensitive regular expression.
qpass.cli
¶
Usage: qpass [OPTIONS] KEYWORD..
Search your password store for the given keywords or patterns and copy the password of the matching entry to the clipboard. When more than one entry matches you will be prompted to select the password to copy.
If you provide more than one KEYWORD all of the given keywords must match, in other words you’re performing an AND search instead of an OR search.
Instead of matching on keywords you can also enter just a few of the characters in the name of a password, as long as those characters are in the right order. Some examples to make this more concrete:
- The pattern ‘pe/zbx’ will match the name ‘Personal/Zabbix’.
- The pattern ‘ba/cc’ will match the name ‘Bank accounts/Creditcard’.
When a password is copied to the clipboard, any text after the first line will
be shown on the terminal, to share any additional details about the password
entry (for example the associated username or email address). The -q
, --quiet
option suppresses this text.
Supported options:
Option | Description |
---|---|
-e , --edit |
Edit the matching entry instead of copying it to the clipboard. |
-l , --list |
List the matching entries on standard output. |
-n , --no-clipboard |
Don’t copy the password of the matching entry to the clipboard, instead show the password on the terminal (by default the password is copied to the clipboard but not shown on the terminal). |
-p , --password-store=DIRECTORY |
Search the password store in You can use the |
-f , --filter=PATTERN |
Don’t show lines in the additional details which match the case insensitive
regular expression given by PATTERN . This can be used to avoid revealing
sensitive details on the terminal. You can use this option more than once. |
-x , --exclude=GLOB |
Ignore passwords whose name matches the given GLOB filename pattern.
This argument can be repeated to add multiple exclude patterns. |
-v , --verbose |
Increase logging verbosity (can be repeated). |
-q , --quiet |
Decrease logging verbosity (can be repeated). |
-h , --help |
Show this message and exit. |
qpass.exceptions
¶
Custom exceptions raised by qpass
.
-
exception
qpass.exceptions.
PasswordStoreError
[source]¶ Base class for custom exceptions raised by
qpass
.
-
exception
qpass.exceptions.
MissingPasswordStoreError
[source]¶ Raised when the password store directory doesn’t exist.