flask-dynamo Documentation

Transcription

1 flask-dynamo Documentation Release Randall Degges January 22, 2018

2

3 Contents 1 User s Guide Quickstart Getting Help Contributing API Reference API Additional Notes Change Log Upgrade Guide Python Module Index 15 i

4 ii

5 flask-dynamo is an extension for Flask that makes using Amazon s DynamoDB NoSQL database incredibly simple and enjoyable. DynamoDB is my favorite NoSQL database, as it s fast, scalable, requires 0 maintenance, has a simple API, and is a joy to work with. Contents 1

6 2 Contents

7 CHAPTER 1 User s Guide This part of the documentation will show you how to get started with flask-dynamo. If you re a new flask-dynamo user, start here! Quickstart This section will guide you through everything you need to know to get up and running with flask-dynamo! Installation The first thing you need to do is install flask-dynamo. Installation can be done through pip, the Python package manager. To install flask-dynamo, run: $ pip install flask-dynamo If you d like to upgrade an existing installation of flask-dynamo to the latest release, you can run: $ pip install -U flask-dynamo Set Environment Variables In order to run properly, flask-dynamo requires that you set several environment variables. The required environment variables are: AWS_ACCESS_KEY_ID (your Amazon access key ID) AWS_SECRET_ACCESS_KEY (your Amazon secret access key) There are also optional variables you can set: AWS_REGION (defaults to us-east-1) DYNAMO_ENABLE_LOCAL (defaults to False) DYNAMO_LOCAL_HOST (defaults to None) DYNAMO_LOCAL_PORT (defaults to None) 3

8 These credentials can be grabbed from your AWS Console. Note: A full list of Amazon regions can be found here: If you re unsure of how to set environment variables, I recommend you check out this StackOverflow question. Specify Your Tables The next thing you need to do is tell flask-dynamo which tables you ll be using. If you re not sure how tables work with DynamoDB, you should read through the boto DynamoDB tutorial before continuing. The way you can specify your tables is by creating an array called DYNAMO_TABLES (this is what flask-dynamo uses to set everything up). Below is an example: # app.py from flask import Flask from flask_dynamo import Dynamo app = Flask( name ) app.config[ DYNAMO_TABLES ] = [ { TableName= users, KeySchema=[dict(AttributeName= username, KeyType= HASH )], AttributeDefinitions=[dict(AttributeName= username, AttributeType= S )], ProvisionedThroughput=dict(ReadCapacityUnits=5, WriteCapacityUnits=5) }, { TableName= groups, KeySchema=[dict(AttributeName= name, KeyType= HASH )], AttributeDefinitions=[dict(AttributeName= name, AttributeType= S )], ProvisionedThroughput=dict(ReadCapacityUnits=5, WriteCapacityUnits=5) } ] In the above example, I m defining two DynamoDB tables: users and groups, along with their respective schemas. flask-dynamo will respect any boto tables you define it will also respect any of the other fields you specify on your tables. Initialize Dynamo Now that you ve defined your tables, you can initialize flask-dynamo in your app. All you need to do is pass your app to the Dynamo constructor: # app.py from flask import Flask from flask_dynamo import Dynamo app = Flask( name ) app.config[ DYNAMO_TABLES ] = [ { TableName= users, 4 Chapter 1. User s Guide

9 ] }, { } KeySchema=[dict(AttributeName= username, KeyType= HASH )], AttributeDefinitions=[dict(AttributeName= username, AttributeType= S )], ProvisionedThroughput=dict(ReadCapacityUnits=5, WriteCapacityUnits=5) TableName= groups, KeySchema=[dict(AttributeName= name, KeyType= HASH )], AttributeDefinitions=[dict(AttributeName= name, AttributeType= S )], ProvisionedThroughput=dict(ReadCapacityUnits=5, WriteCapacityUnits=5) dynamo = Dynamo(app) If you use the app factory pattern then use: # app.py from flask import Flask from flask_dynamo import Dynamo def create_app(): app = Flask( name ) app.config[ DYNAMO_TABLES ] = [ { TableName= users, KeySchema=[dict(AttributeName= username, KeyType= HASH )], AttributeDefinitions=[dict(AttributeName= username, AttributeType= S )], ProvisionedThroughput=dict(ReadCapacityUnits=5, WriteCapacityUnits=5) }, { TableName= groups, KeySchema=[dict(AttributeName= name, KeyType= HASH )], AttributeDefinitions=[dict(AttributeName= name, AttributeType= S )], ProvisionedThroughput=dict(ReadCapacityUnits=5, WriteCapacityUnits=5) } ] dynamo = Dynamo() dynamo.init_app(app) return app app = create_app() From this point on, you can interact with DynamoDB through the global dynamo object, or through Flask.current_app.extensions[ dynamodb ] if you are using the Flask app factory pattern. Create Your Tables If you haven t already created your DynamoDB tables, flask-dynamo can help you out! After configuring flask-dynamo, you can use the following code snippet to create all of your predefined DynamoDB tables: with app.app_context(): dynamo.create_all() This works great in bootstrap scripts Quickstart 5

