Application structure, versioning, and environments the Andela way.

Software versioning is the process of labeling different releases or improvement of a particular application for both internal use by the developers and release designation to the users. Versioning is very crucial as it allows application developers to track changes and know when improvements to the application have been made during the process of development.

A good application structure should enable the developers to easily differentiate and separate various versions of the application during the development cycle.

Now that you know what versioning is(V1, V2…) lets jump straight to the process of developing a perfect and most recommended structure for your application.

Step 1: Create a new repo and clone it to your local computer

Allow me to assume that by now you are relatively good with GitHub and git and you can create a repo and clone it on your computer.

Note: In this article, I will be refering challenge 2 as Version 1 (V1) and challenge 3 as Version 2 (V2) as far as Andela is concerned.
It is important to note that both the versions are supposed to be on the SAME NEW REPO.

While creating a new repository for this, make sure that you select the most relevant repo name, make the repo public and initialize the repo with a README. Add a .gitignore file specifying your language, ie, python (I will explain why you need this later in this tutorial). It is optional to add a license to your repository, but it is something you can consider (All my apps have MIT licenses. 😜😜😜). Clone this repository on your computer, in a location that is easy to access.

Step 2: Set up your editor

There are several editors in the market today, that one can use to develop their application. The most common and recommended editors used are VS code, Sublime text, Light table, Atom, and Brackets. In this tutorial, I will use VS code since it is friendly and the most recommended for Andela projects.

If you dont have VS code editor installed, click here for instalation and more documentation on the same.

After cloning the repository to your most preferable location, open the editor and locate the repo from the location where it is saved at as below.

( 😉 😉 you are probably wondering how I have tom n jerry on my git, don’t worry 😆 😆)

Below is an image showing how the editor should look like after opening the cloned repo in it. To do this click on File, Open folder, then locate the repo.

The welcome page can be closed, so assume it. On this window, you can see that the app folder/directory contain the .gitignore, license, and README which we added while creating the repo. Note that you must have the README and .gitignore.

• README: A readme file contains a brief explanation of the app, for instance, the APIs in the app, the languages used, the developers, how to test the APIs among other information that might be useful for to the user. Below is an example of how a readme page should look like when you open it on GitHub.

Click here to find out more on how to edit your readme so that it looks appieling and easy to ready and follow.

It is recommended that NOTHING except the readme should be PUSHED and be COMMITTED to the master branch. Master should be a branch accessible to the end users so it should only contain the links to the app and the readme which guides them.

N/B: You can thus go ahead and edit your readme and make the first commit to the master branch. After making this commit, you can branch off, master to a new branch called develop (this is the universal name for it). It is from “develop” that you will be brunching off all other feature branches. The app structure should be set up in the develop branch.

At this point, I want to believe that your readme in the master branch is descriptive enough and you have branched off from master to develop.

Step 3: Set up the structure

This is an essential step as you will be adding files and folders to the root directory/folder which is your repo on the local machine. Below is a manual skeleton of a simple structure of the app.

NOTE: Every subfolder except the root directory MUST have an __init__.py file in them.

Let’s go ahead and do this practically. to add a file click on “add file” to add a folder click on “add folder.”

As you can see, at the bottom bar, we are currently working on develop, and the basic structure is set, and in every subdirectory/subfolder, there is a __init__.py file.

At this point, I want to assume that we all have this kind of structure and we are in develop branch.

Step 4: Set up the environment.

A virtual environment, in the simplest way possible, is where all the application’s installations are done and stored. It helps us to save on space and processing of the computer since all the installations are done virtually hence the name virtual environment. Most people call it venv or env.

For us to include the env or the venv subfolder in our app structure we cd into the root directory of our app which in my case is StackOverflow-lite in the terminal and type the below command.

virtualenv venv

Press enter and let the virtual environment be installed. A folder called venv will be added automatically in your root directory as seen below.

After doing this, it is recommended that you install an autoenv whose function is to set commands that run anytime you cd into the root directory. This reads the .env file (which we are making next) and executes the commands in it. Use the command below to install it.

pip install autoenv

Create a file called .env whose function is to store all the commands that run the app, define the environment to be used, the secret keys and the urls, i.e., database urls.

The autoactivation of the venv is done by running the commands below, that is after autovenv is installed.

$ echo "source `which activate.sh`" >> ~/.bashrc
$ source ~/.bashrc

Alternatively, without installing the autovenv, you can manually activate the virtual environment by running the code below in your terminal when in the root directory.

cd venv/Scripts/activate

The following are basically the content of a .env file which is created in the root directory.

source env/bin/activate (this line activates the virtual env)
export FLASK_APP="run.py" (this exports the flask application)
export SECRET="anything that you want" (exports the secret key)
export APP_SETTINGS="development" (exports the app settings)
export DATABASE_URL="your database url" (the DB url)

At this point, your root directory should contain a .env file as part of the structure, and you should be able to activate your virtual environment. When activated, the name of the venv will appear at the beginning of the lines in the terminal as shown below.

