Document the PyNaCl encoding system

docs/encoding.rst

+Encoders
+========
+
+PyNaCl supports a simple method of encoding and decoding messages in different
+formats. Encoders are simple classes with staticmethods that encode/decode and
+are typically passed as a keyword argument `encoder` to various methods.
+
+For example you can generate a signing key and encode it in hex with:
+
+.. code:: python
+
+    hex_key = nacl.signing.SigningKey.generate().encode(encoder=nacl.encoding.HexEncoder)
+
+Then you can later decode it from hex:
+
+.. code:: python
+
+    signing_key = nacl.signing.SigningKey(hex_key, encoder=nacl.encoding.HexEncoder)
+
+
+Built in Encoders
+-----------------
+
+.. autoclass:: nacl.encoding.RawEncoder
+    :members:
+
+.. autoclass:: nacl.encoding.HexEncoder
+    :members:
+
+.. autoclass:: nacl.encoding.Base16Encoder
+    :members:
+
+.. autoclass:: nacl.encoding.Base32Encoder
+    :members:
+
+.. autoclass:: nacl.encoding.Base64Encoder
+    :members:
+
+
+Defining your own Encoder
+-------------------------
+
+Defining your own encoder is easy. Each encoder is simply a class with 2 static
+methods. For example here is the hex encoder:
+
+.. code:: python
+
+    import binascii
+
+    class HexEncoder(object):
+
+        @staticmethod
+        def encode(data):
+            return binascii.hexlify(data)
+
+        @staticmethod
+        def decode(data):
+            return binascii.unhexlify(data)

docs/index.rst

@@ -9,6 +9,15 @@ Contents:
    signing
 
 
+Support Features
+----------------
+
+.. toctree::
+    :maxdepth: 2
+
+    encoding
+
+
 Api Documentation
 -----------------
 

docs/signing.rst

@@ -19,7 +19,7 @@ Signer's perspective (:class:`~nacl.signing.SigningKey`)
 
 .. code:: python
 
-    import binascii
+    import nacl.encoding
     import nacl.signing
 
     # Generate a new random signing key
@@ -32,17 +32,16 @@ Signer's perspective (:class:`~nacl.signing.SigningKey`)
     verify_key = signing_key.verify_key
 
     # Serialize the verify key to send it to a third party
-    binascii.hexlify(bytes(verify_key))
+    verify_key_hex = verify_key.encode(encoder=nacl.encoding.HexEncoder)
 
 Verifier's perspective (:class:`~nacl.signing.VerifyKey`)
 
 .. code:: python
 
-    import binascii
     import nacl.signing
 
     # Create a VerifyKey object from a hex serialized public key
-    verify_key = nacl.signing.VerifyKey(binascii.unhexlify(verify_key_hex))
+    verify_key = nacl.signing.VerifyKey(verify_key_hex, encoder=nacl.encoding.HexEncoder)
 
     # Check the validity of a message's signature
     # Will raise nacl.signing.BadSignatureError if the signature check fails

nacl/signing.py

@@ -47,7 +47,7 @@ class VerifyKey(encoding.Encodable, six.StringFixer, object):
     signatures.
 
     :param key: [:class:`bytes`] Serialized Ed25519 public key
-    :param encoding: [:class:`str`] The encoding that the key is encoded with
+    :param encoder: A class that is able to decode the `key`
     """
 
     def __init__(self, key, encoder=encoding.RawEncoder):
@@ -73,8 +73,8 @@ class VerifyKey(encoding.Encodable, six.StringFixer, object):
             signature and message concated together.
         :param signature: [:class:`bytes`] If an unsigned message is given for
             smessage then the detached signature must be provded.
-        :param encoding: [:class:`str`] The encoding that the secret message
-            and signature is encoded with.
+        :param encoder: A class that is able to decode the secret message and
+            signature.
         :rtype: :class:`bytes`
         """
         if signature is not None:
@@ -107,7 +107,7 @@ class SigningKey(encoding.Encodable, six.StringFixer, object):
         masquerade as you.
 
     :param seed: [:class:`bytes`] Random 32-byte value (i.e. private key)
-    :param encoding: [:class:`str`] The encoding that the seed is encoded with
+    :param encoder: A class that is able to decode the seed
 
     :ivar: verify_key: [:class:`~nacl.signing.VerifyKey`] The verify
         (i.e. public) key that corresponds with this signing key.
@@ -155,8 +155,7 @@ class SigningKey(encoding.Encodable, six.StringFixer, object):
         Sign a message using this key.
 
         :param message: [:class:`bytes`] The data to be signed.
-        :param encoding: [:class:`str`] The encoding to encode the signed
-            message with.
+        :param encoder: A class that is used to encode the signed message.
         :rtype: :class:`~nacl.signing.SignedMessage`
         """
         sm = nacl.ffi.new("unsigned char[]", len(message) + nacl.lib.crypto_sign_BYTES)