10 Working with Tables Now that you ve got everything setup, you can easily access your tables in a dictionary-like format through dynamo.tables. Below is an example view which creates a new user account: # /create_user ) def create_user(): dynamo.tables[ users ].put_item(data={ username : rdegges, first_name : Randall, last_name : Degges, r@rdegges.com, }) On a related note, you can also use the dynamo.tables dictionary to iterate through all of your tables (this is sometimes useful). Here s how you could iterate over your existing DynamoDB tables: # app.py for table_name, table in dynamo.tables.items(): print(table_name, table) Deleting Tables If, for some reason, you d like to destroy all of your predefined DynamoDB tables, flask-dynamo can also help you with that. The below code snippet will destroy all of your predefined DynamoDB tables: # app.py dynamo.destroy_all() Note: data! Please be extremely careful when running this it has the potential to completely destroy your application s Using DynamoDB Local If you d like to use a local DynamoDB instance, flask-dynamo can help you. The only change you need to make is to your configuration. By specifying a few extra configuration variables, you ll be able to connect to your local DynamoDB instance as opposed to the real AWS cloud service this is great for testing things out. For more information about DynamoDB local, read the official DynamoDB Local documentation. The settings you need to set are: DYNAMO_ENABLE_LOCAL - Set this to True. DYNAMO_LOCAL_HOST - Set this to your local DB hostname usually localhost. DYNAMO_LOCAL_PORT - Set this to your local DB port usually Chapter 1. User s Guide

11 The settings above can be specified in one of two ways, either via environment variables, or via application configuration options directly, eg: app.config[ DYNAMO_ENABLE_LOCAL ] = True app.config[ DYNAMO_LOCAL_HOST ] = localhost app.config[ DYNAMO_LOCAL_PORT ] = 8000 No other code needs to be changed in order to use DynamoDB Local. Specifying boto3 Session If you would like to specify the boto3 session that Flask-dynamo should use, flask-dynamo has an option in the app config. This is optional, and if you don t specify a session, flask-dynamo will create one for you. This may be useful if you want to reuse the boto3 session with multiple plugins. DYNAMO_SESSION - optional Sets the boto3 session that flask-dynamo should use. eg: from boto3.session import Session() boto_sess = Session( region_name= us-east-1, aws_access_key_id= example_key_id, aws_secret_access_key= my_super_secret_key ) app.config[ DYNAMO_SESSION ] = boto_sess Getting Help Have a question you can t find an answer to? Things not working as expected? If you ve found a bug, or think something might not be working correctly, please file an issue on the official flaskdynamo issue tracker. If you need specific help getting something working, please me directly: r@rdegges.com or send me a -Randall Contributing Want to contribute to flask-dynamo? AWESOME! There s only a few things you need to know to get started: 1. All development is done on the Github repo. 2. When you send a pull request, please send it to the develop branch this is where active development happens. 3. Please add tests if you can it ll make accepting your pull requests a lot easier! That s about it! Setup Your Environment To get started developing, you ll want to fork flask-dynamo on Github Getting Help 7

12 After that, you ll need to check out the develop branch, as this is where you should base your development from: $ git clone git@github.com:yourusername/flask-dynamo.git $ cd flask-dynamo $ git fetch origin develop:develop $ git checkout develop Next, create a new branch that describes the change you want to make: $ git checkout -b bug-fix Next, you ll want to install all of the local dependencies with pip: $ pip install -r requirements.txt After that, you ll want to install the flask-dynamo package in development mode: $ python setup.py develop Lastly, you ll want to configure your AWS access keys as environment variables so you can run the tests: $ export AWS_ACCESS_KEY_ID=xxx $ export AWS_SECRET_ACCESS_KEY=xxx Running Tests After writing some code, you ll need to run the tests to ensure everything is still working ok! This can be done by running: $ python setup.py test From the project s root directory. Note: The tests take a while to run this is on purpose, as Amazon rate limits your requests. Submitting Your Pull Request Now that you ve added an awesome feature or fixed a bug, you probably want to submit your pull request, so let s do it! First, you ll want to push your topic branch to your Github fork: $ git push origin bug-fix Then, go to Github on your fork, and submit a pull request from your topic branch into the develop branch on the main flask-dynamo repository. That s it! Thanks! I d also like to give you a big shout out for any contributions you make. You are totally fucking awesome and I love you. -Randall 8 Chapter 1. User s Guide