(venv) C:\Users\simon\Desktop\Stackoverflow-lite-APIs>

(😉 😜 Am using windows btw: among the few programmers who feel comfortable coding with windows. So don’t get confused with the above line.)

This what you should be having as we speak…wait are we speaking? 😆 😆 😆 (don’t mind me with the emojis and the humor, they ease the coding for me 👌

Step 5: Set up your configurations (Important but not very necessary for version 1)

I know when I say important but not necessary you will ignore because you are probably tired. DO NOT IGNORE it; it will save your time later as you proceed. This is the simplest since it is universal and the lines of code are almost the same.

Python or Flask requires configurations to determine which environment should the app run in (development, production or testing) and the debug mode (True). All these are well defined for Flask in the configuration file universally called .config which we had already created in the instance subfolder.

Below are the settings and their brief explanation. Ensure that you research more so that you can be able to explain what every single line of code does.

import os """We import the OS since it is from the OS that we have set all the requrements in the venv."""
class Config(object):
    """Parent configuration class."""
    DEBUG = False
    SECRET = os.getenv('SECRET') 
    """gets the secret key set in the .env file"""
    DATABASE_URI = os.getenv('DATABASE_URL')
class DevelopmentConfig(Config):
    """Configurations for Development."""
    DEBUG = True
class TestingConfig(Config):
    """Configurations for Testing, with a separate test database."""
    TESTING = True
    DATABASE_URI = 'testing URL for the test DB'
    DEBUG = True
class StagingConfig(Config):
    """Configurations for Staging."""
    DEBUG = True
class ProductionConfig(Config):
    """Configurations for Production."""
    DEBUG = False
    TESTING = False
app_config = {
    'development': DevelopmentConfig,
    'testing': TestingConfig,
    'staging': StagingConfig,
    'production': ProductionConfig,
}

The first class Config contains the general settings that all other environments will be inheriting. The app config dictionary app_config exports the defined environments which you will use later. Research and read more on what all these codes mean as you will be asked to explain by the LFAs later ( 😉 😜 don't get scared).

Step 6: Set up the server

This is the last step where we want to make sure that our app structure is okay and that the server can run. Initially, we had created a file called run.py (If you don't have it, just add a file in the root directory and name it. run.py.It is in this file that we initialize and run the app by defining the app settings and. Below is a brief description of what your run.py should have.

"""app initializer """
import os
"""you import this to get all that we had defined and exported in the .env"""
from app import create_app
"""this is imported from the __init__.py file contained in the subdirectory called app"""
config_name = os.getenv("APP_SETTINGS")
"""Gets the app settings defined in the .env file"""
app = create_app(config_name)
"""defining the configuration to be used"""
if __name__ == '__main__':
app.run()

The app, however, cannot run before we create the application itself. The app is created in the __init__.py file that is in the app folder

IMPORTANT TO NOTE: App is created in the __init__.py file in the app folder. This is the only __init__.py that should have content. The others are left blank as their functions is to make the files in the folders be converted to modules that can be imported and exported.

Here is how to create the app. First, ensure that your venv is active then install flask using the command below

(venv) C:\Users\simon\Desktop\Stackoverflow-lite-APIs>pip install flask

This installs flask into our virtual environments. You can note that my venv is active. In the environments, install a .env to assist python in activating the environment configurations. Use the below command

pip install python-dotenv

You are now set to create your app. Below is a simple structure of how the app should be created

'''Creating app'''
import os
from flask import Flask
from instance.config import app_config
"""importing the configurations from the .config file which is in the instance folder"""
def create_app(config_name):
'''creating  the app using the configurations in the dictionary created in the .config file'''
app = Flask(__name__, instance_relative_config=True)
app.config.from_object(app_config[config_name])
app.config.from_pyfile('config.py')
return app

After doing this go to the terminal and run: which should start up your server

flask run

The server should be running. This is the final app structure that you should be having at the moment. Other folders will be autogenerated once the server is running as seen below.

• .gitignore and requirements.txt explained

Gitignore: A git ignore file is very important for the app since any file included in it will not be uploaded to GitHub for the public to view. Sensitive settings like the secret key are not supposed to be exposed to the public thus explaining the importance of a git ignore file. You will realize that some folders are deemed in your app structure like the below captured:

This is because, in the gitignore, you specified that the file or folder should not be uploaded to GitHub.

Requirements.txt: This is a file generated using the command below. In it contains all the installations installed in the virtual environment. Use the command below to add this file in your root directory.

pip freeze> requirements.txt

Doing this will add a file in your root directory, and thus your final structure at this point should look like this:

Other files that you will want to include in your root directory include:

.travis.yml: Which will enable you to run your tests and obtain your test coverage

Procfile: Will assist when hosting your application on Heroku

And by the way, my files are green in color because I have pylint (an extension that enables you to detect errors in your code before running it)

Congratulations, you have the app structure the Andela way, and your app is running. You can now go ahead and create your APIs.

If you are having a blocker or stack, Just slack me (SimonAntonny) or (Munniomer)