add PEP-257 docstrings

Author: Varbin

README.rst

@@ -101,5 +101,7 @@ Changelog
 
 Version 1.0:
     -   The "normal" camellia version is used instead of the mini or reference version.
-    -   Camellia is now loaded using CFFI. This improves speed and avoids shipped DLLs. It's better than the self-made-on-first-use compilation.
+    -   Camellia is now loaded using CFFI. This improves speed and avoids shipped DLLs. It's better than the self-made-on-first-use compilation,
+        which 
     -   Supports all standart modes of operation (ECB, CBC, CFB, OFB, CTR)
+    -   Electronic code book mode of operation is not implicit default anymore.

doc/conf.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-#
+"""Sphinx configuration for python-camellia."""
 # python-camellia documentation build configuration file, created by
 # sphinx-quickstart on Sun Oct 30 00:20:11 2016.
 #

setup.py

@@ -1,4 +1,15 @@
 #!/usr/bin/env python3
+"""
+Setup script for module `python-camellia`.
+
+Usage:
+    setup.py build          Builds extension modules and prepares for 
+                            installation
+    setup.py install        Installs module
+
+    setup.py sdist          Creates source package
+    setup.py bdist_wheel    Creates a `wheel` binary package
+"""
 
 from __future__ import print_function
 
@@ -21,11 +32,12 @@
 description = 'Camellia-cipher in Python'
 
 
-def long_description():
+def long_description(short=description):
+    """Try to read README.rst or returns fallback."""
     try:
         return open('README.rst').read()
     except:
-        return description
+        return short
 
 
 ext = camellia_build.ffi.distutils_extension()

src/camellia/__init__.py

@@ -1,4 +1,14 @@
 #!/usr/bin/env python3
+r"""Camellia implementation for Python.
+
+Example:
+
+    >>> import camellia
+    >>> cipher = camellia.new(b'\x80'+b'\x00*15, mode=camellia.MODE_ECB)
+    >>> cipher.encrypt(b'\x00'*16)
+    b'l"\x7ft\x93\x19\xa3\xaa}\xa25\xa9\xbb\xa0Z,'
+
+"""
 
 try:
     from ._camellia import lib, ffi
@@ -20,8 +30,6 @@
 #: CTR mode of operation
 MODE_CTR = 6
 
-#: All currently supported blockcipher modes of operation
-SUPPORTED_MODES = [MODE_ECB, MODE_CBC, MODE_CTR]
 
 if sys.version_info.major <= 2:
     b = lambda b: "".join(map(chr, b))
@@ -51,6 +59,7 @@ def Camellia_Ekeygen(rawKey):
     return keytable
 
 def Camellia_Encrypt(keyLength, keytable, plainText):
+    r"""Encrypt a plaintext block by given arguments."""
     if keyLength not in [128, 192, 256]:
         raise ValueError("Invalid key length, "
                          "it must be 16, 24 or 32 bytes long!")
@@ -67,6 +76,7 @@ def Camellia_Encrypt(keyLength, keytable, plainText):
 
 
 def Camellia_Decrypt(keyLength, keytable, cipherText):
+    r"""Decrypt a plaintext block by given arguments."""
     if keyLength not in [128, 192, 256]:
         raise ValueError("Invalid key length, "
                          "it must be 16, 24 or 32 bytes long!")
@@ -82,15 +92,14 @@ def Camellia_Decrypt(keyLength, keytable, cipherText):
     return b(out)[:-1]
 
 
