diff --git a/docs/gnupg.rst b/docs/gnupg.rst index 323db8c..c216846 100644 --- a/docs/gnupg.rst +++ b/docs/gnupg.rst @@ -1,44 +1,125 @@ -gnupg Module -============ +gnupg package +============= + +gnupg module +------------ + +This module contains public classes for working with GnuPG_. To get started, +do: + +>>> import gnupg +>>> gpg = gnupg.GPG() + .. automodule:: gnupg :members: :undoc-members: + :private-members: :show-inheritance: + +meta module +----------- + +Contains the meta and base classes which :class:`gnupg.GPG` inherits +from. Mostly, you shouldn't ever need to touch anything in here, unless you're +doing some serious hacking. + + +.. automodule:: gnupg._meta + :members: + :undoc-members: + :private-members: + :show-inheritance: + + +parsers module +-------------- + +These are classes for parsing both user inputs and status file descriptor +flags from GnuPG's output. The latter are used in order to determine what our +GnuPG process is doing and retrieve information about its operations, which +are stored in corresponding classes in :attr:`gnupg.GPG._result_dict`. Some +status flags aren't handled yet -- infomation on *all* of the flags (well, at +least the documented ones…) can be found in the docs/DETAILS file in GnuPG's +source_, which has been included here_ as well. + + +.. automodule:: gnupg._parsers + :members: + :undoc-members: + :private-members: + :show-inheritance: + + +util module +----------- + +You shouldn't really need to mess with this module either, it mostly deals +with low-level IO and file handling operations, de-/en- coding issues, and +setting up basic package facilities such as logging. + +.. automodule:: gnupg._util + :members: + :undoc-members: + :private-members: + :show-inheritance: + + +About this fork +--------------- + +This is a modified version of python-gnupg_, (forked from version 0.3.2) which +was created by Vinay Sajip, which itself is a modification of GPG.py written +by Steve Traugott, which in turn is a modification of the pycrypto GnuPG +interface written by A.M. Kuchling. + +This version is patched to sanitize untrusted inputs, due to the necessity of +executing :class:`subprocess.Popen([...], shell=True)` in order to communicate +with GnuPG. Several speed improvements were also made based on code profiling, +and the API has been cleaned up to support an easier, more Pythonic, +interaction. + + Previous Authors' Documentation ------------------------------- Steve Traugott's documentation: - Portions of this module are derived from A.M. Kuchling's well-designed - GPG.py, using Richard Jones' updated version 1.3, which can be found in - the pycrypto CVS repository on Sourceforge: - - http://pycrypto.cvs.sourceforge.net/viewvc/pycrypto/gpg/GPG.py - - This module is *not* forward-compatible with amk's; some of the old - interface has changed. For instance, since I've added decrypt - functionality, I elected to initialize with a 'gpghome' argument instead - of 'keyring', so that gpg can find both the public and secret keyrings. - I've also altered some of the returned objects in order for the caller to - not have to know as much about the internals of the result classes. - - While the rest of ISconf is released under the GPL, I am releasing this - single file under the same terms that A.M. Kuchling used for pycrypto. - - Steve Traugott, stevegt@terraluna.org - Thu Jun 23 21:27:20 PDT 2005 + | Portions of this module are derived from A.M. Kuchling's well-designed + | GPG.py, using Richard Jones' updated version 1.3, which can be found in + | the pycrypto CVS repository on Sourceforge: + | + | http://pycrypto.cvs.sourceforge.net/viewvc/pycrypto/gpg/GPG.py + | + | This module is *not* forward-compatible with amk's; some of the old + | interface has changed. For instance, since I've added decrypt + | functionality, I elected to initialize with a 'gpghome' argument instead + | of 'keyring', so that gpg can find both the public and secret keyrings. + | I've also altered some of the returned objects in order for the caller to + | not have to know as much about the internals of the result classes. + | + | While the rest of ISconf is released under the GPL, I am releasing this + | single file under the same terms that A.M. Kuchling used for pycrypto. + | + | Steve Traugott, stevegt@terraluna.org + | Thu Jun 23 21:27:20 PDT 2005 Vinay Sajip's documentation: - This version of the module has been modified from Steve Traugott's version - (see http://trac.t7a.org/isconf/browser/trunk/lib/python/isconf/GPG.py) by - Vinay Sajip to make use of the subprocess module (Steve's version uses - os.fork() and so does not work on Windows). Renamed to gnupg.py to avoid - confusion with the previous versions. + | This version of the module has been modified from Steve Traugott's version + | (see http://trac.t7a.org/isconf/browser/trunk/lib/python/isconf/GPG.py) by + | Vinay Sajip to make use of the subprocess module (Steve's version uses + | os.fork() and so does not work on Windows). Renamed to gnupg.py to avoid + | confusion with the previous versions. + | + | A unittest harness (test_gnupg.py) has also been added. + | + | Modifications Copyright (C) 2008-2012 Vinay Sajip. All rights reserved. - A unittest harness (test_gnupg.py) has also been added. - Modifications Copyright (C) 2008-2012 Vinay Sajip. All rights reserved. +.. _GnuPG: http://gnupg.org +.. _python-gnupg: https://code.google.com/p/python-gnupg/ +.. _source: http://http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gnupg.git;a=shortlog;h=refs/heads/master +.. _here: ./DETAILS.html diff --git a/docs/index.rst b/docs/index.rst index 234f0ca..5616b8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,20 +1,36 @@ -.. python-gnupg documentation master file, created by +.. gnupg documentation master file, created by sphinx-quickstart on Fri Apr 5 22:38:47 2013. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -python-gnupg documentation -========================== +gnupg: Python Package Documentation +=================================== +A Python interface for handling interactions with GnuPG, including keyfile +generation, keyring maintainance, import and export, encryption and +decryption, sending to and recieving from keyservers, and signing and +verification. Contents: .. toctree:: - :maxdepth: 4 + :maxdepth: 2 gnupg - parsers +Source, license, & bug reports +============================== +The source code which was used to generate this documentation is accessible by +clicking the little [source]_ links next to the docs. Current source code can +be found in this github repository_. The **master** branch always reflects the +latest release, all releases are tagged with signed, annotated git tags, and +the **develop** branch represents the state of the next release. + +This package is released under AGPLv3_ or greater. + +If you find a bug, or would like to request a feature, please use our public +bugtracker_ on github. Patches warmly welcome. + Indices and tables ================== @@ -22,3 +38,7 @@ Indices and tables * :ref:`modindex` * :ref:`search` +.. _source: https://github.com/isislovecruft/python-gnupg +.. _repository: https://github.com/isislovecruft/python-gnupg +.. _AGPLv3: https://www.gnu.org/licenses/agpl-3.0.txt +.. _bugtracker: https://github.com/isislovecruft/python-gnupg/issues diff --git a/docs/parsers.rst b/docs/parsers.rst deleted file mode 100644 index 0b9c688..0000000 --- a/docs/parsers.rst +++ /dev/null @@ -1,7 +0,0 @@ -parsers Module -============== - -.. automodule:: parsers - :members: - :undoc-members: - :show-inheritance: