Flash-Blog

A lightweight micro-blogging engine built with Flask and HTMX. This is an educational repository designed for practicing open source contributions.

Project Overview

Flash-Blog is a fully functional micro-blogging application that demonstrates modern web development patterns using:

• Backend: Python 3.13+ with Flask 3.1.2
• Frontend: HTMX 2.0.8 for dynamic interactions without complex JavaScript
• Database: SQLite (supports both in-memory and persistent storage)
• Package Manager: uv for fast dependency management

Features

• User registration and authentication
• Create, edit, and delete blog posts
• Comment system with real-time updates via HTMX
• Full REST API for programmatic access
• Search functionality
• User profiles with bio
• Pagination for posts

Learning Objectives

This repository contains intentionally seeded issues across different difficulty levels. By working through these issues, you will learn:

1. HTTP Methods: Understanding GET, POST, PUT, DELETE in a real application
2. Database Operations: SQLite queries, schema design, and proper parameterization
3. Session Management: User authentication and secure password handling
4. API Design: RESTful endpoints and JSON responses
5. Frontend-Backend Integration: Using HTMX for dynamic updates
6. Testing: Writing and running pytest tests
7. Git Workflows: Forking, branching, pull requests

Quick Start

Prerequisites

• Python 3.13 or higher
• uv package manager

Installation

1. Clone the repository:

git clone https://github.com/anxkhn/flash-blog-workshop.git
cd flash-blog-workshop

2. Install dependencies using uv:

uv sync

3. Run the application:

uv run flask --app run:app run

4. Open your browser at http://localhost:5000

Using in-memory database (default for development)

The application uses SQLite in development mode. For testing, an in-memory database is used automatically.

Using persistent database

Set the DATABASE_PATH environment variable:

export DATABASE_PATH=blog.db
uv run flask --app run:app run

Project Structure

flash-blog-workshop/
flash_blog/
__init__.py          # Application factory
config.py            # Configuration settings
database.py          # Database utilities
auth/                # Authentication module
__init__.py
routes.py
blog/                # Blog module
__init__.py
routes.py
api/                 # REST API module
__init__.py
routes.py
templates/           # Jinja2 templates
base.html
auth/
login.html
register.html
profile.html
blog/
index.html
view.html
create.html
edit.html
user_posts.html
search.html
partials/
comments.html
search_results.html
static/
css/
style.css
tests/               # Test files
conftest.py
test_factory.py
test_database.py
test_auth.py
test_blog.py
test_api.py
pyproject.toml       # Project configuration
README.md
CONTRIBUTING.md
LICENSE

Test Commands

Run all tests:

uv run pytest

Run specific test file:

uv run pytest tests/test_auth.py

Run with verbose output:

uv run pytest -v

Issue Labels Guide

Label	Color	Description
good-first-issue	Purple	Good for newcomers (15-30 min)
intermediate	Yellow	Moderate difficulty (1-2 hours)
advanced	Orange	Complex challenge (3-6 hours)
bug	Red	Something is not working
documentation	Blue	Improvements to docs
tests	Cyan	Related to testing
enhancement	Cyan	New feature or request
security	Red	Security vulnerability
performance	Yellow	Performance optimization
refactoring	Yellow	Code quality improvements
ci-cd	Gray	CI/CD pipeline issues

Using github.dev

For quick edits without local setup:

1. Press . (period) while viewing any file on GitHub
2. This opens the web-based VS Code editor
3. Make your changes and commit directly

Contributing

See CONTRIBUTING.md for detailed guidelines on:

• Setting up your development environment
• Creating issues and pull requests
• Code style guidelines
• Testing requirements

License

This project is licensed under the MIT License - see the LICENSE file for details.