Flask Empty

version 0.6.5

Flask-Empty is a simple flask boilerplate for fast prototyping. Just use cookiecutter and create a new project in no time.

# if cookiecutter is not installed
pip3 install cookiecutter

# using cookiecutter // linux/Mac
cookiecutter https://github.com/italomaia/flask-empty

# answer the prompt and you're done!

Getting Started

You're advised to use venv from here on. In your project folder, create and enable it like this:

python3 -m venv venv
. venv/bin/activate  # [.csh|.fish]

# install required packages
pip3 install -r requirements.txt

# loads env variables and runs the project in development mode
make run-dev

Getting Started With Docker

Given you have up-to-date docker installed in your machine, all you need to do is:

# build container image
docker build . -t my-project-name
# run container in development mode
docker run --rm -p 5000:5000 my-project-name

Environment Variables

For flask to run correctly, some environment variables need to be set. The ones needed by your project can be seen in the Dockerfile or Makefile files. For a list of all other optional environment variables, check this link. When using docker, you can easely set them inline before each run. When using docker-compose, set them in the yaml configuration file for each environment.

Important files to be aware of

/extensions.py all extension instances that need initialization should be available here, so Empty can see and initialize them for you. If instantiated somewhere else, just import them here and you should be fine.

/config.py has pre-set configuration classes for you to meddle with. They're are all self explanatory and commented.

/main.py instantiates your project's main class. Override it to quickly add custom extension setups, simple views, context processors, etc. It already has some sensitive defaults for most use cases. See https://github.com/italomaia/empty for the available options.

<project>/<project>.ini is the configuration file used with uwsgi. Use it like this:

uwsgi --ini your_project.ini

commands.py adds few very useful commandline commands (...) to help your development productivity. You can also add your own. Check available commands by running FLASK_ENV=development FLASK_CONFIG_DEFAULT=Dev flask in the terminal.

Heroku

Empty comes with a pre-configured procfile and heroku() wrapper for _appfactory. No setup required.

Other topics

Templates

There are some error templates bundled with flask-empty by default. All empty right now. Just fill them up for your project.

Macros

You can use the jinja2 macros available in templates/macros to easily integrate your jinja2 templates with flask extensions like wtforms and common tasks like showing flash messages.

Available macros, formhelpers and flashing are very useful.

Blueprints

You can create blueprints easily with make new-app. The will live, by default at apps folder. Remember to configure your blueprints in config.py so that they can be properly loaded.

Json Friendly

Variables true, false and null are now supported as aliases for True, False and None. This way, valid json can be copy-pasted directly into your code and will be interpreted as valid python. Ex: data = {"x": true, "y": false, "z": null}

Supported Extensions

Flask-SQLAlchemy

While creating your project, Flask-Empty will ask you if you wish to enable SQL support. Confirm if you do so and Flask-SQLAlchemy will be made available. See config.py for its default configuration.

_ps: currently, db-create will only create your models if they are imported somewhere in your application.

By somewhere, try the same module where your Blueprint instance is defined.

Flask-Mongoengine

As mongodb is really cool, supporting it is a must. Just say yes at the prompt when asked and Flask-Mongoengine will be setup for you.

Flask-WTF

Flask-WTF is the "the facto" extension for handling forms with Flask. It is simply great, and Flask-Empty supports it! Just say "yes" during project creation and Flask-WTF support will be on.

Flask-Admin

Just create an admin.py file in your blueprint, define your admin models inside and change LOAD_MODULES_EXTENSIONS to also pre-load admin, like this:

Flask-Marshmallow

Gives you, almost for free, model serialization, deserialization and validation. Also quite handy for fast development of rest applications.

Flask-Security

Get user session and permissioning out-of-the-box with this great project.

Examples

The blog example in this project is probably outdated by now, so, just create a new project and mess around to your heart's content for quick learning.

FAQ

Is flask-empty boilerplate compatible with flask 0.x? Cuz' that's what my app uses.

Right now, flask-empty is a very simple project where many good practices and code examples were glued together.

Until recently I was focused in keeping backward compatibility with flask 0.8. Well, that goal is no more.

Flask-empty will be compatible with the latest version of Flask and, by chance, with previous versions. Things will be easier (for me!) this way.

So, which is the oldest version where flask-empty works?

In my last test, version 1.0.

I think flask-empty should have this and that configured by default. Will you add support?

My current goals are:

• Make flask-empty real easy to start a project with
• Keep things simple and robust

If your suggestion is simple, VERY useful and has little overhead, I'll probably consider adding it to the project.

If you make the code and send a pull request, then I'll consider it real hard. Now, if your suggestion is rejected or advised in a different approach, don't get sad (you're awesome ;).

I just made a cool example with flask-empty and want to add it to examples.

Pull request it for evaluation ;) Just keep in mind that good examples are short (not really...) and focused in it's showcase.