Updating docs for Python 3

doc/changes.rst

@@ -1,3 +1,8 @@
+0.2.0
+-----
+* Feature: Support Python 3.2 and 3.3
+* Breakage: Removing S3Type (no longer have boto as dependency)
+
 0.1.1
 -----
 * Bug fix: Can call ``incr_()`` on models that have not been saved yet (:sha:`0a1990f`)

doc/conf.py

@@ -37,7 +37,6 @@
 numpydoc_show_class_members = False
 intersphinx_mapping = {
     'python': ('http://docs.python.org/', None),
-    'boto': ('http://boto.readthedocs.org/en/latest/', None),
 }
 
 

doc/ref/flywheel.compat.rst

@@ -0,0 +1,7 @@
+flywheel.compat module
+======================
+
+.. automodule:: flywheel.compat
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/ref/flywheel.rst

@@ -13,6 +13,7 @@ Submodules
 
 .. toctree::
 
+   flywheel.compat
    flywheel.engine
    flywheel.model_meta
    flywheel.models

doc/topics/crud.rst

@@ -47,7 +47,7 @@ type. The results won't have all of the item's fields, so you can call
 Get
 ---
 Fetch an item from its primary key fields. This will be faster than a query,
-but requires you to know the primary key/keys of all items you want fetched.
+but requires you to know the primary keys of all items you want fetched.
 
 .. code-block:: python
 

doc/topics/develop.rst

@@ -4,15 +4,15 @@ To get started developing flywheel, run the following command:
 
 .. code-block:: bash
 
-    wget https://raw.github.com/mathcamp/devbox/master/devbox/unbox.py && \
+    wget https://raw.github.com/mathcamp/devbox/0.1.0/devbox/unbox.py && \
     python unbox.py git@github.com:mathcamp/flywheel
 
 This will clone the repository and install the package into a virtualenv
 
 Running Tests
 -------------
-The command to run tests is ``python setup.py nosetests``. Most of these tests
-require `DynamoDB Local
+The command to run tests is ``python setup.py nosetests``, or ``tox``. Most of
+these tests require `DynamoDB Local
 <http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.html>`_.
 There is a nose plugin that will download and run the DynamoDB Local service
 during the tests. It requires the java 6/7 runtime, so make sure you have that

doc/topics/getting_started.rst

@@ -29,9 +29,7 @@ Here are the steps to set up a simple example model with flywheel:
 
     # Create an engine and connect to an AWS region
     engine = Engine()
-    engine.connect_to_region('us-east-1',
-                             aws_access_key_id=<YOUR AWS ACCESS KEY>,
-                             aws_secret_access_key=<YOUR AWS SECRET KEY>)
+    engine.connect_to_region('us-east-1')
 
     # Register our model with the engine so it can create the Dynamo table
     engine.register(Tweet)

doc/topics/models/basics.rst

@@ -16,7 +16,7 @@ The model declares the fields an object has, their :ref:`data
 types<data_types>`, and the :ref:`schema <schema>` of the table.
 
 Since DynamoDB is a NoSQL database, you can attach arbitrary additional fields
-to the model, and they will be stored appropriately. For example, this tweet
+to the model and they will be stored appropriately. For example, this tweet
 doesn't declare a ``retweets`` field, but you could assign it anyway:
 
 .. code-block:: python
@@ -32,10 +32,11 @@ metadata about the model. This metadata object has the :meth:`create
 
 .. code-block:: python
 
-    from boto.dynamodb2 import connect_to_region
+    from dynamo3 import DynamoDBConnection
 
-    connection = connect_to_region('us-east-1')
+    connection = DynamoDBConnection.connect_to_region('us-east-1')
     Tweet.meta_.create_dynamo_schema(connection)
+    Tweet.meta_.delete_dynamo_schema(connection)
 
 You can also register your models with the engine and create all the tables at once:
 

doc/topics/models/data_types.rst

@@ -30,31 +30,31 @@ special notes. For more information, the code for data types is located in
 :mod:`~flywheel.fields.types`.
 
 
