Improve doc

LowVoltage/__init__.py

@@ -3,13 +3,11 @@
 # Copyright 2014-2015 Vincent Jacques <vincent@vincent-jacques.net>
 
 """
-.. automodule:: LowVoltage.connection
-.. automodule:: LowVoltage.actions
+All public symbols are imported in the top-level module, no need to import submodules.
 """
 
 from actions import *
 from attribute_types import *
 from compounds import *
 from connection import *
 from exceptions import *
-from policies import *

LowVoltage/attribute_types.py

@@ -2,6 +2,16 @@
 
 # Copyright 2014-2015 Vincent Jacques <vincent@vincent-jacques.net>
 
+"""
+In DynamoDB, the key attributes are typed.
+Here are a few constants for those types, to be used in :class:`.CreateTable` or compared to what :class:`.DescribeTable` returns.
+"""
+
 STRING = "S"
+"The 'string' attribute type"
+
 NUMBER = "N"
+"The 'number' attribute type"
+
 BINARY = "B"
+"The 'binary' attribute type"

LowVoltage/connection/__init__.py

@@ -2,18 +2,19 @@
 
 # Copyright 2014-2015 Vincent Jacques <vincent@vincent-jacques.net>
 
-import LowVoltage.policies as _pol
 # @todo Do we really need two Connection classes?
 from .signing import SigningConnection
 from .retrying import RetryingConnection
+from .retry_policies import ExponentialBackoffRetryPolicy
+from .credentials import StaticCredentials, EnvironmentCredentials
 
 
 # @todo Consider using a builder pattern... as everywhere else in LowVoltage
 def make_connection(
     region,
     credentials,
     endpoint=None,
-    retry_policy=_pol.ExponentialBackoffRetryPolicy(1, 2, 5)
+    retry_policy=ExponentialBackoffRetryPolicy(1, 2, 5)
 ):
     """Create a connection using the provided retry policy"""
     # @todo Maybe allow injection of the Requests session to tweek low-level parameters (connection timeout, etc.)?

LowVoltage/policies/retry.py → LowVoltage/connection/retry_policies.py

@@ -7,6 +7,9 @@
 
 
 class ExponentialBackoffRetryPolicy(object):
+    """
+    Retry failed requests with a waiting time growing exponentialy.
+    """
     def __init__(self, first_wait, multiplier, max_tries):
         self.__first_wait = first_wait
         self.__multiplier = multiplier

LowVoltage/connection/retrying.py

@@ -8,7 +8,8 @@
 from LowVoltage.actions.action import Action
 from .signing import SigningConnection
 import LowVoltage.exceptions as _exn
-import LowVoltage.policies as _pol
+from .credentials import StaticCredentials
+from .retry_policies import ExponentialBackoffRetryPolicy
 
 
 class RetryingConnection(object):
@@ -87,7 +88,7 @@ def build(self):
 
     def setUp(self):
         super(RetryingConnectionLocalIntegTests, self).setUp()
-        self.connection = RetryingConnection(SigningConnection("us-west-2", _pol.StaticCredentials("DummyKey", "DummySecret"), "http://localhost:65432/"), _pol.ExponentialBackoffRetryPolicy(1, 2, 5))
+        self.connection = RetryingConnection(SigningConnection("us-west-2", StaticCredentials("DummyKey", "DummySecret"), "http://localhost:65432/"), ExponentialBackoffRetryPolicy(1, 2, 5))
 
     def test_request(self):
         r = self.connection(self.TestAction("ListTables"))
@@ -99,7 +100,7 @@ def test_client_error(self):
             self.connection(self.TestAction("UnexistingAction"))
 
     def test_network_error(self):
-        connection = RetryingConnection(SigningConnection("us-west-2", _pol.StaticCredentials("DummyKey", "DummySecret"), "http://localhost:65555/"), _pol.ExponentialBackoffRetryPolicy(0, 1, 4))
+        connection = RetryingConnection(SigningConnection("us-west-2", StaticCredentials("DummyKey", "DummySecret"), "http://localhost:65555/"), ExponentialBackoffRetryPolicy(0, 1, 4))
         with self.assertRaises(_exn.NetworkError):
             connection(self.TestAction("ListTables"))
 

LowVoltage/connection/signing.py

@@ -13,7 +13,7 @@
 import LowVoltage.testing as _tst
 from LowVoltage.actions.action import Action, ActionProxy
 import LowVoltage.exceptions as _exn
-import LowVoltage.policies as _pol
+from .credentials import StaticCredentials
 
 
 class SigningConnection(object):
@@ -138,7 +138,7 @@ def json(self):
 
     def setUp(self):
         super(SigningConnectionUnitTests, self).setUp()
