Unsignedio
/
python-gnupg
mirror of https://github.com/markqvist/python-gnupg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Cleanup docstrings in gnupg.py.

fix/30-hidden-recipient
Isis Lovecruft 2013-12-03 22:35:17 +00:00
parent 04b9a13a51
commit 641f503f4a
No known key found for this signature in database
GPG Key ID: 5C17776E27F7E84D
1 changed files with 57 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
gnupg/gnupg.py
View File

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