Cleanup docstrings in gnupg.py.
Isis Lovecruft
parent
04b9a13a51
commit
641f503f4a
110
gnupg/gnupg.py
110
gnupg/gnupg.py
|
|
@ -21,16 +21,17 @@
|
|||
===========
|
||||
A Python interface to GnuPG.
|
||||
|
||||
.. moduleauthor:: Isis Agora Lovecruft <isis@patternsinthevoid.net>
|
||||
.. moduleauthor:: Isis Lovecruft <isis@patternsinthevoid.net>
|
||||
see also :attr:`gnupg.__authors__`
|
||||
:license: see :attr:`gnupg.__license__`
|
||||
:info: see <https://www.github.com/isislovecruft/python-gnupg>
|
||||
.. license:: see :attr:`gnupg.__license__`
|
||||
.. info:: https://github.com/isislovecruft/python-gnupg
|
||||
"""
|
||||
|
||||
from __future__ import absolute_import
|
||||
from codecs import open as open
|
||||
|
||||
import encodings
|
||||
import exceptions
|
||||
import functools
|
||||
import os
|
||||
import re
|
||||
|
|
@ -41,7 +42,7 @@ try:
|
|||
except ImportError:
|
||||
from cStringIO import StringIO
|
||||
|
||||
## see PEP-328 http://docs.python.org/2.5/whatsnew/pep-328.html
|
||||
#: see :pep:`328` http://docs.python.org/2.5/whatsnew/pep-328.html
|
||||
from . import _parsers
|
||||
from . import _util
|
||||
from . import _trust
|
||||
|
|
@ -70,35 +71,36 @@ class GPG(GPGBase):
|
|||
"""Initialize a GnuPG process wrapper.
|
||||
|
||||
:param str binary: Name for GnuPG binary executable. If the absolute
|
||||
path is not given, the evironment variable $PATH is
|
||||
searched for the executable and checked that the
|
||||
real uid/gid of the user has sufficient permissions.
|
||||
path is not given, the environment variable
|
||||
``$PATH`` is searched for the executable and
|
||||
checked that the real uid/gid of the user has
|
||||
sufficient permissions.
|
||||
|
||||
:param str homedir: Full pathname to directory containing the public
|
||||
and private keyrings. Default is whatever GnuPG
|
||||
defaults to.
|
||||
|
||||
:param str,int,bool verbose: String or numeric value to pass to gpg's
|
||||
``--debug-level`` option. See the gpg man
|
||||
page for the list of valid options. If
|
||||
False, debug output is not generated by
|
||||
the gpg binary. If True, defaults to
|
||||
``--debug-level basic.``
|
||||
:type verbose: :obj:`str` or :obj:`int` or :obj:`bool`
|
||||
:param verbose: String or numeric value to pass to GnuPG's
|
||||
``--debug-level`` option. See the GnuPG man page for
|
||||
the list of valid options. If False, debug output is
|
||||
not generated by the GnuPG binary. If True, defaults
|
||||
to ``--debug-level basic.``
|
||||
|
||||
:param str keyring: Name of keyring file containing public key data, if
|
||||
unspecified, defaults to 'pubring.gpg' in the
|
||||
``homedir`` directory.
|
||||
:param str keyring: Name of keyring file containing public key data.
|
||||
If unspecified, defaults to :file:`pubring.gpg` in
|
||||
the **homedir** directory.
|
||||
|
||||
:param str secring: Name of alternative secret keyring file to use. If
|
||||
left unspecified, this will default to using
|
||||
'secring.gpg' in the :param:homedir directory, and
|
||||
create that file if it does not exist.
|
||||
:file:`secring.gpg` in the **homedir** directory,
|
||||
and create that file if it does not exist.
|
||||
|
||||
:param list options: A list of additional options to pass to the GPG
|
||||
:param list options: A list of additional options to pass to the GnuPG
|
||||
binary.
|
||||
|
||||
:raises: :exc:`RuntimeError` with explanation message if there is a
|
||||
problem invoking gpg.
|
||||
:raises: A :exc:`~exceptions.RuntimeError` with explanation message
|
||||
if there is a problem invoking GnuPG.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -227,7 +229,7 @@ class GPG(GPGBase):
|
|||
In simpler terms: this function isn't for signing your friends' keys,
|
||||
it's for something like signing an email.
|
||||
|
||||
:type data: str or file
|
||||
:type data: :obj:`str` or :obj:`file`
|
||||
:param data: A string or file stream to sign.
|
||||
:param str default_key: The key to sign with.
|
||||
:param str passphrase: The passphrase to pipe to stdin.
|
||||
|
|
@ -236,7 +238,7 @@ class GPG(GPGBase):
|
|||
:param bool binary: If True, do not ascii armour the output.
|
||||
:param str digest_algo: The hash digest to use. Again, to see which
|
||||
hashes your GnuPG is capable of using, do:
|
||||
``$ gpg --with-colons --list-config digestname``.
|
||||
:command:`$ gpg --with-colons --list-config digestname`.
|
||||
The default, if unspecified, is ``'SHA512'``.
|
||||
"""
|
||||
if 'default_key' in kwargs.items():
|
||||
|
|
@ -384,11 +386,11 @@ class GPG(GPGBase):
|
|||
def delete_keys(self, fingerprints, secret=False, subkeys=False):
|
||||
"""Delete a key, or list of keys, from the current keyring.
|
||||
|
||||
The keys must be refered to by their full fingerprint for GnuPG to
|
||||
The keys must be referred to by their full fingerprints for GnuPG to
|
||||
delete them. If ``secret=True``, the corresponding secret keyring will
|
||||
be deleted from :attr:`GPG.secring`.
|
||||
be deleted from :obj:`.secring`.
|
||||
|
||||
:type fingerprints: str or list or tuple
|
||||
:type fingerprints: :obj:`str` or :obj:`list` or :obj:`tuple`
|
||||
:param fingerprints: A string, or a list/tuple of strings,
|
||||
representing the fingerprint(s) for the key(s)
|
||||
to delete.
|
||||
|
|
@ -398,8 +400,7 @@ class GPG(GPGBase):
|
|||
|
||||
:param bool subkeys: If True, delete the secret subkey first, then the
|
||||
public key. (default: False) Same as:
|
||||
``$ gpg --delete-secret-and-public-key
|
||||
0x12345678``
|
||||
:command:`$gpg --delete-secret-and-public-key 0x12345678`.
|
||||
"""
|
||||
which = 'keys'
|
||||
if secret:
|
||||
|
|
@ -548,7 +549,7 @@ class GPG(GPGBase):
|
|||
:param dict input: A dictionary of parameters and values for the new
|
||||
key.
|
||||
:returns: The result mapping with details of the new key, which is a
|
||||
:class:`parsers.GenKey <GenKey>` object.
|
||||
:class:`GenKey <gnupg._parsers.GenKey>` object.
|
||||
"""
|
||||
args = ["--gen-key --batch"]
|
||||
key = self._result_map['generate'](self)
|
||||
|
|
@ -585,11 +586,11 @@ class GPG(GPGBase):
|
|||
|
||||
def gen_key_input(self, separate_keyring=False, save_batchfile=False,
|
||||
testing=False, **kwargs):
|
||||
"""Generate a batch file for input to :meth:`GPG.gen_key()`.
|
||||
"""Generate a batch file for input to :meth:`~gnupg.GPG.gen_key`.
|
||||
|
||||
The GnuPG batch file key generation feature allows unattended key
|
||||
generation by creating a file with special syntax and then providing it
|
||||
to: ``gpg --gen-key --batch``. Batch files look like this:
|
||||
to: :command:`gpg --gen-key --batch`. Batch files look like this:
|
||||
|
||||
| Name-Real: Alice
|
||||
| Name-Email: alice@inter.net
|
||||
|
|
@ -648,9 +649,10 @@ class GPG(GPGBase):
|
|||
|
||||
:param bool separate_keyring: Specify for the new key to be written to
|
||||
a separate pubring.gpg and secring.gpg. If True,
|
||||
:meth:`GPG.gen_key` will automatically rename the separate keyring
|
||||
and secring to whatever the fingerprint of the generated key ends
|
||||
up being, suffixed with '.pubring' and '.secring' respectively.
|
||||
:meth:`~gnupg.GPG.gen_key` will automatically rename the separate
|
||||
keyring and secring to whatever the fingerprint of the generated
|
||||
key ends up being, suffixed with '.pubring' and '.secring'
|
||||
respectively.
|
||||
|
||||
:param bool save_batchfile: Save a copy of the generated batch file to
|
||||
disk in a file named <name_real>.batch, where <name_real> is the
|
||||
|
|
@ -664,11 +666,12 @@ class GPG(GPGBase):
|
|||
|
||||
:param str name_real: The name field of the UID in the generated key.
|
||||
:param str name_comment: The comment in the UID of the generated key.
|
||||
|
||||
:param str name_email: The email in the UID of the generated key.
|
||||
(default: $USER@$(hostname) ) Remember to use UTF-8 encoding for
|
||||
the entirety of the UID. At least one of ``name_real``,
|
||||
``name_comment``, or ``name_email`` must be provided, or else no
|
||||
user ID is created.
|
||||
(default: ``$USER`` @ :command:`hostname` ) Remember to use UTF-8
|
||||
encoding for the entirety of the UID. At least one of
|
||||
``name_real``, ``name_comment``, or ``name_email`` must be
|
||||
provided, or else no user ID is created.
|
||||
|
||||
:param str key_type: One of 'RSA', 'DSA', 'ELG-E', or 'default'.
|
||||
(default: 'RSA', if using GnuPG v1.x, otherwise 'default') Starts
|
||||
|
|
@ -707,7 +710,7 @@ class GPG(GPGBase):
|
|||
:param str subkey_usage: Key usage for a subkey; similar to
|
||||
``key_usage``.
|
||||
|
||||
:type expire_date: int or str
|
||||
:type expire_date: :obj:`int` or :obj:`str`
|
||||
:param expire_date: Can be specified as an iso-date or as
|
||||
<int>[d|w|m|y] Set the expiration date for the key (and the
|
||||
subkey). It may either be entered in ISO date format (2000-08-15)
|
||||
|
|
@ -729,17 +732,17 @@ class GPG(GPGBase):
|
|||
:param str passphrase: The passphrase for the new key. The default is
|
||||
to not use any passphrase. Note that GnuPG>=2.1.x will not allow
|
||||
you to specify a passphrase for batch key generation -- GnuPG will
|
||||
ignore the ``passphrase`` parameter, stop, and ask the user for
|
||||
ignore the **passphrase** parameter, stop, and ask the user for
|
||||
the new passphrase. However, we can put the command
|
||||
'%no-protection' into the batch key generation file to allow a
|
||||
``%no-protection`` into the batch key generation file to allow a
|
||||
passwordless key to be created, which can then have its passphrase
|
||||
set later with '--edit-key'.
|
||||
set later with ``--edit-key``.
|
||||
|
||||
:param str preferences: Set the cipher, hash, and compression
|
||||
preference values for this key. This expects the same type of
|
||||
string as the sub-command ‘setpref’ in the --edit-key menu.
|
||||
|
||||
:param str revoker: Should be given as 'algo:fpr' [case sensitive].
|
||||
:param str revoker: Should be given as 'algo:fpr' (case sensitive).
|
||||
Add a designated revoker to the generated key. Algo is the public
|
||||
key algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
|
||||
fpr is the fingerprint of the designated revoker. The optional
|
||||
|
|
@ -750,18 +753,18 @@ class GPG(GPGBase):
|
|||
preferred keyserver URL for the key.
|
||||
|
||||
:param str handle: This is an optional parameter only used with the
|
||||
status lines KEY_CREATED and KEY_NOT_CREATED. string may be up to
|
||||
100 characters and should not contain spaces. It is useful for
|
||||
batch key generation to associate a key parameter block with a
|
||||
status line.
|
||||
status lines ``KEY_CREATED`` and ``KEY_NOT_CREATED``. string may
|
||||
be up to 100 characters and should not contain spaces. It is
|
||||
useful for batch key generation to associate a key parameter block
|
||||
with a status line.
|
||||
|
||||
:rtype: str
|
||||
:returns: A suitable input string for the :meth:`GPG.gen_key` method,
|
||||
the latter of which will create the new keypair.
|
||||
|
||||
see
|
||||
http://www.gnupg.org/documentation/manuals/gnupg-devel/Unattended-GPG-key-generation.html
|
||||
for more details.
|
||||
See `this GnuPG Manual section`__ for more details.
|
||||
|
||||
__ http://www.gnupg.org/documentation/manuals/gnupg-devel/Unattended-GPG-key-generation.html
|
||||
"""
|
||||
#: A boolean for determining whether to set subkey_type to 'default'
|
||||
default_type = False
|
||||
|
|
@ -934,20 +937,21 @@ generate keys. Please see
|
|||
>>> decrypted
|
||||
'The crow flies at midnight.'
|
||||
|
||||
|
||||
:param str cipher_algo: The cipher algorithm to use. To see available
|
||||
algorithms with your version of GnuPG, do:
|
||||
``$ gpg --with-colons --list-config ciphername``.
|
||||
:command:`$ gpg --with-colons --list-config ciphername`.
|
||||
The default ``cipher_algo``, if unspecified, is ``'AES256'``.
|
||||
|
||||
:param str digest_algo: The hash digest to use. Again, to see which
|
||||
hashes your GnuPG is capable of using, do:
|
||||
``$ gpg --with-colons --list-config digestname``.
|
||||
:command:`$ gpg --with-colons --list-config digestname`.
|
||||
The default, if unspecified, is ``'SHA512'``.
|
||||
|
||||
:param str compress_algo: The compression algorithm to use. Can be one
|
||||
of ``'ZLIB'``, ``'BZIP2'``, ``'ZIP'``, or ``'Uncompressed'``.
|
||||
|
||||
See also: :meth:`GPGBase._encrypt`
|
||||
.. seealso:: :meth:`._encrypt`
|
||||
"""
|
||||
stream = _make_binary_stream(data, self._encoding)
|
||||
result = self._encrypt(stream, recipients, **kwargs)
|
||||
|
|
|
|||
Loading…
Reference in New Issue