-        self.connection = SigningConnection("us-west-2", _pol.StaticCredentials("DummyKey", "DummySecret"), "http://localhost:65432/")
+        self.connection = SigningConnection("us-west-2", StaticCredentials("DummyKey", "DummySecret"), "http://localhost:65432/")
 
     def testSign(self):
         self.assertEqual(
@@ -233,6 +233,6 @@ def build(self):
             return {}
 
     def test_network_error(self):
-        connection = SigningConnection("us-west-2", _pol.StaticCredentials("DummyKey", "DummySecret"), "http://localhost:65555/")
+        connection = SigningConnection("us-west-2", StaticCredentials("DummyKey", "DummySecret"), "http://localhost:65555/")
         with self.assertRaises(_exn.NetworkError):
             connection(self.TestAction("ListTables"))

LowVoltage/connection/tests/unit.py

@@ -4,3 +4,4 @@
 
 from ..signing import SigningConnectionUnitTests
 from ..retrying import RetryingConnectionUnitTests
+from ..retry_policies import ExponentialBackoffRetryPolicyUnitTests

LowVoltage/tests/unit.py

@@ -6,7 +6,6 @@
 from LowVoltage.actions.tests.unit import *
 from LowVoltage.compounds.tests.unit import *
 from LowVoltage.connection.tests.unit import *
-from LowVoltage.policies.tests.unit import *
 from LowVoltage.testing.tests.unit import *
 
 

README.rst

@@ -1,4 +1,9 @@
-LowVoltage is a standalone Python (2 and 3) client for DynamoDB that doesn't hide any feature of the API.
+LowVoltage is a standalone Python (2.7+ and 3.4+) client for `DynamoDB <http://aws.amazon.com/documentation/dynamodb/>`__
+that doesn't hide any feature of `the API <http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/Welcome.html>`__.
+
+It's licensed under the `MIT license <http://choosealicense.com/licenses/mit/>`__.
+It depends only on the excellent `python-requests <http://python-requests.org>`__ library.
+It's available on the `Python package index <http://pypi.python.org/pypi/LowVoltage>`__, its `documentation is hosted by Python <http://pythonhosted.org/LowVoltage>`__ and its source code is on `GitHub <https://github.com/jacquev6/LowVoltage>`__.
 
 .. image:: https://img.shields.io/travis/jacquev6/LowVoltage/master.svg
     :target: https://travis-ci.org/jacquev6/LowVoltage
@@ -24,12 +29,6 @@ LowVoltage is a standalone Python (2 and 3) client for DynamoDB that doesn't hid
 .. image:: https://pypip.in/status/LowVoltage/badge.svg
     :target: https://pypi.python.org/pypi/LowVoltage
 
-.. image:: https://pypip.in/egg/LowVoltage/badge.svg
-    :target: https://pypi.python.org/pypi/LowVoltage
-
-.. image:: https://pypip.in/wheel/LowVoltage/badge.svg
-    :target: https://pypi.python.org/pypi/LowVoltage
-
 .. image:: https://img.shields.io/github/issues/jacquev6/LowVoltage.svg
     :target: https://github.com/jacquev6/LowVoltage/issues
 
@@ -39,20 +38,31 @@ LowVoltage is a standalone Python (2 and 3) client for DynamoDB that doesn't hid
 .. image:: https://img.shields.io/github/stars/jacquev6/LowVoltage.svg
     :target: https://github.com/jacquev6/LowVoltage/stargazers
 
+Quick start
+===========
 
-Why?
-====
+Install from PyPI::
+
+    $ pip install LowVoltage
+
+Import the package and create a connection:
+
+.. doctest::
+
+    >>> from LowVoltage import *
+    >>> connection = make_connection("eu-west-1", EnvironmentCredentials())
+
+Assuming you have a table named "LowVoltage.DocTests" with a hash key on the number attribute "h", you can put an item and get it back:
+
+.. doctest::
 
-- I wanted to learn DynamoDB
-- I found out Boto is (was?) not up-to-date with newer API parameters and does (did?) not support Python 3
-- I had some time
+    >>> table = "LowVoltage.DocTests"
 
-Tenets
-======
+    >>> connection(PutItem(table, {"h": 0, "a": 42, "b": u"bar"}))
+    <LowVoltage.actions.put_item.Result object at ...>
 
-- Users should be able to do everything that is permited by `the API <http://docs.aws.amazon.com/amazondynamodb/latest/APIReference>`__.
-- Users should never risk a typo: we provide symbols for all DynamoDB constants.
-- Users should never have to use deprecated API parameters.
+    >>> connection(GetItem(table, {"h": 0})).item
+    {u'a': 42, u'h': 0, u'b': u'bar'}
 
 Todo
 ====

doc/conf.py

@@ -3,7 +3,6 @@
 # Copyright 2014-2015 Vincent Jacques <vincent@vincent-jacques.net>
 
 import textwrap
-import alabaster
 
 
 master_doc = "index"
@@ -15,14 +14,19 @@
 
 # https://github.com/bitprophet/alabaster
 # html_theme_path
-extensions.append('alabaster')
-html_theme = 'alabaster'
+extensions.append("alabaster")
+html_theme = "alabaster"
 html_sidebars = {
-    '**': [
-        'about.html', 'navigation.html', 'searchbox.html',
+    "**": [
+        "about.html", "navigation.html", "searchbox.html",
     ]
 }
-
+html_theme_options = {
+    "github_user": "jacquev6",
+    "github_repo": "LowVoltage",
+    "github_banner": True,
+    "travis_button": True,
+}
 
 # http://sphinx-doc.org/ext/autodoc.html
 extensions.append("sphinx.ext.autodoc")

doc/index.rst

@@ -2,39 +2,7 @@
 LowVoltage
 ==========
 
-LowVoltage is a Python (2 and 3) client for `DynamoDB <http://aws.amazon.com/documentation/dynamodb/>`__
-that doesn't hide any feature of `the API <http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/Welcome.html>`__.
-
-It's licensed under the `MIT license <http://choosealicense.com/licenses/mit/>`__.
-
-It depends only on the excellent `python-requests <http://python-requests.org>`__ library.
-It's available on the `Python package index <http://pypi.python.org/pypi/LowVoltage>`__ and the source code is on `GitHub <https://github.com/jacquev6/LowVoltage>`__.
-
-Quick start
-===========
-
-Install from PyPI::
-
-    $ pip install LowVoltage
-
-Import the package and create a connection:
-
-.. doctest::
-
-    >>> from LowVoltage import *
-    >>> connection = make_connection("eu-west-1", EnvironmentCredentials())
-
-Assuming you have a table named "LowVoltage.DocTests" with a hash key on the number attribute "h", you can put an item and get it back:
-
-.. doctest::
-
-    >>> table = "LowVoltage.DocTests"
-
-    >>> connection(PutItem(table, {"h": 0, "a": 42, "b": u"bar"}))
-    <LowVoltage.actions.put_item.Result object at ...>
-
-    >>> connection(GetItem(table, {"h": 0})).item
-    {u'a': 42, u'h': 0, u'b': u'bar'}
+.. include:: ../README.rst
 
 Contents
 ========

doc/reference.rst

@@ -2,9 +2,47 @@
 Reference
 =========
 
+.. automodule:: LowVoltage
+
+Connection
+==========
+
+.. automodule:: LowVoltage.connection
+
+Credentials
+-----------
+
+@todo Link to user guide (authentication).
+
+.. automodule:: LowVoltage.connection.credentials
+
+Retry policies
+--------------
+
+@todo Link to user guide (error management).
+
+.. automodule:: LowVoltage.connection.retry_policies
+
+Attribute types
+===============
+
+.. automodule:: LowVoltage.attribute_types
+
+Exceptions
+==========
+
+@todo Link to user guide (error management).
+
+.. toctree::
+
+    reference/exceptions
+
 Actions
 =======
 
+@todo Link to user guide (action/compound).
+@todo In actions that have a compound, link to this compound.
+
 Admin actions
 -------------
 
@@ -38,6 +76,8 @@ Batch actions
 Compounds
 =========
 
+@todo Link to user guide (action/compound).
+
 .. toctree::
 
     reference/compounds/batch_get_item_iterator

doc/reference/exceptions.rst

@@ -0,0 +1,4 @@
+Exceptions
+==========
+
+.. automodule:: LowVoltage.exceptions

doc/user_guide.rst

@@ -5,9 +5,20 @@ User guide
 Introduction
 ============
 
+Why?
+====
+
+- I wanted to learn DynamoDB
+- I found out Boto is (was?) not up-to-date with newer API parameters and does (did?) not support Python 3
+- I had some time
+
 Tenets
 ======
 
+- Users should be able to do everything that is permited by `the API <http://docs.aws.amazon.com/amazondynamodb/latest/APIReference>`__.
+- Users should never risk a typo: we provide symbols for all DynamoDB constants.
+- Users should never have to use deprecated API parameters.
+
 Everything is available in top-level module
 ===========================================
 

setup.py

@@ -27,8 +27,6 @@
         "Programming Language :: Python :: 2",
         "Programming Language :: Python :: 2.7",
         "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.2",
-        "Programming Language :: Python :: 3.3",
         "Programming Language :: Python :: 3.4",
         "Environment :: Web Environment",
     ],