You’ve already started your Python project by following the best practices I mentioned in the previous article, right?

Now, it’s time to focus on maintaining your project, this involves ensuring that the project remains organized, functional, easy to share and scale.

1. requirements.txt

The requirements.txt file lists all the dependencies your project needs to run. This file allows others to recreate your environment and automate in pipelines.

Steps:

• To generate the file, use the command:

pip freeze > requirements.txt

• To install dependencies from the file, use:

pip install -r requirements.txt

2. Update Your README.md and MkDocs

A well-documented project avoid this:

README.md should contain:

• Project Description
• Installation Instructions and How to Run
• Usage Examples
• Contribution Guidelines (Open Source)

MkDocs is a tool for creating professional documentation sites:

• Install MkDocs:

pip install mkdocs

# or 

poetry add mkdocs

• Create a documentation project:

mkdocs new project-docs

• Serve the site locally with:

cd project-docs
mkdocs serve 

• Deploy to GitHub Pages with:

mkdocs gh-deploy

Now you will have a well-documented project!

3. Pre-commit

Pre-commit hooks automate checks before allowing changes to be committed.

This can help you save a lot of time and enforce code quality preventing common errors.

Steps:

• Install Pre-commit with:

pip install pre-commit

• Add a .pre-commit-config.yaml file with hooks for tasks like fixing trailing whitespace or linting.

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0 
    hooks:
      - id: check-yaml # check-yaml: Ensures your YAML files are valid.
      - id: end-of-file-fixer # end-of-file-fixer: Ensures there’s exactly one newline at the end of files.
      - id: trailing-whitespace # trailing-whitespace: Removes trailing whitespace from files.
      - id: debug-statements # debug-statements: Warns about leftover print() or pdb statements.
  - repo: https://github.com/psf/black
    rev: 23.9.1 
    hooks:
      - id: black # black: Formats your Python code according to the Black code style.
        language_version: python3

• Install the hooks using:

pre-commit install

• Test the Pre-Commit hooks:

pre-commit run --all-files

• Expected return:

(venv) PS C:\WVS\project-docs> pre-commit run --all-files
check yaml...............................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
debug statements (python)................................................Passed
black....................................................................Passed

Now, every commit will run these checks automatically.

4. Docker

If you’re sharing your project using a requirements.txt file, you should also consider using Docker in the same way.

Make all your projects Docker-first because it’s the most effective method for ensuring that others can easily replicate and run them on their machines.

And of course guarantees consistent environments across development and testing stages.

Steps:

• Create a Dockerfile defining the project’s environment and dependencies.

# Use the official Python image as the base image
FROM python:3.12-slim

# Set the working directory inside the container
WORKDIR /app

# Copy the requirements file and install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy the application code into the container
COPY src/ ./src/

# Expose the port the app runs on
EXPOSE 5000

# Set the default command to run the application
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "src.app:app"]

• Build the Docker Image:

docker build -t api .

• Run the Docker Container:

docker run -p 5000:5000 --env-file .env api

Tip: Add a .dockerignore File to prevent unnecessary files from being copied into the Docker image, if necessary.

5. Test-Driven Development (TDD)

Test-Driven Development (TDD) involves writing tests before implementing the functionality.

Instead of you going to test manually, you can write some tests to simulate some actions.

Steps:

• Install Testing Dependencies:

pip install pytest

# or

poetry add pytest

• Create a tests/ Directory
• Here are an example from my code:

import sys
import os
import pytest

# Add the 'src' directory to the Python path
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../src')))

from app import app

@pytest.fixture
def client():
    app.config['TESTING'] = True
    with app.test_client() as client:
        yield client

def test_api_is_up(client):
    # Send a GET request to the root endpoint
    response = client.get('/')

    # Assert that the response status code is 200 (OK)
    assert response.status_code == 200

• Run the tests using pytest:

pytest

• Expected return:

