DEV Community: fergus-mk

Todo App - Project Idea - Flask/PostgreSQL/Docker

fergus-mk — Sat, 19 Aug 2023 11:46:17 +0000

Creating a todo app is a great way to get familiar with some core programming technologies. In this post I show an example Python project which uses Flask, PostgreSQL, and Docker. The code is available in this GitHub repo You can use this as inspiration to create your own app.

Technologies Used

First I want to briefly introduce the technologies I have used and explain why:

What is it: A lightweight web framework which lets you build web applications quickly with a minimal amount of code.

Why Use It: It is easy to start with and flexible. I like it for learning as rather than giving you a strict framework it lets you think critically about the structure you choose.

What is it: A very popular open-source relational database management system (RDBMS)

Why Use It: It is suitable for handling large datasets and has support for lots of different data types.

What is it: A platform that allows you to build software in containers. A container holds everything to run your application including the code, runtime, system tools, and libraries. This makes it a lot easier to run it on different servers and to collaborate as your app grows.

Why Use It: It ensures your application runs the same everywhere (local machine, virtual machine etc.) This makes it easier to scale your app and collaborate.

The App:

The App is an API which lets you create, update and delete todos. First you make a user who can log in with their password and then they can interact with their todo list.

First I will show an example from the the API endpoint documentation and then I am going to show you the structure of my project a long with a brief explanation and some tips for your own design.

API Endpoints

User Routes

Create a new user
- URL: /api/users
- Method: POST
- Data Params: ```
{
"first_name": "[string]", // Non-empty, max 50 chars, only alpha
"last_name": "[string]", // Non-empty, max 50 chars, only alpha

"email": "[unique string]", // Valid email with '@'
"password": "[string]" // Contains at least 5 chars, 1 number and 1 special char
}

- Success Response: 
      - Code: `201 CREATED`
      - Content: `{ id: [integer], first_name: "[string]", last_name: "[string]", email: "[unique string]" }`
    - Error Response:
      - Code: `409 CONFLICT`

See [app readme](https://github.com/fergus-mk/simple-todo-app/tree/master) for full documentation of the endpoints available. Essentially these let users:
- Create update and delete users
- Create update and delete todos
- Get a token which is used to login

## Project Structure

📂 **simple_todo_app**
- 📁 **app/**: *The heart of the application.*
        - 📄 `__init__.py`: Initialises routes and db 
    - 📁 **auth/**: *Handles authentication.*
        - 📄 `auth.py`: User authentication logic.
    - 📁 **config/**: *Configuration settings.*
        - 📄 `config.py`: Used to access env variables.
    - 📁 **crud/**: *CRUD operations.*
        - 📄 `todo_crud.py`: Manage to-do interaction with db.
        - 📄 `user_crud.py`: Manage user interaction with.
    - 📁 **helpers/**: *Functions used*
        - 📄 `extensions.py`: Used to initialise ORM and stop circular imports .
        - 📄 `helpers.py`: General functions.
        - 📄 `validators.py`: Validates data.
    - 📁 **models/**: *Data models.*
        - 📄 `models.py`: ORM models (using objects to manage db interaction).
    - 📁 **routes/**: *URL routes.*
        - 📄 `routes.py`: Maps URL routes to functions.

- 📁 **migrations/**: *Database migrations.*
- 📄 **Dockerfile**: Containerize the application.
- 📄 **app.py**: *Application's entry point.*
- 📄 **docker-compose.yaml**: Docker multi-container configurations.
- 📄 **requirements.txt**: *Project dependencies.*

## Explanation
The application doesn't strictly follow a MVC design pattern however I have tried to separate different components where possible. It follows a basic structure where 📄 app.py calls 📄 app/init.py and this file initialises the roots and the db.

📄 **app.py**

from app import create_app

app = create_app()

if name == "main":
app.run(host='0.0.0.0', debug=True, port=8001)


📄 **app/init.py**

from flask import Flask
from flask_migrate import Migrate
from flasgger import Swagger

from app.config.config import Config
from app.helpers.extensions import db, ma
from app.models.models import User, Todo
from app.routes.routes import init_user_routes, init_todo_routes, init_auth_routes

def create_app():
"""Create app instance"""
app = Flask(name)
app.config.from_object(Config)

db.init_app(app) # Initalize db with app
ma.init_app(app) # Initalize marshamallow with app
migrate = Migrate(app, db) # Migrate db with app

Swagger(app) # Will be used to create OpenAPI documentation 

with app.app_context():     
    db.create_all() # Create all db tables

init_user_routes(app)
init_todo_routes(app)
init_auth_routes(app)

return app


The 📁 app/auth/ dir handles authorisation and authentication of users. 📁 app/config holds some info used to connect to the db (it is essentially there to keep code neat). 📁 app/crud contains the functions that directly read and write to the db (for both users and todos). 📁 app/helpers is a generic folder containing some functions and extra functionality. 📁 app/models is contains Python objects which are used to interact with the db (this is ORM which is explained below).

📄 **app/models/models.py**

from marshmallow import fields

from app.helpers.extensions import db, ma

class Todo(db.Model):
"""Todo table containing todo items for users"""
tablename = "todo"
id = db.Column(db.Integer, primary_key=True)
user_email = db.Column(db.String, db.ForeignKey("user.email"))
content = db.Column(db.String, nullable=False)
priority = db.Column(db.Integer, nullable=False, default=1)

class TodoSchema(ma.SQLAlchemyAutoSchema):
"""TodoSchema for serializing and deserializing Todo instances"""
class Meta:
model = Todo
load_instance = True # Deserialize to model instance
sqla_Session = db.session
include_fk = True # So marshmallow recognises person_id during serialization
user_email = fields.Str()
content = fields.Str()
priority = fields.Integer()

class User(db.Model):
"""User table containing user details"""
tablename = "user"
id = db.Column(db.Integer, primary_key=True)
email = db.Column(db.String(50), unique=True)
first_name = db.Column(db.String(50))
last_name = db.Column(db.String(50))
password = db.Column(db.String, nullable=False)

todos = db.relationship(
    Todo,
    backref="user",
    cascade="all, delete, delete-orphan",
    single_parent=True
)

def __repr__(self):
    return f"User {self.first_name} {self.last_name} with email {self.email}"

class UserLoadSchema(ma.SQLAlchemyAutoSchema):
"""UserLoadSchema for deserializing User instances"""
class Meta:
model = User
load_instance = True
sqla_Session = db.session
include_relationships = True # This means it will also go into neighbouring schema
exclude = ("id", "password") # Exclude password and id during deserialization

email = fields.Str()
first_name = fields.Str()
last_name = fields.Str()
password = fields.Str() # Password needed for user load
todos = fields.Nested(TodoSchema, many=True)

class UserDumpSchema(ma.SQLAlchemyAutoSchema):
"""UserDumpSchema for serializing User instances"""
class Meta:
model = User
load_instance = True # Deserialize to model instance
sqla_Session = db.session
include_relationships = True
exclude = ("id", "password")

email = fields.Str()
first_name = fields.Str()
last_name = fields.Str()
todos = fields.Nested(TodoSchema, many=True)

Initialized schemas for global use throughout the app

todo_schema = TodoSchema()
todos_schema = TodoSchema(many=True) # Many=True to serialize a list of objects
user_load_schema = UserLoadSchema() # Used for deserializing user data from requests
user_dump_schema = UserDumpSchema() # Used for serializing user data to responses


Within the root folder 📁 migrations is used for db migrations (essentially version control for the db). The 📄 docker-compose.yml is used to define the relationship between the apps two containers (one for the Flask app and one for the PostgreSQL db). 📄  Dockerfile specifies the details of the Flask app (there isn't one for PostgreSQL as this is built on the standard PostgreSQL Docker image). The 📄 requirements.txt file defines the packages needed for the Flask app.

📄 **docker-compose.yml**

version: '3.8'
services:
web:
build: .
volumes:
- .:/app
ports:
- "8001:8001"
depends_on:
- pgsql
environment:
- FLASK_APP=app:create_app
- FLASK_RUN_HOST=0.0.0.0

pgsql:
image: postgres:12.11
restart: always
volumes:
- postgres_data:/var/lib/postgresql/data/
env_file:
- .env
ports:
- 5432:5432

volumes:
postgres_data:


## Things to consider in your design
- **ORM** - The app uses Object-Relational Mapping which simplifies interaction between Object-Oriented languages (e.g. Python) and a database. For a proper explanation see [free code camps explanation](https://www.freecodecamp.org/news/what-is-an-orm-the-meaning-of-object-relational-mapping-database-tools/)
- **Database Migrations** - The app has database migrations which are handy for tracking changes to your db.
- **Structure** - As I mentioned above I have tried to separate different app components. In general this makes your app easier to debug, maintain and scale.
- **Marshmallow** - Is a Python library used for serialisation/deserialisation (converting data types) and also doing data validation

__I hope you enjoyed the post and it inspires you for you own project!__

Data Analytics X Sustainability - Top Free Technologies

fergus-mk — Fri, 18 Aug 2023 12:26:43 +0000

Combining Data & Sustainability: 3 Great Software Solutions

Are you a MSc student from data or sustainability backgrounds? Interested in merging the two areas in your research? Here are three free software tools that you can use to conduct your interdisciplinary research. Let's dive in!

1. Google Earth Engine (GEE)

GEE is a cloud-based platform that lets you access satellite imagery from some of the world’s major space agencies including NASA’s Copernicus imagery and Sentinel imagery from the European Space Agency. It utilises Google's cloud computing resources and runs your analysis in parallel over numerous servers, which makes it excellent for handling large amounts of data.

Features:

Access to satellite imagery from NASA and ESA.
Utilises Google's cloud computing resources.
Excellent for handling large data.
Pre-processing satellite imagery handled automatically.

GEE Resources:

2. QGIS

QGIS is an open-source GIS software with a user-friendly GUI. It has an active community who are constantly making new tools for it. You can also use code to interact with your data if you prefer. QGIS is easy to pick up and use without a steep learning curve and offers a great way to visually see and interact with your data. Compared with GEE, it is considerably more flexible. QGIS's paid-for competitor is ArcGIS Pro and honestly I recommend QGIS, the features are broadly similar and QGIS has more functionality due to open-source community.

Features:

Open-source GIS software.
User-friendly GUI.
Active community support.
Can be integrated with coding.

QGIS Resources:

3. OpenLCA

OpenLCA does what it says on the tin; it is open-source software that allows you to conduct Lifecycle Analysis (or LCA). LCA involves quantifying the environmental impact of a good or substance over its lifecycle. This can mean you can understand the full environmental impact of goods, products and commodities. The only issue I have with OpenLCA is that the API doesn't really work (note they are developing it). This means you cant interact with it programatically in the same way you use the paid-for competitor SimaPro. If this is a dealbreaker, Brightway2 is a Python native alternative.

Features:

Open-source software for LCA.
Allows interaction with LCA databases.
Calculates quantified impacts of various goods and commodities.

OpenLCA Resources:

Wrapping Up

These three tools are a great starting point for anyone looking to merge data analytics with sustainability research. If anyone has used any of these tools or a competitor I'd love to hear your opinion!

Making a Simple Python Text Based Game

fergus-mk — Sat, 29 Jul 2023 07:48:16 +0000

Making a simple text based game is a great way for a beginner to work on their programming skills and get exposed to Object-Oriented Programming (OOP). Once you have a basic design it is easy to further expand upon this and make your game more complicated. This post shows you a simple text based game and explains how you would create your own.

Goblins & Gladiators lets players can create goblin and gladiator type characters and make them fight (a little like Pokemon). You can find the Github repo for the game here, please feel free to use this as inspiration for your own game.

As you can see the game has highly sophisticated industry-leading graphics developed by the Unreal Engine 5:

# A Goblin
               ||                                ||
               ||||                            ||||
               |||||                          |||||
               ||||||                        ||||||
               |||||||                      |||||||
               ||||||||||||||||||||||||||||||||||||
               ||||||||||||||||||||||||||||||||||||
               ||||||||||||||||||||||||||||||||||||
                ||||||||||||||||||||||||||||||||||
                 |||||||     ||||||||     |||||||
                 ||||||||||||||||||||||||||||||||
                 ||||||||||||||||||||||||||||||||
                 ||||||||||||||||||||||||||||||||
                 ||||||||||            ||||||||||
                 ||||||||||||||||||||||||||||||||
                   ||||||||||||||||||||||||||||
                      ||||||||||||||||||||||
                         ||||||||||||||||
                              ||||||

The steps to make your game
Designing and making your game follows 3 simple steps:

Brainstorm
Model
Coding

Step 1 - Brainstorm
Before you begin jumping in an writing code you want to have some idea of what your game will be like and how it will be played. Think along the lines of What will the characters in the game be like? What will they do? Will they interact with each other and if so how?.

Personally I find using pen and paper can be great for sketching out initial ideas. You might come up with a diagram something like this:

Step 2 - Model
Creating a model is the next step in the process. This is generally done using Unified Markup Language (UML). This lets you take your sketch and describe your game and show how the different components will interact with each other. It is similar to the sketch but more detailed and more closely related to how the game will be coded.

I have included an example from Goblins & Gladiators below. You will note that the design has changed a little from the sketch. This is totally fine, the process of designing and modelling your game should be iterative so don't worry if you have to go back and make changes. I am not going to explain my diagram in detail, I just wanted to give a rough idea of what one might look like.

You will notice that goblin and gladiators both inherit from characters. This essentially means they are a type of character and share some of its features. If this is new to you I encourage you to learn a bit about OOP, I have included resources below.

Step 3 - Code
The final step is to actually code your game. Again this can be iterative and you may come up with new ideas and revisit the previous step to change the design. I have included an example of the character class in the game which serves as the basis for both goblins and gladiators.

class Character(ABC):
    __character_list = None  # Used in static method to return created characters

    def __init__(self, name, attack_strength, defence_strength, max_hp, item=""):
        """
        Constructor class that initiates Character objects
        """
        self.name = name
        self.attack_strength = attack_strength
        self.defence_strength = defence_strength
        self.max_hp = max_hp
        self.hp = max_hp  # Current hp can be equal to or less than max hp
        self.item = (
            item  # The character has no item as default but can equip up to 1 item
        )

    def attack(self, opponent):
        """
        Deals damage to opponent, note attack has random chance of missing and dealing 0 damage

        Parameters
        ----------
        opponent
            The character affected (Character)

        Returns
        --------
            If the attack is successfull, opponent receives damage from the attack. The amount of 
            damage dealt is equal to the attack_strength attacking character + randomized value 
            - defence_strength of defending chatacter. If the attack misses a string is printed to 
            notify attack has missed and no damage is dealt 
        """
        if self == opponent:
            print(f"{self.name} cannot attack itself, enter a different target")
            return None
        else:
            attack_hit_or_miss = randint(0, 4)  # Attack has random chance of missing
            if attack_hit_or_miss == 0:
                print("attack missed")
            else:
                random_damage_value = randint(
                    -1, 2
                )  # Random number altering the strength of attack

                opponent.receive_damage(
                    self.attack_strength
                    + random_damage_value
                    - opponent.defence_strength
                )
                if opponent.hp > 0:
                    print(
                        f"{self.name} attacked {opponent.name} who now has {opponent.hp} hp"
                    )
                elif opponent.hp <= 0:
                    print(
                        f"{self.name} defeated {opponent.name} who is now dead. {self.name} has won the contest"
                    )
                    visuals.win_visual()

    def equip_item(self, attatch_item):
        """
        Equips selected item to character

        Parameters
        ----------
        attatch_item
            The item the character is equipping (Item)

        Returns
        -------
            The character with its equipped item local parameter equal to the item name. This allows
            the character to use the equipped item
        """
        self.item = attatch_item.name
        print(f"{self.name} has now equipped {attatch_item.name}")

    def receive_damage(self, damage_amount):
        """
        Removes amount of damage recieved from own hp

        Parameters
        ----------
        damage_amount
            The amount of damage to recieve (int)

        Returns
        -------
            The character with damage_amount subtracted from its hp
        """
        self.hp = self.hp - damage_amount

    def character_details(self):
        """
        Gives key character details in a human readable sentence (more information than __str__)

        Returns
        --------
            The name, hp, attack_strength and defence_strength of the character 
        """
        return f"{self.name} has {self.hp} hp, {self.attack_strength} attack_strength and {self.defence_strength} defence_strength"

    @staticmethod
    def get_character_list():
        """
        Ensures only a singleton list of characters 

        Example
        -------
            the_characters = Character.get_character_list()
            the_characters.append(new_goblin_character)
            the_characters.append(new_gladiator_character)
            print(the_characters)
        """
        if Character.__character_list == None:
            Character.__character_list = []
        return Character.__character_list

Again don't get bogged down in the details. This has just been included as an example.

Playing The Game
Now of course this is the important part. Actually playing the game. There are detailed instructions in the repo, but I wanted to give you a quick preview. Basically creating characters looks a little like this:

flame_goblin = characters.Goblin('flame goblin', 'fire')
fighter = characters.Gladiator('fighter')

You can then get them to attack each other (or use healing spells and other special abilities):

flame_goblin.attack(fighter)
flame goblin attacked fighter who now has 8 hp"

The fight continues until one character dies and loses. The game also shows some of the graphics I showed earlier.

Resources

This course by Olivia Chiu Stone and Baron Stone is great for learning about object oriented design (note it is paid for)
This video is a great example of a simple Pokemon text based game
This page has some more example project designs