Merge pull request data61#24 from NICTA/develop

* Calculate code coverage data61#16

* Add instructions for enabling bash completion of cli tool.

* Update docs, add doctests and build docs on travis.

* Generate coverage using nosetests.

* Add example cli session to documentation

* Document serialisation of keys using JWK format (data61#20)

Document serialisation of keys using JWK format

* Improved support for alternative encodings (data61#23)

* Ability to encrypt and decrypt with an arbitrary EncodedNumber object. Closes data61#21
* Fix encryption tests that were not actually encrypting data61#22
* Add an example using an alternative encoding base

* Documentation of alt base. Fix broken links.

.travis.yml

@@ -5,7 +5,10 @@ env:
 
 # Note travis times out with the following:
 #  - TEST_PYCRYPTO="true" TEST_GMPY="false"
-
+
+# Inorder to test with and without some libraries, we explicitly
+# install deps instead of installing from the requirements file
+
 python:
   - "3.3"
   - "3.4"
@@ -21,7 +24,9 @@ before_install:
   - sudo apt-get install -qq python3-crypto
   - sudo apt-get install -qq libgmp-dev libmpfr-dev
   - sudo apt-get install -qq libgmp3-dev libgmp3c2 libmpfr4 libmpc-dev libmpc2
-  # Install gmpy2 dependencies
+  - pip install --upgrade pip
+  - pip install --upgrade nose
+  # Install gmpy2 dependency
   - if [[ $TEST_GMPY == "true" ]]; then
       wget ftp://ftp.gnu.org/gnu/mpc/mpc-1.0.3.tar.gz;
       tar xzvf mpc-1.0.3.tar.gz;
@@ -37,7 +42,7 @@ before_install:
       pip install pycrypto==2.6.1;
     fi
 install:
-  - pip install nose
+  - pip install numpy
   - pip install click
-# command to run tests
 script:  nosetests -v
+

README.rst

@@ -1,15 +1,17 @@
-python-paillier
+python-paillier  |release|
 ===============
 
-+--------------+------------+-----------+
-|  release     | master     | develop   |
-+==============+============+===========+
-|  |release|   | |travisM|  | |travisD| |
-+--------------+------------+-----------+
-|              | |reqM|     | |reqD|    |
-+--------------+------------+-----------+
-|              | |rtdM|     | |rtdD|    |
-+--------------+------------+-----------+
++---------------------+-----------------+
+|       master        |    develop      |
++=====================+=================+
+|      |travisM|      |   |travisD|     |
++---------------------+-----------------+
+|      |rtdM|         |   |rtdD|        |
++---------------------+-----------------+
+|      |coverageM|    |   |coverageD|   |
++---------------------+-----------------+
+|      |reqM|         |   |reqD|        |
++---------------------+-----------------+
 
 A library for Partially Homomorphic Encryption in Python.
 
@@ -34,7 +36,7 @@ Or use nose::
 Code History
 ------------
 
-Developed at Data61.
+Developed at `Data61 | CSIRO <http://data61.csiro.au>`_.
 
 Parts derived from the Apache licensed Google project:
 https://code.google.com/p/encrypted-bigquery-client/
@@ -72,5 +74,13 @@ expert. The crypto parts are mercifully short, however.
    :alt: Documentation Status
 
 .. |rtdD| image:: https://readthedocs.org/projects/python-paillier/badge/?version=develop
-    :target: http://python-paillier.readthedocs.org/en/latest/?badge=develop
-    :alt: Documentation Status
+   :target: http://python-paillier.readthedocs.org/en/latest/?badge=develop
+   :alt: Documentation Status
+
+.. |coverageM| image:: https://coveralls.io/repos/NICTA/python-paillier/badge.svg?branch=master&service=github
+    :target: https://coveralls.io/github/NICTA/python-paillier?branch=master
+
+.. |coverageD| image:: https://coveralls.io/repos/NICTA/python-paillier/badge.svg?branch=develop&service=github
+    :target: https://coveralls.io/github/NICTA/python-paillier?branch=develop
+
+

docs/cli.rst

@@ -1,16 +1,10 @@
 .. _cli:
 
+====================
 Command Line Utility
 ====================
 
-The command line utility is not installed by default. When installing with pip you
-must specify the optional extra eg::
-
-    pip install "phe[CLI]>1.2" --upgrade
-
-
-After :ref:`installation`, the **pheutil** command line program will be installed on your path.
-This interface allows a user to:
+This cli interface allows a user to:
 
 - generate and serialize key pairs (of different key sizes)
 - encrypt and serialize given a public key and a plaintext number
@@ -20,6 +14,27 @@ This interface allows a user to:
 - multiply an encrypted number to a plaintext number
 
 
+Installation
+------------
+
+The command line utility is not installed by default. When installing with pip you
+must specify the optional extra eg::
+
+    pip install "phe[cli]" --upgrade
+
+
+After :ref:`installation`, the **pheutil** command line program will be installed on your path.
+
+
+To use the command line client without installing `python-paillier`, run the
+:mod:`phe.command_line` module from the project root::
+
+    python -m phe.command_line
+
+
+Usage Help
+----------
+
 For commands, and examples call `--help`::
 
     $ pheutil --help
@@ -61,8 +76,45 @@ Each command also includes more detail, e.g. for `genpkey`::
       --id TEXT          Add an identifying comment to the key
 
 
-
-To use the command line client without installing `python-paillier`, run the
-:mod:`phe.command_line` module from the project root::
-
-    python -m phe.command_line
+Example Session
+---------------
+
+::
+
+    $ pheutil genpkey --keysize 1024 example_private_key.json
+    Generating a paillier keypair with keysize of 1024
+    Keys generated
+    Private key written to example_private_key.json
+    $ pheutil extract example_private_key.json example_public_key.json
+    Loading paillier keypair
+    Public key written to example_public_key.json
+    $ pheutil encrypt --output test.enc example_public_key.json 5000
+    Loading public key
+    Encrypting: +5000.0000000000000000
+    $ cat test.enc | python -m json.tool
+    {
+        "e": -32,
+        "v": "8945468961282852256778220989238222172150456425808373953578229301775803205409565637223688006899379858518150634149268673387123813092667724639715011697847472787020974697972558733184395004744948252959649660835719161407306407854534355718203796283103451456746682405859634010362011442548072273622024024463167923466056606817150074423359137917704381669997696942809271828714079014827677816707229329379573217492868913536374239033718507818834874942682659422972598117458546894148344090333255242329686475806834331038677335462130194428967083103705644514152785933564702168267063628303275275994362218144323611010911197842705253655015"
+    }
+    $ pheutil add --output result.enc example_public_key.json test.enc 100
+    Loading public key
+    Loading encrypted number
+    Loading unencrypted number
+    Adding
+    Exponent is less than -32
+    $ pheutil decrypt example_private_key.json result.enc
+    Loading private key
+    Decrypting ciphertext
+    5100.0
+
+
+
+Bash Completion
+---------------
+
+Bash completion can be enabled by adding the following to your `.bashrc` file::
+
+    eval "$(_PHEUTIL_COMPLETE=source pheutil)"
+
+Further information on bash completion can be found in the `click <http://click.pocoo.org/5/bashcomplete/>`_
+documentation.

docs/compatibility.rst

@@ -9,3 +9,10 @@ This library may, with *care*, be used with other Paillier implementations.
   different Encoding scheme. Base of 2 is fixed (see :ref:`alternative-base`)
 - `paillier.js <https://github.com/hardbyte/paillier.js>`_ - Early prototype library for Javascript/Typescript
 
+
+
+
+.. toctree::
+   :maxdepth: 2
+
+   alternatives

docs/conf.py

@@ -70,6 +70,10 @@ def __getattr__(cls, name):
     #'sphinxcontrib.napoleon'  # Sphinx 1.2
 ]
 
+# Don't test blocks that are not doctest directive blocks - e.g. all the
+# code in alternitives.rst
+doctest_test_doctest_blocks = ""
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/index.rst

@@ -1,7 +1,3 @@
-.. phe documentation master file, created by
-   sphinx-quickstart on Wed Jun 11 15:00:09 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
 python-paillier
 ===============
@@ -21,21 +17,19 @@ The homomorphic properties of the Paillier crypto system are:
 
    installation
    usage
+   serialisation
    caveats
    cli
    phe
    compatibility
 
 
-.. toctree::
-   :maxdepth: 1
-
-   alternatives
-
 
 Example
 -------
 
+.. doctest::
+
     >>> from phe import paillier
     >>> public_key, private_key = paillier.generate_paillier_keypair()
     >>> secret_number_list = [3.141592653, 300, -4.6e-12]

docs/installation.rst

@@ -3,6 +3,10 @@
 Installation
 ============
 
+.. note::
+
+    This library requires a minimum Python version of at least 3.3.
+
 Using pip
 ---------
 
@@ -11,9 +15,9 @@ Using pip at the command line, to install the base library from `PyPi <https://p
     $ pip install phe
 
 
-To also install the command line utility, introduced at version 1.2::
+To also install the :ref:`command line utility <cli>`, introduced at version 1.2::
 
-    pip install "phe[CLI]>1.2"
+    pip install "phe[cli]>1.2"
 
 
 

docs/phe.rst

@@ -2,6 +2,10 @@ API Documentation
 =================
 
 
+Paillier
+--------
+
+
 .. automodule:: phe.paillier
     :members:
     :undoc-members:
@@ -16,3 +20,13 @@ Utilities
     :members:
     :undoc-members:
     :show-inheritance:
+
+
+CLI
+----
+
+
+.. automodule:: phe.command_line
+    :members:
+    :undoc-members:
+    :show-inheritance: