local_florist Assembly local_florist

A Pythonic Object-Oriented Web Framework built on Flask

About

Assembly is a pythonic object-oriented, mid stack, batteries included framework built on Flask, that adds structure to your Flask application, and group your routes by class.

Assembly allows you to build web applications in much the same way you would build any other object-oriented Python program.

Assembly helps you create small to enterprise level applications easily.

Assembly Makes Flask Great Again!

Installation Guide

Why Assembly ?

Flask is very easy and simple. It's fun to put a few endpoints in a single file. However when your application starts growing into an endless of endpoints, tons of models and views, or your team is having more people, it is very necessary to have some sort of structure in your application.

And that's what Assembly does. Assembly adds structure to Flask application. Assembly removes a lot of Flask boilerplate. Assembly makes your Flask application scalable and easy to work with.

Instead of having loose endpoints per functions, Assembly organizes all groups of endpoints per class. Instead of each time rendering the template for each endpoint manually, Assembly matches the name of the method of the class, to the name of the template file, making it a one-one match.

Assembly automatically loads your models and configuration.

Assembly is very extensible, as every View is it's own package. Making it easy to add and remove.

Assembly Makes Flask Great Again!

Assembly in action

Structure

-- /
    |- wsgi.py
    |- requirements.txt
    |- lib/
        |- config.py
        |- models.py
    |- run
        |- scripts.py
    |- views/
        |- main.py
    |- templates/
        |- layouts/
            |- base.html    
        |- main/
            |- Index/
                |- index.html
    |- static/
    |- data/

Pythonic Routes

Routes are created based on the class and the method names by default. Class named Index and method named index will be the entry point of the route.

from assembly import Assembly

# Extends to Assembly makes it a route automatically
# By default, Index will be the root url
class Index(Assembly):

    # index is the entry route
    # -> /
    def index(self):
        return "welcome to my site"

    # method name becomes the route
    # -> /hello/
    def hello(self):
        return "I am a string"

    # undescore method name will be dasherize
    # -> /about-us/
    def about_us(self):
        return "I am a string"

# The class name is part of the url prefix
# This will become -> /blog
class Blog(Assembly):

    # index will be the root
    # -> /blog/
    def index(self):
        return [
            {
                "title": "title 1",
                "content": "content"
            },
        ]

    # with params. The order will be respected
    # -> /blog/comments/1234/
    # 1234 will be passed to the id
    def comments(self, id):
        return [
            {
                # comments
            }
        ]

RESTful

Methods named get, post, put, delete, update will automatically accept the associated methods GET, POST, PUT, DELETE UPDATE respectively.

But you can also assign a different method by using the appropriate request decorator.

from assembly import Assembly, request

class Api(Assembly):

    # method named get, automatically accepts get method
    # -> GET /api/<id>
    def get(self, id):
        return {
            "message": "This will show on get call"
        }

    # method named post, automatically accepts post method
    # -> POST /api/
    def post(self):
        return {
            "message": "This will show on POST call"
        }

    # Example of a different route assigned a method
    # /submit/ will only accept POST call
    # -> POST /submit/
    @request.post
    def submit(self):
        return "Submitted!"

Multi Response Type

By default Assembly will map the route to its associated template. It's very convenient as you don't have to explicitely render the template.

But you can also make the route return JSON.

# views/main.py

from assembly import (Assembly, response, request, HTTPError)

# Extends to Assembly makes it a route automatically
# By default, Index will be the root url
class Index(Assembly):

    # index is the entry route
    # -> /
    # it will render its associated template from 
    # 'templates/main/Index/index.html'
    def index(self):
        return 

    # returning string will be rendered as string.
    # -> /hello/
    def hello(self):
        return "I am a string"

    # returns a json response
    # -> /api/
    @response.json
    def api(self):
        return {
            "name": "Assembly",
            "title": "Assembly for ever",
            "items": [
                # list of items
            ]
        }

    # This will throw an Unauthorize error
    def error(self):
        raise HTTPError.Unauthorized()

Quick Start

This quickstart will allow us to go with Assembly from 0 to 100!

1. Install Assembly

Install Assembly with pip install assembly

It is highly recommended to use a virtualenv, in this case let's use VirtualenvWrapper (you can use any that is convenient for you)

mkvirtualenv my-first-app

workon my-first-app

pip install assembly

2. Initialize your application

Initialize Assembly with asm gen:init

CD into the folder you intend to create the application, then run asm gen:init. This will setup the structure along with the necessary files to get started

cd app-dir

asm gen:init

Upon initialization you should have a structure similar to this:

-- /
    |- wsgi.py
    |- requirements.txt
    |- lib/
        |- config.py
        |- models.py
    |- run
        |- scripts.py
    |- views/
        |- main.py
    |- templates/
        |- layouts/
            |- base.html
        |- main/
            |- Index/
                |- index.html
    |- static/
    |- data/

3. Edit your first view

# views/main.py

from assembly import (Assembly, response)

class Index(Assembly):

    def index(self):
        return {
            "title": "Assembly is awesome",
            "content": "That is a true fact"
        }

    @response.json
    def api(self):
        return {
            "name": "Assembly",
            "version": "x-to-infinity"
        }

4. Edit your template

4.0 Edit base layout

<!-- templates/layouts/base.html -->

<!doctype html>
<html lang="en">
  <head>
    <title>{% block title %}{% endblock %}</title>
  </head>

  <body>
    <div class="container">
      {% block body %}{% endblock %}
    </div>
  </body>
</html>

4.1 Edit Index/index.html

<!-- templates/main/Index/index.html -->

{% extends 'layouts/base.html' %}

{% block title %}Welcome to my Assembly Site {% endblock %}

{% block body %}
    <div>
        <h1>{{ title }}</h1>
    </div>
    <div>
        {{ content }}
    </div>
{% endblock %}

5. Serve your first application

If everything is all set, all you need to do now is run your site:

asm gen:serve

It will start serving your application by default at 127.0.0.1:5000

Two endpoints will be available:

  • http://127.0.0.1:5000/ which will show an HTML
  • http://127.0.0.1:5000/api/ which will a json response

Features List

  • Smart Pythonic Routing: automatically generates routes based on the classes and methods in your views

  • Class name as the base url, ie: class UserAccount will be accessed at '/user-account'

  • Class methods (action) could be accessed: hello_world(self) becomes 'hello-world'

  • RESTful: good to create API endpoints, which can also return JSON object

  • Automatic view rendering

  • Auto route can be edited with @request.route()

  • Multi responses type: HTML, JSON, Text

  • Markdown friendly: Inclusion of a markdown file will turn into HTML

  • BCRYPT is chosen as the password hasher

  • Session: Redis, AWS S3, Google Storage, SQLite, MySQL, PostgreSQL

  • Database/ORM: SQLAlchemy base to work DB models via Active-Alchemy

  • Login Manager: for user session management via Flask-Login

  • Form Validations: Validate your forms via WTForms

  • CSRF on all POST: to protect against CSRF attacks

  • Idiomatic HTTP error responses

  • Storage: to access and store files from Local, S3, Google Storage with Flask-Cloudy

  • Mailer: To send email using SMTP or AWS SES

  • Arrow: Human friendly date and time library

  • CLI/Scripts: Create your own scripts to be used on the command line.

  • Caching: To cache responses

  • JWT

  • Pagination

  • Signals: to dispatch messages and data to other part of the application

  • Markdown

  • Jinja2 for templating language

  • Multi application: Allow to share the same codebase but with multiple applications.

  • Web Assets: To easily manage your static content: css, js, images etc...

  • Inbuilt development server

  • And much more...

Image Credit - License: Non-commercial Use : https://imgbin.com/png/q2HLy9Kx/flower-watercolor-painting-png