=========================================== test session starts ===========================================
platform win32 -- Python 3.11.5, pytest-8.3.3, pluggy-1.5.0
rootdir: C:\wvs\api
configfile: pyproject.toml
plugins: flask-1.3.0
collected 1 item

tests\test_app.py .                                                                                  [100%]

============================================ 1 passed in 0.31s ============================================ 

6. CI/CD

CI/CD automates tasks like testing and deploying your code.

With sure testing is good, but let CI/CD pipelines test and deploy for you!

Steps:

• Create a configuration file: .github/workflows/pipeline.yml:

name: Python Only CI  

on: 
  push:
    branches:
      - main
  pull_request:
    branches:
      - main  

jobs:  
  build:  
    runs-on: ubuntu-latest  

    steps:  
    - uses: actions/checkout@v3  

    - name: Set up Python  
      uses: actions/setup-python@v4  
      with:  
        python-version: '3.12'  

    - name: Install dependencies  
      run: pip install -r requirements.txt  

    - name: Run tests  
      run: pytest   

This ensures tests run automatically whenever code is pushed or a pull request is made.

By following these practices, you ensure your project is professional.

This guide documents the steps I take to set up the foundation of any Python project, with a focus on environment setup, version control, and project structure.

1. Git & GitHub Repository

If your project doesn’t have a local and a remote repository, you could be in danger, Git and GitHub is essential for tracking changes and backing up your code.

Steps:

• Create a local repository in your project directory:

git init

• Create a remote repository on GitHub.
• Link the remote repository to your local one and send your first commit:

echo "# python-requests-site" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/lorenzouriel/python-requests-site.git
git push -u origin main

A project without version control could be at risk if anything goes wrong with your code

2. Virtual Environment

Using a virtual environment ensures that your project dependencies do not interfere with other Python projects on your system. It isolates your environment and keeps everything clean.

Steps:

• Create a virtual environment:

python -m venv venv

• Activate the virtual environment:

# Windows
.\venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

Once activated, any Python packages you install will go to the .venv folder and not affect other projects.

3. Use Pyenv

Pyenv allows you to manage multiple Python versions on your system.

It’s useful if you need to test your project with different Python versions or if you want to keep the Python versions for your projects isolated.

Steps:

• Install Pyenv on your system by following the installation guide.
• Install a specific version of Python:

pyenv install 3.12.0

• Set the local Python version for your project

pyenv local 3.12.0

A file called .python-version will be created in your project tree.

This ensures that your project will use the specified Python version, no matter what the global system version is.

4. Use Poetry

Poetry is a dependency manager and build tool for Python projects.

It simplifies dependency management and packaging, making it easier to maintain and share Python projects.

Steps:

• Install Poetry by following the installation guide.
• Once installed, initialize Poetry in your project:

poetry init

• Poetry will guide you through creating a pyproject.toml file, where your dependencies will be listed.
• To install dependencies, run:

poetry install

• Poetry also allows you to create a virtual environment and set the python version:

poetry shell  # Create and log into a shell within the virtual environment
poetry env use 3.12.0  # Sets the version of Python to be used by virtual project environment

The main point is dependency resolution in a clean and efficient way.

Here is a example of a pyproject.toml file with the lib requests installed:

[tool.poetry]
name = "python-requests-site"
version = "0.1.0"
description = ""
authors = ["Lorenzo Uriel <your-email@gmail.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"
requests = "^2.32.3"


[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

5. Create a .gitignore and a .env

.gitignore: This file tells Git which files and directories should not be tracked by version control. This helps prevent sensitive or unnecessary files from being pushed to GitHub.

.env: This file contains environment variables such as API keys, database URLs and other configuration values. It’s important to keep this file private, so it should never be committed to the repository.

Steps:

• In the case of .gitignore I always use the toptal model, you can check here.
• Just create the files and add the values:

# Windows
New-Item .gitignore
New-Item .env


# macOS/Linux
touch .gitignore
touch .env

Here’s a great starting point for creating a Python project from scratch, there are several other approaches you can take to ensure the project is maintained according to best practices.