-def new(key, mode=MODE_ECB, **kwargs):
+def new(key, mode, **kwargs):
     """Create an "CamelliaCipher" object.
-    The default mode is ECB.
     
     :param key: The key for encrytion/decryption. Must be 16/24/32 in length.
     :type key: bytestring
 
-    :param mode: Mode of operation, only ECB (0) and CBC (1) are supported.
-    :type mode: int, on of MODE_* constants
+    :param mode: Mode of operation.
+    :type mode: int, one of MODE_* constants
 
     :param IV: Initialisation vector for CBC/CFB/OFB, must be 16 in length.
     :type IV: bytestring
@@ -107,55 +116,29 @@ def new(key, mode=MODE_ECB, **kwargs):
 block_size = 16
 
 class CamelliaCipher(PEP272Cipher):
-    """
-    The CamelliaCipher object.
-    """
+    """The CamelliaCipher object."""
 
     #: block size of the camellia cipher
     block_size = 16 
 
     def __init__(self, key, mode, **kwargs):
-        """
-        Constructer of Cipher class. See :func:`camellia.new`.
-        """
-
+        """Constructer of Cipher class. See :func:`camellia.new`."""
         keytable = Camellia_Ekeygen(key)
         self.key_length = len(key)*8
-            
 
         PEP272Cipher.__init__(self, keytable, mode, **kwargs)
 
     def encrypt_block(self, key, block, **kwargs):
+        """Encrypt a single block with camellia."""
         return Camellia_Encrypt(self.key_length, key, block)
 
     def decrypt_block(self, key, block, **kwargs):
+        """Decrypt a single block with camellia."""
         return Camellia_Decrypt(self.key_length, key, block)
 
 
-
-CamelliaCipher.encrypt.__doc__ = """\
-Encrypt string.
-
-:param string:
-    The data to encrypt.
-    For the most modes of operation it must be a multiple
-    of 16 in length.
-:type string: bytestring
-"""
-
-
-CamelliaCipher.decrypt.__doc__ = """\
-Decrypt string.
-
-:param string:
-    The data to decrypt.
-    For the most modes of operation it must be a multiple
-    of 16 in length.
-:type string: bytestring
-"""
-
-
 def test(v=True):
+    """Small selftest of camellia with a single test vector."""
     key = b"80000000000000000000000000000000"
     plain = b"00000000000000000000000000000000"
     cipher = b"6C227F749319A3AA7DA235A9BBA05A2C"
@@ -172,7 +155,7 @@ def test(v=True):
             print("Required:\tcipher=%s" % cipher.decode())
             return "failed"
         else:
-            raise
+            raise Exception("Camellia does not work as expected!")
 
     dc = c.decrypt(ec)
 
@@ -182,9 +165,12 @@ def test(v=True):
             print("Required:\tcipher=%s" % plain.decode())
             return "failed"
         else:
-            raise
+            raise Exception("Camellia does not work as expected!")
 
     return "passed"
 
+
+assert test(False) == "passed"
+
 if __name__ == "__main__":
     print("Test: "+test())

src/camellia_build/__init__.py

@@ -1,4 +1,22 @@
 #!/usr/bin/env python3
+"""Builder for the C-extension of python-camellia.
+
+Usage:
+    a) __init__.py     Build extension module inplace.
+
+    b) Import camellia_build:
+
+    >>> from camellia_build import ffi
+    >>> extension = ffi.distutils_extension()
+    >>> from setuptools import setup
+    >>> setup(
+        ext_modules = [ext],
+        ...
+        )
+
+The extension will be built as camellia._camellia.
+"""
+
 
 import os
 from ._build_utils import make_ffi

src/camellia_build/_build_utils.py

@@ -1,9 +1,17 @@
+"""Small util for building single-source CFFI extension.
+
+Functions:
+    get_compile()   returns configured distutils C-compiler
+    make_ffi(...)   setups and extension (with ASLR on Windows!)
+"""
+
 from cffi import FFI
 from distutils.ccompiler import new_compiler
 from distutils.dist import Distribution
 
 
 def get_compiler():
+    """Return compile configured by Python."""
     dist = Distribution()
     dist.parse_config_files()
     cmd = dist.get_command_obj('build')
@@ -12,6 +20,7 @@ def get_compiler():
 
 
 def make_ffi(source_file, header_file, name, extra_link_args=[]):
+    """Setup an CFFI extension."""
     with open(header_file) as f:
         header = f.read()