-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Possibly a more drastic rewrite of docs #13
Comparing the previous documentation to other projects (especially pytest, flask) I think I was trying to cover absolutely every aspect, in as much detail as possible. That seemed reasonable at the time, because I'm familiar with the code. Stepping back, it seems unapproachable in its sudden depth. I'm going to try another approach that walks through different options as users might discover them. That also means staying away from "this is how DynamoDB works" as much as possible. That can live in a section in the future if it's something people want.
- Loading branch information
1 parent
df620a3
commit 027af9e
Showing
16 changed files
with
151 additions
and
3,500 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,136 @@ | ||
Defining Models | ||
^^^^^^^^^^^^^^^ | ||
|
||
To start, you'll need to create a base class that your models inherit from: | ||
|
||
.. code-block:: python | ||
from bloop import new_base | ||
BaseModel = new_base() | ||
Add some columns to your model. You'll need at least a hash key: | ||
|
||
.. code-block:: python | ||
from bloop import Column, DateTime, String, UUID | ||
class User(BaseModel): | ||
id = Column(UUID, hash_key=True) | ||
email = Column(String) | ||
created_on = Column(DateTime) | ||
Finally, bind the model to an Engine to create the table: | ||
|
||
.. code-block:: python | ||
from bloop import Engine | ||
engine = Engine() | ||
engine.bind(User) | ||
======== | ||
Metadata | ||
======== | ||
|
||
You can customize how the table is created with an inner ``Meta`` class: | ||
|
||
.. code-block:: python | ||
class Tweet(BaseModel): | ||
class Meta: | ||
table_name = "custom_table_name" | ||
read_units = 1000 | ||
write_units = 300 | ||
user = Column(Integer, hash_key=True) | ||
created = Column(DateTime, range_key=True) | ||
Available properties: | ||
|
||
**table_name** | ||
| *(default is class name)* | ||
| The table name in DynamoDB. | ||
**read_units** | ||
| *(default is 1)* | ||
| The provisioned read units for the table. | ||
**write_units** | ||
| *(default is 1)* | ||
| The provisioned write units for the table. | ||
======= | ||
Columns | ||
======= | ||
|
||
.. code-block:: python | ||
Column(typedef, hash_key=False, range_key=False, name=None, **kwargs) | ||
**hash_key** | ||
|
||
----- | ||
Types | ||
----- | ||
|
||
Each ``Column`` must have a type. The built-in types are:: | ||
|
||
String | ||
UUID | ||
DateTime | ||
Float | ||
Integer | ||
Binary | ||
Boolean | ||
Set | ||
List | ||
TypedMap | ||
Map | ||
|
||
Many types can be passed directly without instantiating. These are equivalent: | ||
|
||
.. code-block:: python | ||
Column(String) | ||
Column(String()) | ||
Column(DateTime) | ||
Column(DateTime(timezone="utc")) | ||
Column(Float) | ||
Column(Float()) | ||
Set, List, and TypedMap require an inner type. Bloop requires type information for List and Map because there isn't | ||
enough type information when loading values from DynamoDB to determine the type to use. | ||
|
||
.. code-block:: python | ||
Column(Set(DateTime)) | ||
Column(Set(Integer)) | ||
Column(Set(Binary)) | ||
Column(List(Boolean)) | ||
Column(TypedMap(Integer)) | ||
----------------- | ||
Hash & Range Keys | ||
----------------- | ||
|
||
Every model needs a hash key; you may optionally include a range key. These are specified with the ``hash_key`` and | ||
``range_key`` kwargs: | ||
|
||
.. code-block:: python | ||
id = Column(Integer, hash_key=True) | ||
----- | ||
Names | ||
----- | ||
|
||
DynamoDB includes column names when computing item sizes. Instead of shortening ``created_on`` to ``c`` in the model, | ||
bloop exposes a ``name`` kwarg to map the model name to a different DynamoDB name: | ||
|
||
.. code-block:: python | ||
created_on = Column(DateTime, name="c") |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
Save and Delete Objects | ||
^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
||
Create some stuff, delete some stuff. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
Query and Scan | ||
^^^^^^^^^^^^^^ |
Oops, something went wrong.