The quickest way to start a new Flask-Diamond project is to use the scaffolding system. Scaffolding applies a series of file templates that result in a starter application that can be further customized. This document discusses the configuration questions that are used during scaffolding.
As described in the Quick Start, the basic process looks like this:
mkdir my-application cd my-application mkvirtualenv -a . my-application pip install Flask-Diamond flask-diamond scaffold app make install docs test db server
When you invoke flask-diamond, a template is automatically applied. Using mr.bob, a brief set of questions are used to populate the templates with variables. When you answer these questions, your choices are stored in a file called .mrbob.ini that is located in the root folder of your project.
This template is suitable for supporting many types of Python projects. It will create a basic directory structure that provide requirements management, documentation, build, deployment, and other basic project needs. This step of the scaffolding process asks the following questions:
The application name is a human-readable name that will be used in documentation, on websites, and when talking about the project. This should follow conventions that are established within your community. In the case of Flask-Diamond, the project name tries to follow the naming pattern established by other Flask extensions like Flask-Admin, Flask-Security, and Flask-RESTful.
The module name is a PEP8 styled name. In the case of Flask-Diamond, the module name should be lowercase and hyphens become underscores. Thus, Flask-Diamond becomes flask_diamond.
Example: Flask-Diamond is a batteries-included Flask framework.
This question corresponds to the setuptools.setup(description="") variable in the project setup.py file. The short description is intended to appear as a brief summary in PyPI.
Example: Flask-Diamond is a batteries-included Flask framework. Easily scaffold a working application with sensible defaults, then override the defaults to customize it for your goals.
This question corresponds to the setuptools.setup(long_description="") variable in the project setup.py file. In practice, this usually ends up being multiple paragraphs.
Your application will run as an HTTP service that listens on the port provided here. Thus, if you answer 8000 you will be able to connect to your application at http://localhost:8000/admin.
There are some steps in the scaffolding process that are automatically generated for you because they involve random processes.
Flask uses a secret key to seed certain cryptographic functions. To generate a suitable random string for the secret key, use the following Python code:
python -c 'import os; print(repr(os.urandom(24)))'
Flask uses a hash salt for password storage. To generate a suitable random string for the hash salt, use the following Python code:
python -c 'import string as s, random as r; \ print repr("".join(r.choice(s.letters+s.digits) for _ in range(16)))'
Flask-Diamond can simplify the creation of testing accounts during development. One of the default accounts has administrative privileges, so a simple password is used to protect the account. This password is just 3 letters long by default, so it should never be used anywhere but during development. To ensure this weak password is not used in production, the Makefile is hardcoded to use the development configuration, only.