diff --git a/gnupg/gnupg.py b/gnupg/gnupg.py index 0ad2cd0..61c97ed 100644 --- a/gnupg/gnupg.py +++ b/gnupg/gnupg.py @@ -21,16 +21,17 @@ =========== A Python interface to GnuPG. -.. moduleauthor:: Isis Agora Lovecruft +.. moduleauthor:: Isis Lovecruft see also :attr:`gnupg.__authors__` -:license: see :attr:`gnupg.__license__` -:info: see +.. 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 ` object. + :class:`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 .batch, where 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 [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)