Giter Site home page Giter Site logo

teracyhq-incubator / flask-boilerplate Goto Github PK

View Code? Open in Web Editor NEW
10.0 3.0 6.0 153 KB

Boilerplate to speed up Flask development with best practices.

License: BSD 3-Clause "New" or "Revised" License

Shell 0.41% Python 98.92% Makefile 0.31% HTML 0.15% Mako 0.21%

flask-boilerplate's Introduction

flask-boilerplate

Boilerplate to speedup flask development with best practices.

Project Status

  • develop branch:

Heroku deployment: https://flbp.herokuapp.com/

Build Status Coverage Status

  • master branch:

Build Status Coverage Status

Installation

Use teracy-dev: http://dev.teracy.org/docs/getting_started.html

Then:

$ ws
$ cd personal
$ git clone [email protected]:teracyhq/flask-boilerplate.git
$ cd flask-boilerplate
$ mkvirtualenv flask-boilerplate
$ make resolve

Configuration

See flask-boilerplate/app/config.py

Usage

Run

$ python manage.py db setup
$ python manage.py runserver -h 0.0.0.0

Then open: http://localhost:5000/ to see how the app works.

Test

$ make test-unit

to run unit tests

or:

$ make test-intg

to run integration tests

or:

$ make test

to run both unit and integration tests

after that, $ make report-coverage to see coverage report.

Style

$ make check-style

to check pep8, pylint styles.

REST APIs

Flask-Boilerplate focuses on REST APIs driven development. There are built-in endpoints of users and roles.

We use HTTPie and httpie-jwt-auth plugin for testing.

To install HTTPie and httpie-jwt-auth, please follow:

$ pip install --upgrade httpie
$ pip install --upgrade httpie-jwt-auth

Note: should use sudo to install for system wide usage.

after that: $ http --version should print out: 0.9.2 or something similar on the screen.

/api/versions

$ http :5000/api/versions -v
GET /api/versions HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:5000
User-Agent: HTTPie/0.9.2



HTTP/1.0 200 OK
Content-Length: 302
Content-Type: application/json; charset=utf-8
Date: Tue, 25 Aug 2015 18:02:02 GMT
Server: Werkzeug/0.10.4 Python/2.7.6
Set-Cookie: session=eyJfaWQiOnsiIGIiOiJOakZoTXpKaU5tTXpZelpqWlRReFpEWmtPRFUxTlRrM1pqazFPRFU0TWpFPSJ9fQ.CL4_Gg.EHh4Ipnc24t_maZ29rkNPxFEYhU; HttpOnly; Path=/

{
    "latest": {
        "info": "developing version, APIs are expected to change and break things", 
        "status": "@", 
        "version": "v1.0"
    }, 
    "supported": [
        {
            "info": "developing version, APIs are expected to change and break things", 
            "status": "@", 
            "version": "v1.0"
        }
    ]
}

/api/v1.0/users

  • To create a new user:
$ http POST :5000/api/v1.0/users [email protected] password=123456 -v
POST /api/v1.0/users HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 51
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/0.9.2

{
    "email": "[email protected]", 
    "password": "123456"
}

HTTP/1.0 201 CREATED
Content-Length: 422
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Aug 2015 03:40:50 GMT
Location: http://localhost:5000/api/v1.0/users/1
Server: Werkzeug/0.10.4 Python/2.7.6
Set-Cookie: session=eyJfaWQiOnsiIGIiOiJOakZoTXpKaU5tTXpZelpqWlRReFpEWmtPRFUxTlRrM1pqazFPRFU0TWpFPSJ9fQ.CL7Gwg.aIDJrepymtCif8S9ktd3MLHhOfs; HttpOnly; Path=/

{
    "data": {
        "active": true, 
        "confirmed_at": "2015-08-26T03:40:50+00:00", 
        "created_at": "2015-08-26T03:40:50+00:00", 
        "email": "[email protected]", 
        "id": 1, 
        "roles": [
            {
                "description": "user role", 
                "id": 1, 
                "name": "user"
            }
        ], 
        "updated_at": "2015-08-26T03:40:50+00:00"
    }
}

/api/v1.0/token

  • to retrieve the jwt token:
$ http POST :5000/api/v1.0/token [email protected] password=123456 -v
POST /api/v1.0/token HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 51
Content-Type: application/json
Host: localhost:5000
User-Agent: HTTPie/0.9.2

{
    "email": "[email protected]", 
    "password": "123456"
}