13 CHAPTER 2 API Reference If you are looking for information on a specific function, class or method, this part of the documentation is for you. API This part of the documentation documents all the public classes, functions, and API details in flask-dynamo. This documentation is auto generated, and is always a good up-to-date reference. Configuration class flask_dynamo.manager.dynamo(app=none) DynamoDB engine manager. init_app(app) Initialize this extension. Parameters app (obj) The Flask application. connection Our DynamoDB connection. This will be lazily created if this is the first time this is being accessed. This connection is reused for performance. DynamoLazyTables = None get_table(table_name) create_all(wait=false) Create all user-specified DynamoDB tables. We ll ignore table(s) that already exists. We ll error out if the tables can t be created for some reason. destroy_all(wait=false) Destroy all user-specified DynamoDB tables. We ll error out if the tables can t be destroyed for some reason. class flask_dynamo.manager.dynamolazytables(connection, table_config) Manages access to Dynamo Tables. keys() The table names in our config. 9

14 len() The number of tables we are configured for. items() The table tuples (name, connection.table()). wait_exists(table_name) wait_not_exists(table_name) create_all(wait=false) destroy_all(wait=false) Errors class flask_dynamo.errors.configurationerror This exception is raised if the user hasn t properly configured Flask-Dynamo. 10 Chapter 2. API Reference

15 CHAPTER 3 Additional Notes This part of the documentation covers changes between versions and upgrade information, to help you migrate to newer versions of flask-dynamo easily. flask-dynamo is in the public domain (UNLICENSE), so you can do whatever you want with it! Change Log All library changes, in descending order. Version Released on September 6, Fixing init issues. Version Released on August 21, Added support for shared boto3 session. Version Released on August 21, Added support for flask app factory and traditional methods of initialization. Added documentation for boto3. Fixed reuse of DynamoDB connections across requests. Optimized tests to run faster. Added support for AWS_SESSION_TOKEN. for the code! 11

16 Version Released on August 1, Improving the create_all management command so it won t error out when attempting to re-create already created tables. for the codez! Version Released on May 25, Fixing deferred initialization of app object. for the fix! Version Released on March 29, Allowing users to specify DYNAMO_TABLES dynamically =) This makes it possible to specify your tables dynamically instead of immediately at startup. Version Released on March 29, Merging PR for improved environment variable detection using boto. We ll now allow the user to configure Flask-Dynamo through all of the standard boto methods. Version Released on November 17, Adding support for DynamoDB Local! Version Released on November 17, Fixing packaging issues with import ordering. for the report! Version Released on June 21, Adding tests. Adding docs. Adding logo. Slight refactoring. 12 Chapter 3. Additional Notes

17 Version Released on June 21, First release! Basic functionality. Upgrade Guide This page contains specific upgrading instructions to help you migrate between flask-dynamo releases. Version > Version No changes needed! Version > Version No changes needed! Version > Version Changes required. The app.config[ DYNAMO_TABLES ] schema needs to be updated to boto3 style. See Specify Your Tables for examples of how to do this. OPTIONAL: Use the app factory pattern, and access Dynamo via Flask.current_app.extensions[ dynamodb ] Version > Version No changes needed! Version > Version No changes needed! Version > Version No changes needed! Version > Version No changes needed! 3.2. Upgrade Guide 13

18 Version > Version No changes needed! Version > Version No changes needed! Version > Version No changes needed! 14 Chapter 3. Additional Notes

19 Python Module Index f flask_dynamo, 3 flask_dynamo.errors, 10 flask_dynamo.manager, 9 15

20 16 Python Module Index

21 Index C ConfigurationError (class in flask_dynamo.errors), 10 connection (flask_dynamo.manager.dynamo attribute), 9 create_all() (flask_dynamo.manager.dynamo method), 9 create_all() (flask_dynamo.manager.dynamolazytables method), 10 D destroy_all() (flask_dynamo.manager.dynamo method), 9 destroy_all() (flask_dynamo.manager.dynamolazytables method), 10 Dynamo (class in flask_dynamo.manager), 9 DynamoLazyTables (class in flask_dynamo.manager), 9 DynamoLazyTables (flask_dynamo.manager.dynamo attribute), 9 F flask_dynamo (module), 3 flask_dynamo.errors (module), 10 flask_dynamo.manager (module), 9 G get_table() (flask_dynamo.manager.dynamo method), 9 I init_app() (flask_dynamo.manager.dynamo method), 9 items() (flask_dynamo.manager.dynamolazytables method), 10 K keys() L len() (flask_dynamo.manager.dynamolazytables method), 9 (flask_dynamo.manager.dynamolazytables method), 9 W wait_exists() (flask_dynamo.manager.dynamolazytables method), 10 wait_not_exists() (flask_dynamo.manager.dynamolazytables method), 10 17