Flask Applications the SciComp Way

• What is supported/required?
  • Python 3
  • Virtual Environments
  • Unit Tests
  • Database Access
  • Which RDBMS should I use?
  • REST Access
  • Other Supported/Recommended Modules
  • Web Servers
  • SSL (https)
  • Interacting with the gizmo cluster
  • My app needs to call some R code
  • Secrets Management
  • Does your app use PHI?
  • Use GitHub for version control
  • Helpful Tools for code development
  • Linters
  • Profiling
  • Continuous Integration (CI)

Use these templates to build your own Flask application in a way that will be supported by SciComp.

What is supported/required?

Python 3

Python 3 was released in 2008 and Python 3.x should be used for all new projects. If you have an existing Python 2 codebase, contact SciComp for help with porting it to Python 3.

Virtual Environments

Use Pipenv to manage the virtual environment for this project. If pipenv is not installed, install it.

The first time you clone the repository, create the virtual environment and install the dependencies with this command:

pipenv install

Before each session of working with this app, activate the virtual environment in your current shell with:

pipenv shell

Unit Tests

Flask makes it easy to add unit tests to your application. Unit tests give you confidence that your app works the way it's supposed to.

Every route in a Flask app should have at least one unit test.

Database Access

For most new applications, we recommend SQLAlchemy, which provides an Object-Relational Mapper (ORM) for Python.

There are some cases where using an ORM is overkill and you just need to run some simple queries. In these cases, you can use the DB API module for your RDBMS (MySQL, PostgreSQL, sqlite). When using these low-level modules, you must always write code in such a way as to avoid SQL injection. For example, never do this:

# Never do this -- insecure!
symbol = 'RHAT' # assume this comes from a form or other untrusted source
c.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)

Instead do this:

t = ('RHAT',)
c.execute('SELECT * FROM stocks WHERE symbol=?', t)

Which RDBMS should I use?

PostgreSQL is the main supported RDBMS. You may use sqlite3 just for testing and development(??), but in production you should use PostgreSQL.

For PostgreSQL, use myDB. If your app lives outside the Hutch network, use Amazon RDS for PostgreSQL.

If you need to use a NoSQL database, use MongoDB and the PyMongo module.

REST Access

If your application is meant to expose a service that other code can consume, use the Flast-RESTful module.

Other Supported/Recommended Modules

(??)

• SciPy
• NumPy
• pandas
• ??

Web Servers

TODO fill this in

• Flask development server - pros & cons
• gunicorn
• apache and nginx via WSGI

SSL (https)

It's recommended that your web app only be accessible via SSL (the HTTPS protocol). If your web app will use a fredhutch.org or fhcrc.org domain, contact SciComp for help setting this up. If you'll be using an external domain name, consider using Let's Encrypt to set up your SSL certificates.

Interacting with the gizmo cluster

?? Do we need this section ?? Are flask apps allowed to submit jobs to the cluster ??

My app needs to call some R code

We recommend that you port the R code to Python.

(??)

Secrets Management

FIXME add to this

Does your app use PHI?

FIXME add to this

Use GitHub for version control

Store your code in a GitHub repository (ADD MORE HERE)

Helpful Tools for code development

Linters

We strongly recommend using linters when developing Python code. Linters such as pylint, pyflakes, and flake8 (which combines the first two) will point out syntactic, stylistic, logical, and many other issues with your code. Ideally, code should be free of linting warnings before it's committed to Git.

The Atom text editor has add-on packages which enable linting right inside your editing window.

Profiling

Profiling helps you find the parts of your code that run slowly and can be optimized.

Continuous Integration (CI)

Use Travis CI or circleci to automate the testing and deployment of your code.

(should we require CI? we can at least illustrate it by example in this repository)