-+----------+-------------+---------------------------------------------------------------+
-| Type     | Dynamo Type | Description                                                   |
-+==========+=============+===============================================================+
-| unicode  | STRING      | Basic STRING type. This is the default for fields             |
-+----------+-------------+---------------------------------------------------------------+
-| str      | BINARY      |                                                               |
-+----------+-------------+---------------------------------------------------------------+
-| int      | NUMBER      | Enforces integer constraint on data                           |
-+----------+-------------+---------------------------------------------------------------+
-| float    | NUMBER      |                                                               |
-+----------+-------------+---------------------------------------------------------------+
-| set      | \*_SET      | This will use the appropriate type of DynamoDB set            |
-+----------+-------------+---------------------------------------------------------------+
-| bool     | NUMBER      |                                                               |
-+----------+-------------+---------------------------------------------------------------+
-| datetime | NUMBER      | datetimes MUST be provided in UTC                             |
-+----------+-------------+---------------------------------------------------------------+
-| date     | NUMBER      | dates MUST be provided in UTC                                 |
-+----------+-------------+---------------------------------------------------------------+
-| Decimal  | NUMBER      | If you need decimal precision in your application             |
-+----------+-------------+---------------------------------------------------------------+
-| dict     | STRING      | Stored as json-encoded string                                 |
-+----------+-------------+---------------------------------------------------------------+
-| list     | STRING      | Stored as json-encoded string                                 |
-+----------+-------------+---------------------------------------------------------------+
++----------+----------+-------------+---------------------------------------------------------------+
+| PY2 Type | PY3 Type | Dynamo Type | Description                                                   |
++==========+==========+=============+===============================================================+
+| unicode  | str      | STRING      | Basic STRING type. This is the default for fields             |
++----------+----------+-------------+---------------------------------------------------------------+
+| str      | bytes    | BINARY      | Binary data, (serialized objects, compressed data, etc)       |
++----------+----------+-------------+---------------------------------------------------------------+
+| int/long | int      | NUMBER      | Enforces integer constraint on data                           |
++----------+----------+-------------+---------------------------------------------------------------+
+| float    |          | NUMBER      |                                                               |
++----------+----------+-------------+---------------------------------------------------------------+
+| set      |          | \*_SET      | This will use the appropriate type of DynamoDB set            |
++----------+----------+-------------+---------------------------------------------------------------+
+| bool     |          | NUMBER      |                                                               |
++----------+----------+-------------+---------------------------------------------------------------+
+| datetime |          | NUMBER      | datetimes will be treated as naïve. UTC recommended.          |
++----------+----------+-------------+---------------------------------------------------------------+
+| date     |          | NUMBER      | dates will be treated as naïve. UTC recommended.              |
++----------+----------+-------------+---------------------------------------------------------------+
+| Decimal  |          | NUMBER      |                                                               |
++----------+----------+-------------+---------------------------------------------------------------+
+| dict     |          | STRING      | Stored as json-encoded string                                 |
++----------+----------+-------------+---------------------------------------------------------------+
+| list     |          | STRING      | Stored as json-encoded string                                 |
++----------+----------+-------------+---------------------------------------------------------------+
 
 If you attempt to set a field with a type that doesn't match, it will raise a
 ``TypeError``.  If a field was created with ``coerce=True`` it will first
@@ -64,10 +64,10 @@ you.
 
 .. note::
 
-    Certain fields will auto-coerce specific data types. For example, a ``str``
-    field will auto-encode a ``unicode`` to utf-8 even if ``coerce=False``.
-    Similarly, a ``unicode`` field will auto-decode a ``str`` value to a
-    unicode string.
+    Certain fields will auto-coerce specific data types. For example, a
+    ``bytes`` field will auto-encode a ``unicode`` to utf-8 even if
+    ``coerce=False``.  Similarly, a ``unicode`` field will auto-decode a
+    ``bytes`` value to a unicode string.
 
 .. warning::
 
@@ -135,7 +135,7 @@ store any python object in pickled format.
             return value
 
         def ddb_dump(self, value):
-            # Pickle and convert to a Binary object for boto
+            # Pickle and convert to a Binary object
             return Binary(pickle.dumps(value))
 
         def ddb_load(self, value):

doc/topics/models/schema.rst

@@ -16,7 +16,7 @@ unique identifier for each object.
 **Local Secondary Indexes**: Optional, up to 5. You may only use these if your
 table has a range key. These fields are indexed in a similar fashion as the
 range key. You may also query against them within a specific hash key. You can
-think of these as a range key with no uniqueness requirements.
+think of these as range keys with no uniqueness requirements.
 
 **Global Secondary Indexes**: Optional, up to 5. These indexes have a hash key
 and optional range key, and can be put on any declared field. This allows you