HTTP/1.0 200 OK
Content-Length: 238
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Aug 2015 03:45:54 GMT
Server: Werkzeug/0.10.4 Python/2.7.6
Set-Cookie: session=eyJfaWQiOnsiIGIiOiJOakZoTXpKaU5tTXpZelpqWlRReFpEWmtPRFUxTlRrM1pqazFPRFU0TWpFPSJ9fQ.CL7H8g.O2eBChbsZEacjpfEfBtpOu-lyzE; HttpOnly; Path=/

{
    "expires_in": 7200, 
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0NDA1NjA3NTQsInB3ZCI6ImMwYjQ0MTEwZjEwOWYwZGRmZDQ2NDNlM2M4NDRiNzIwIiwic3ViIjoxLCJleHAiOjE0NDA1Njc5NTR9.5nLH7uOBxjISIgTRlqXEJmJxA_A9171ip9KM3uS2kKo"
}

After that, the token should be use to access token required resources.

For example:

$ http --auth-type=jwt --auth=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0NDA1NjA3NTQsInB3ZCI6ImMwYjQ0MTEwZjEwOWYwZGRmZDQ2NDNlM2M4NDRiNzIwIiwic3ViIjoxLCJleHAiOjE0NDA1Njc5NTR9.5nLH7uOBxjISIgTRlqXEJmJxA_A9171ip9KM3uS2kKo: :5000/api/v1.0/users/me -v
GET /api/v1.0/users/me HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0NDA1NjA3NTQsInB3ZCI6ImMwYjQ0MTEwZjEwOWYwZGRmZDQ2NDNlM2M4NDRiNzIwIiwic3ViIjoxLCJleHAiOjE0NDA1Njc5NTR9.5nLH7uOBxjISIgTRlqXEJmJxA_A9171ip9KM3uS2kKo
Connection: keep-alive
Host: localhost:5000
User-Agent: HTTPie/0.9.2



HTTP/1.0 200 OK
Content-Length: 422
Content-Type: application/json; charset=utf-8
Date: Wed, 26 Aug 2015 03:48:06 GMT
Server: Werkzeug/0.10.4 Python/2.7.6
Set-Cookie: session=eyJfaWQiOnsiIGIiOiJOakZoTXpKaU5tTXpZelpqWlRReFpEWmtPRFUxTlRrM1pqazFPRFU0TWpFPSJ9fQ.CL7Idg.oDFRMTszTfmSxl1hvNLVaIxUwg0; HttpOnly; Path=/

{
    "data": {
        "active": true, 
        "confirmed_at": "2015-08-26T03:40:50+00:00", 
        "created_at": "2015-08-26T03:40:50+00:00", 
        "email": "[email protected]", 
        "id": 1, 
        "roles": [
            {
                "description": "user role", 
                "id": 1, 
                "name": "user"
            }
        ], 
        "updated_at": "2015-08-26T03:40:50+00:00"
    }
}

Contributing

Discussions

Join us:

Get our news:

Author and contributors

See more details at AUTHORS.md and CONTRIBUTORS.md files.

License

BSD License

Copyright (c) Teracy, Inc. and individual contributors.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

    1. Redistributions of source code must retain the above copyright notice,
       this list of conditions and the following disclaimer.

    2. Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.

    3. Neither the name of Teracy, Inc. nor the names of its contributors may be used
       to endorse or promote products derived from this software without
       specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

flask-boilerplate's People

Contributors

datphan avatar hoatle avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

flask-boilerplate's Issues

use better semantic special method names for Resource

CRUD and list => CRUDL

create -> POST
read -> GET
update -> PUT
delete -> DELETE
list -> GET

update this on https://github.com/teracyhq/flask-boilerplate/blob/develop/app/api/base.py#L166-L177

to:

    special_methods = {
        'get': ['GET'],
        'put': ['PUT'],
        'patch': ['PATCH'],
        'post': ['POST'],
        'delete': ['DELETE'],
        'index': ['GET'],
        'create': ['POST'],
        'read': ['GET'],
        'update': ['PUT'],
        'list': ['GET']
    }

note: remember to update existing resources (UserResource, RoleResource)

add support for @extract_args to avoid boilerplate

from:

    @route('', methods=['GET'])
    @token_auth_required()
    @permissions_required(admin_role_permission)
    @marshal_with(_user_list_schema)
    @paginated
    @use_args(search_args)  # TODO(hoate): add support for @extract_args to avoid boilerplate
    def index(self, args):
        filters, args = extract_filters(args)
        args['filters'] = filters
        return auth_datastore.find_users(**args), args

to:

    @route('', methods=['GET'])
    @token_auth_required()
    @permissions_required(admin_role_permission)
    @marshal_with(_user_list_schema)
    @paginated
    @extract_args(search_args) 
    def index(self, args):
        return auth_datastore.find_users(**args), args

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.