Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/italomaia/flask-empty

An empty project skeleton / boilerplate for flask projects. Powered by CookieCutter.
https://github.com/italomaia/flask-empty

blueprint boilerplate flask hacktoberfest python skeleton-application

Last synced: about 20 hours ago
JSON representation

An empty project skeleton / boilerplate for flask projects. Powered by CookieCutter.

Awesome Lists containing this project

README 

        
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.



```shell

# 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](https://docs.python.org/3/library/venv.html) from here on.

In your project folder, create and enable it like this:



```shell

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:



```shell

# 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](https://flask.palletsprojects.com/en/1.1.x/config/). 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](https://pypi.org/project/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.



`/.ini` is the configuration file used with

[uwsgi](https://github.com/unbit/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 _app_factory_. 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.