@@ -34,7 +34,8 @@ Example declaration of hash and range key:
         userid = Field(hash_key=True)
         ts = Field(data_type=datetime, range_key=True)
 
-For this version of a Tweet, each ``(userid, ts)`` pair is a unique value.
+For this version of a Tweet, each ``(userid, ts)`` pair is a unique value. The
+Dynamo table will be sharded across userids.
 
 Local Secondary Indexes
 -----------------------
@@ -44,9 +45,9 @@ optimize how much additional storage is used. The projection types are:
 
 **All**: All fields are projected into the index
 
-**Keys only**: Only the primary key and indexed keys are project into the index
+**Keys only**: Only the primary key and indexed keys are projected into the index
 
-**Include**: Like the "Keys only" projection, but allows you to specify
+**Include**: Like the "keys only" projection, but allows you to specify
 additional fields to project into the index
 
 This is how they it looks in the model declaration:
@@ -80,13 +81,11 @@ can be specified in the model declaration. Here are some examples below:
     class Tweet(Model):
         __metadata__ = {
             'global_indexes': [
-                GlobalIndex.all('ts-index', 'city', 'ts').throughput(read=10,
-                                                                     write=2),
+                GlobalIndex.all('ts-index', 'city', 'ts').throughput(read=10, write=2),
                 GlobalIndex.keys('rt-index', 'city', 'retweets')\
                         .throughput(read=10, write=2),
                 GlobalIndex.include('like-index', 'city', 'likes',
-                                    includes=['text']).throughput(read=10,
-                                                                  write=2),
+                                    includes=['text']).throughput(read=10, write=2),
             ],
         }
         userid = Field(hash_key=True)

doc/topics/queries.rst

@@ -3,10 +3,10 @@
 Table Queries
 =============
 The query syntax is heavily inspired by `SQLAlchemy <http://www.sqlalchemy.org/>`_.
-In DynamoDB, queries must use one of the table's indexes. Queries may only
-query across a single hash key. This means that for a query there will always
-be at least one call to ``filter`` which will, at a minimum, set the hash key
-to search on.
+In DynamoDB, queries must use one of the table's indexes. Queries are
+constrained to a single hash key value. This means that for a query there will
+always be at least one call to ``filter`` which will, at a minimum, set the
+hash key to search on.
 
 .. code-block:: python
 
@@ -22,7 +22,7 @@ You may also use inequality filters on range keys and secondary indexes
     engine.query(Tweet).filter(Tweet.userid == 'abc123',
                                Tweet.ts >= earlyts).all()
 
-There are two final statements that will return all results:
+There are two finalizing statements that will return all results:
 :meth:`~flywheel.engine.Query.all` and :meth:`~flywheel.engine.Query.gen`.
 Calling :meth:`~flywheel.engine.Query.all` will return a list of results.
 Calling :meth:`~flywheel.engine.Query.gen` will return a generator. If your
@@ -38,7 +38,7 @@ memory at the same time.
     for tweet in all_tweets:
         retweets += tweet.retweets
 
-there are two final statements that retrieve a single item:
+there are two finalizing statements that retrieve a single item:
 :meth:`~flywheel.engine.Query.first` and :meth:`~flywheel.engine.Query.one`.
 Calling :meth:`~flywheel.engine.Query.first` will return the first element of
 the results, or None if there are no results. Calling
@@ -90,11 +90,11 @@ you want the results to be sorted by a particular index:
         retweets = Field(data_type=int, index='rt-index')
 
     # Get the 10 most retweeted tweets for a user
-    top_ten = engine.query(Tweet).filter(id='abc123').index('rt-index')\
+    top_ten = engine.query(Tweet).filter(userid='abc123').index('rt-index')\
             .limit(10).all(desc=True)
 
     # Get The 10 most recent tweets for a user
-    top_ten = engine.query(Tweet).filter(id='abc123').index('ts-index')\
+    top_ten = engine.query(Tweet).filter(userid='abc123').index('ts-index')\
             .limit(10).all(desc=True)
 
 Shorthand

flywheel/fields/types.py

@@ -244,6 +244,7 @@ class IntType(TypeDefinition):
 
     """ Integer values (includes longs) """
     data_type = int
+    aliases = list(six.integer_types)
     ddb_data_type = NUMBER
 
     def coerce(self, value, force):