Starting a Simple Flask Application From Scratch
The moving parts of starting a small project in Flask - what, why and how.
As introduced in the previous article, we’re going to build a web app using Python and Flask. It’s going to interact with the Spotify API and show the album image of the currently playing song for a logged-in user. The visuals are meant to be displayed as big as wanted or necessary. Fullscreen if possible. Apart from stating the initial intentions, we have not done any hands-on work. Let’s change this!
In this part, I want to help you get a grasp of the parts which help you work with a small Flask applications, what files are present and what they do, why people like them, and the process of setting such a thing up.
If you have any questions, just drop me a mail or tweet at me :)
What We’re Going to Use, and Why
If you look at any larger web project, you’ll see lots of different parts and tools working together and being used. Lots of this stuff is pretty straight-forward if you have dealt with it for a while, but can be overwhelming when starting out. Instead of jumping into “this is what you need to type into your terminal”, I’d like to walk you through my set of tech/tools of choice and briefly explain why I make use of them.
A source control system - Git. This makes it easier to collaborate with other people, track changes on the code and prevents disaster (aka I deleted something and everything stopped working or ‘the newest code broke stuff, I just want to see how it was before’). An alternative might be to create copies of the complete project when you feel like it, but let’s not do this.
Github - it’s a platform to share your code with others and access it from your server, a way to have it somewhere else than your laptop (which makes it harder to lose your work if you happen to lose your computer or the hard drive fails you). It also makes it easier to discover and browse open source projects, which is why I put this one on it publicly.
Markdown - as markup format for the README file - a way to introduce the project and describe how to perform useful operations on it, such as setting stuff up. Markdown looks nice in a text editor (human-readable in its raw form), is easy to type, and can be rendered to fancy text.
Flask with Python - the thing on the server, which reacts to user requests and returns webpages. Flask is lightweight and modular. Python is a language I like and a joy to work with. Solid alternatives, for example, might be Ruby with Ruby on Rails, Golang or PHP with Laravel - user’s choice.
CSS + HTML + JS - is what websites are made from, we’re gonna use Jinja2 to create templates which will be rendered out and is pretty much default for Flask.
Virtualenv - is a nice way to make sure a project has exactly what it needs in terms of Python dependencies, and a particular Python version. Virtualenv-wrapper is really cool to make it easy to deal with multiple virtual environments on Linux or Mac.
Pip - to install dependencies in the virtualenv (and for Python in general). For example you usually install the Flask module using pip.
When starting a new project, usually my goal is to have a comfortable base to build on. I want to know where everything is and what it does. I also really like having the stuff I work on being able to do something or be interactive. That’s a nice motivational boost to go and make it do the right thing after it does someting. With a webdev project, that’s simple. The first thing I aim for is usually printing “Hello World!” or something equally simple.
If you read the previous article, you will see that we are not aspiring to account for everything which we came up with. I like starting out simple and fleshing out parts one after the other. It’s very easy to build too much, or get discouraged by trying to tackle something which will finally work in a few days. Hooray for iterative approaches!
The Project structure, is pretty much a barebones thing, and some parts are only there because it’s an open source project (actually, only the LICENSE file). We can start with this and move stuff around / get more fancy as we need it.
The Basic Project, Step by Step
Making use of all the components described previously and putting everything into place, results in the project looking like this. The link goes to an earlier stage of the big-album-art project, right after I started it. You can browse through the files and see how everything comes together.
When starting out on this, I was a bit rusty regarding Flask, and basically had to start from the beginning as usually. Looking everything up as it comes up. The flask page served as a nice source for a basic Flask app. I also took a look at smallish example Flask project by the creators looking what they chose to do, applying the details I notices and liked.
What was done step-by-step is: I created a new project on Github, having it generate a .gitignore, LICENSE and README.md file right away for convenience. The .gitignore file is meant for letting the source control system know what files and patterns to ignore because they can be generated or should be kept out of the repo. Any project should have a README, stating what the project is about and how to perform basic operations. It’s for other people taking a look or making use of it, but also for yourself-a-few-weeks-later. Having any kind of usable docs saves so much time and effort, it’s magical. Except if it’s wrong and deprecated. Then it can hurt. The README you see in the link is missing details on installing packages/the right python version (which are OS specific) and details on setting up a virtual environment. Something like
$ virtualenv -p /usr/bin/python3.5 env
and explanations would have been nice.
We need to make sure that we know which version of Flask we were using, so another person (or us in the future) can make it work. The requirements.txt file is pretty important to get the app up and running on a completely new computer/from scratch. It contains information on what Python modules are needed, and an exact version annotation. Pip can take care of installing exactly those versions. If you use a virtual environment, those library versions are sure not to be overwritten by other project installing stuff. Once you have it, installing all Python dependencies is as simple as:
$ pip install -r requirements.txt
The Python code is located in its own “baa” folder - which is meant as an acronym for “big-album-art”. baa is a python module by itself (this is achieved by having a __init__.py named file in it. The main.py file contains our current Flask app. It doesn’t do much right now - just return “Hello World” when somebody accesses the / path on the server.
The setup will change during the project, as needed and if it seems to make sense.
This is the way I start small projects from scratch. If you are a bit more advanced and know what you want, you usually use something like a template to start with sane defaults and preconfigured bits. In Django this is integrated into the framework.
With Python in general, you can use cookiecutter with templates other people have provided. You provide variables / answers to questions interactively and can save a lot of time. As I wanted to start as simple as possible, I chose a manual approach.
Next up, we’re going to iterate on the app, and make it do something useful - talk to the Spotify API, interact with a database and handle sessions. But first, we need to setup a database in our development environment. If you want to join in on the fun, and be notified about the next post, just drop me your favorite email address below and I’ll be in touch!