DEV Community: Huy Nguyen

🚀 Supercharge Your FastAPI WebSockets with Channel Layers & Group Messaging

Huy Nguyen — Thu, 18 Sep 2025 02:38:11 +0000

Building real-time features in FastAPI? Hit the wall trying to send messages from HTTP endpoints to WebSocket clients? Struggling with group messaging and scalability?

Fast Channels brings Django Channels' battle-tested architecture to FastAPI and the entire ASGI ecosystem.

The Pain Points We've All Hit

FastAPI's native WebSocket support gets you started, but quickly becomes limiting:

❌ No group messaging - can't broadcast to multiple connections

❌ No cross-process communication - HTTP endpoints can't reach WebSocket clients

❌ Manual connection management - tracking users, rooms, cleanup

❌ No scalability - everything breaks with multiple server instances

❌ Testing nightmare - WebSocket unit tests are painful to write

What Fast Channels Delivers

✅ Group messaging - broadcast to chat rooms, user segments, notification groups

✅ Cross-process communication - HTTP → WebSocket, background workers → clients

✅ Auto connection management - join/leave groups automatically

✅ Multi-instance scaling - Redis-backed message routing

✅ Built-in testing framework - proper WebSocket test utilities

✅ Consumer patterns - WebSocket handlers that feel like FastAPI views

Battle-Tested in Production

This isn't experimental tech. Django Channels has powered real-time features for millions of users across thousands of production applications for years. Fast Channels brings that same proven architecture to FastAPI.

# Simple but powerful
class ChatConsumer(AsyncWebsocketConsumer):
    groups = ["chat_room"]  # Auto-join on connect

    async def receive(self, text_data=None, **kwargs):
        # Broadcast to all users in the room
        await self.channel_layer.group_send("chat_room", {
            "type": "chat_message",
            "message": text_data
        })

Production-Ready Features

Redis Integration: Full Redis support with Sentinel for high availability

Multiple Backends: In-memory for testing, Redis Queue for reliability, Redis Pub/Sub for speed

Type Safety: Complete mypy and pyright support

ASGI Universal: Works with FastAPI, Starlette, Quart, any ASGI framework

Testing Built-in: Comprehensive WebSocket testing utilities

FastAPI vs Fast Channels vs Alternatives

Feature	Native FastAPI	Broadcaster	Fast Channels
Basic WebSocket	✅	✅	✅
Group messaging	❌	✅	✅
Consumer patterns	❌	❌	✅
Message persistence	❌	❌	✅
Testing framework	❌	❌	✅
Auto connection mgmt	❌	❌	✅
Cross-process msgs	❌	❌	✅
Production battle-tested	❌	❌	✅

Real-World Impact

Teams are using Fast Channels for:

🏪 E-commerce: Live inventory, order tracking, flash sale updates

💬 Chat platforms: Real-time messaging, typing indicators, presence

📊 Dashboards: Live metrics, system monitoring, alerts

🎮 Gaming: Multiplayer sync, leaderboards, real-time events

🔔 Notifications: Push alerts, system updates, user notifications

Quick Start

pip install fast-channels[redis]

Register a channel layer, create a consumer, add to FastAPI - done. Your WebSockets now scale across multiple processes and servers.

Why It Matters

Real-time features shouldn't require reinventing messaging infrastructure. Fast Channels gives you Django's proven patterns with FastAPI's developer experience - the best of both worlds.

Production-ready: Redis Sentinel support, proper error handling, connection cleanup

Developer-friendly: Type safety, testing utilities, clear documentation

Scalable: Multi-process, multi-server, battle-tested architecture

Stop building WebSocket boilerplate. Start building features.

🔗 Links:

Building real-time features? What's your biggest WebSocket challenge? 👇

Building a Modern, Type-Safe Authentication System for Django REST Framework

Huy Nguyen — Wed, 09 Jul 2025 13:59:32 +0000

Have you ever spent hours fighting with authentication setup in your Django REST API? Or struggled with type errors that could have been caught at development time? Or wished your API documentation would just... work automatically?

I've been there. After years of wrestling with existing Django authentication packages, I decided to build something better: DRF Auth Kit – a modern, type-safe authentication toolkit that just works.

The Problem: Authentication Shouldn't Be This Hard

Let me paint a picture. You're building a modern web app with a Django REST API backend. You need:

✅ JWT authentication with cookie support

✅ Multi-factor authentication

✅ Social login (Google, GitHub, etc.)

✅ Automatic API documentation

✅ Type safety throughout

With existing solutions, you'd typically:

Install 3-4 different packages
Write custom serializers and views
Manually configure complex URL patterns
Struggle with type hints and documentation
Debug cryptic authentication errors

There had to be a better way.

The Solution: DRF Auth Kit

DRF Auth Kit is what I wish existed when I started building Django APIs. Here's what makes it different:

🎯 One Package, Everything Included

# Get everything you need
pip install drf-auth-kit[all]

# Or pick what you need
pip install drf-auth-kit[mfa]     # + Multi-factor auth
pip install drf-auth-kit[social]  # + Social authentication

🔒 Universal Authentication Backend

Instead of juggling multiple authentication classes:

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'auth_kit.authentication.AuthKitAuthentication',
    ],
}

AUTH_KIT = {
    'AUTH_TYPE': 'jwt',  # or 'token', 'custom'
    'USE_AUTH_COOKIE': True,
    'USE_MFA': True,
}

This single configuration handles:

JWT tokens with automatic refresh
DRF token authentication
Custom authentication backends
HTTP-only cookies with security headers
Multi-factor authentication

🛠️ Intelligent URL Management

Conditional URL patterns - URLs automatically included/excluded based on settings:

# When USE_MFA=True, automatically creates:
# POST /api/auth/login/         # First step (password)
# POST /api/auth/login/verify/  # Second step (MFA code)
# POST /api/auth/login/change-method/
# POST /api/auth/login/resend/
# GET /api/auth/mfa/           # MFA management endpoints

# When USE_MFA=False, creates:
# POST /api/auth/login/         # Direct login

Social authentication - automatic endpoint generation:

# Just add a provider to INSTALLED_APPS:
INSTALLED_APPS = [
    'allauth.socialaccount.providers.google',
    'auth_kit.social',
]

# Automatically creates:
# POST /api/auth/social/google/
# POST /api/auth/social/google/connect/
# GET /api/auth/social/accounts/

📝 Type Safety That Actually Works

Every component includes comprehensive type hints:

from auth_kit.authentication import AuthKitAuthentication
from auth_kit.serializers import LoginRequestSerializer
from auth_kit.views import LoginView

Full mypy and pyright compatibility with comprehensive type hints throughout the codebase. Your IDE will thank you. No more guessing what parameters a function expects or what a setting does.

📚 API Documentation That Updates Itself

Integration with DRF Spectacular means your API docs are always current:

# Zero configuration needed
INSTALLED_APPS = [
    'drf_spectacular',
    'auth_kit',
]

Visit /api/docs/ and you'll see:

Interactive Swagger UI
Complete request/response schemas
Authentication flow examples
Working test interface

🛡️ MFA Made Simple

Multi-factor authentication that doesn't require a PhD:

# Enable MFA
INSTALLED_APPS = [
    'auth_kit',
    'auth_kit.mfa',  # Just add this!
]

AUTH_KIT = {
    'USE_MFA': True,  # URLs automatically reconfigure
}

Automatic URL reconfiguration when MFA is enabled:

Login endpoint becomes two-step flow
MFA management endpoints automatically created
All endpoints documented in your OpenAPI schema

You get:

Email-based MFA with HTML/text templates
Authenticator app support (Google Authenticator, Authy)
Backup codes for account recovery
Extensible system for custom MFA methods

The login flow becomes a clean two-step process:

Username/password → Get ephemeral token
MFA code → Get final auth tokens

🌐 Social Authentication That Just Works

Social login with 50+ providers and automatic URL generation:

INSTALLED_APPS = [
    'auth_kit',
    'auth_kit.social',  # Automatic URL generation
    'allauth.socialaccount.providers.google',
    'allauth.socialaccount.providers.github',
    # Add any provider, URLs created automatically!
]

# URLs are automatically created for each provider:
# POST /api/auth/social/google/
# POST /api/auth/social/github/
# POST /api/auth/social/google/connect/
# POST /api/auth/social/github/connect/
# GET /api/auth/social/accounts/

No manual URL configuration needed! The system scans your installed providers and creates endpoints automatically.

🍪 Security-First Cookie Authentication

HTTP-only cookies with all the security features:

AUTH_KIT = {
    'USE_AUTH_COOKIE': True,
    'AUTH_COOKIE_SECURE': True,      # HTTPS only
    'AUTH_COOKIE_HTTPONLY': True,    # No JavaScript access
    'AUTH_COOKIE_SAMESITE': 'Lax',   # CSRF protection
}

Perfect for modern web apps where you want security without complexity.

Real-World Example: Complete Auth Setup

Here's how you'd set up a complete authentication system:

# settings.py
INSTALLED_APPS = [
    'rest_framework',
    'auth_kit',
    'auth_kit.mfa',
    'auth_kit.social',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    'allauth.socialaccount.providers.google',
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'auth_kit.authentication.AuthKitAuthentication',
    ],
}

AUTH_KIT = {
    'AUTH_TYPE': 'jwt',
    'USE_AUTH_COOKIE': True,
    'USE_MFA': True,
}

# Social auth providers
SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'SCOPE': ['profile', 'email'],
        'AUTH_PARAMS': {'access_type': 'online'},
        'OAUTH_PKCE_ENABLED': True,
        'APP': {
            'client_id': 'your-google-client-id',
            'secret': 'your-google-client-secret',
        }
    }
}

# urls.py
from django.urls import path, include

urlpatterns = [
    path('api/auth/', include('auth_kit.urls')),
    path('api/auth/social/', include('auth_kit.social.urls')),
]

That's it! You now have:

JWT authentication with cookies
User registration and email verification
Password reset functionality
Multi-factor authentication
Social login with Google
Complete API documentation
Type safety throughout

Customization: Make It Yours

Need custom behavior? Override any component:

# Custom login serializer
class CustomLoginSerializer(LoginRequestSerializer):
    remember_me = serializers.BooleanField(default=False)

    def validate(self, attrs):
        attrs = super().validate(attrs)
        # Your custom logic here
        return attrs

# Apply it
AUTH_KIT = {
    'LOGIN_REQUEST_SERIALIZER': 'myapp.serializers.CustomLoginSerializer',
}

Want a custom MFA method? Easy:

class SMSMFAHandler(BaseMFAHandler):
    name = "sms"

    def send_code(self, user: User, code: str) -> None:
        # Your SMS implementation
        send_sms(user.phone, f"Your verification code: {code}")

# Register it
AUTH_KIT = {
    'MFA_HANDLERS': [
        'auth_kit.mfa.handlers.app.MFAAppHandler',
        'auth_kit.mfa.handlers.email.MFAEmailHandler',
        'myapp.handlers.SMSMFAHandler',
    ],
}

Production-Ready Features

DRF Auth Kit isn't just for prototypes:

Comprehensive test coverage (>95%) across multiple Python/Django versions
Internationalization support for 57 languages
Security best practices built-in
Performance optimized with efficient database queries
Rate limiting and audit logging (coming soon)

The Numbers Don't Lie

Here's how DRF Auth Kit compares to existing solutions:

Feature	dj-rest-auth	django-trench	DRF Auth Kit
Type Safety	❌	❌	✅ Full mypy/pyright
Auto OpenAPI	⚠️ Partial	❌	✅ Complete
Cookie Auth	✅	❌	✅ Enhanced
MFA Support	❌	✅	✅ Simplified
Social Auth	✅	❌	✅ Better integration
Custom Auth	⚠️ Complex	❌	✅ Easy
I18n Support	❌	❌	✅ 57 languages
Test Coverage	⚠️	⚠️	✅ >95%

Try It Today

pip install drf-auth-kit[all]

Check out the complete documentation for detailed guides, examples, and API reference.

What's Next?

The roadmap includes exciting features:

WebAuthn support for passwordless authentication
Hardware security keys (YubiKey, FIDO2)
Rate limiting and audit logging
Advanced security features

Join the Community

DRF Auth Kit is open source and built by developers, for developers:

GitHub: github.com/forthecraft/drf-auth-kit
Documentation: drf-auth-kit.readthedocs.io
PyPI: pypi.org/project/drf-auth-kit

Final Thoughts

Building authentication shouldn't be a painful experience. With DRF Auth Kit, you get a modern, type-safe solution that grows with your project – from simple JWT authentication to complex multi-factor flows.

The combination of type safety, automatic documentation, and developer-friendly APIs makes it perfect for both new projects and existing ones looking to modernize their authentication.

What are you waiting for? Give it a try in your next project and let me know what you think! 🚀

Chanx: The Missing Toolkit for Django Channels - Production-Ready WebSockets Made Simple

Huy Nguyen — Wed, 11 Jun 2025 08:13:18 +0000

Building WebSocket applications with Django Channels just got a whole lot easier

The Problem with Django Channels

Don't get me wrong - Django Channels is fantastic for adding WebSocket support to Django applications. But after building several real-time apps, I kept running into the same challenges:

Setting up authentication for WebSocket connections
Validating message structures and preventing runtime errors
Testing multi-user WebSocket interactions
Managing group messaging patterns
Debugging WebSocket connections during development

I found myself writing the same boilerplate code over and over. So I built Chanx to solve these problems once and for all.

What is Chanx?

Chanx is a comprehensive toolkit that extends Django Channels with production-ready features. Think of it as what Django REST Framework is to Django views - but for WebSocket consumers.

Key Features That'll Save You Hours

🔐 DRF-Style Authentication

Use your existing authentication classes with WebSockets:

from chanx.generic.websocket import AsyncJsonWebsocketConsumer
from rest_framework.authentication import SessionAuthentication
from rest_framework.permissions import IsAuthenticated

class ChatConsumer(AsyncJsonWebsocketConsumer[ChatMessage]):
    authentication_classes = [SessionAuthentication]
    permission_classes = [IsAuthenticated]

    async def receive_message(self, message: ChatMessage, **kwargs):
        # Only authenticated users reach here
        # self.user is automatically populated
        pass

📝 Type-Safe Messaging with Pydantic

No more runtime errors from malformed messages:

from typing import Literal
from chanx.messages.base import BaseMessage

class ChatMessage(BaseMessage):
    action: Literal["chat"] = "chat"
    payload: str

class NotificationMessage(BaseMessage):
    action: Literal["notify"] = "notify"
    payload: dict

# Union type for type safety
AllMessages = ChatMessage | NotificationMessage

class MyConsumer(AsyncJsonWebsocketConsumer[AllMessages]):
    async def receive_message(self, message: AllMessages, **kwargs):
        # Pattern matching with full type safety
        match message:
            case ChatMessage(payload=text):
                await self.handle_chat(text)
            case NotificationMessage(payload=data):
                await self.handle_notification(data)

🎮 WebSocket Playground

Like Swagger, but for WebSockets! Auto-discovers your endpoints and lets you test them interactively:

# settings.py
INSTALLED_APPS = [
    # ...
    'chanx.playground',
]

# urls.py
urlpatterns = [
    path('playground/', include('chanx.playground.urls')),
]

Visit /playground/websocket/ and test your WebSocket endpoints without writing JavaScript!

👥 Simplified Group Messaging

Pub/sub messaging made easy:

class ChatConsumer(AsyncJsonWebsocketConsumer[ChatMessage]):
    async def build_groups(self) -> list[str]:
        room_id = self.scope["url_route"]["kwargs"]["room_id"]
        return [f"chat_room_{room_id}"]

    async def receive_message(self, message: ChatMessage, **kwargs):
        # Broadcast to all users in the room
        await self.send_group_message(message)

Messages automatically include metadata:

{
  "action": "chat",
  "payload": "Hello everyone!",
  "is_mine": false,
  "is_current": false
}

🧪 Testing That Actually Works

Multi-user WebSocket testing without the headaches:

from chanx.testing import WebsocketTestCase

class ChatTest(WebsocketTestCase):
    ws_path = "/ws/chat/room1/"

    async def test_multi_user_chat(self):
        # First user (automatic setup)
        await self.auth_communicator.connect()
        await self.auth_communicator.assert_authenticated_status_ok()

        # Second user with different credentials
        user2_comm = self.create_communicator(headers=user2_headers)
        await user2_comm.connect()

        # Test group messaging
        await self.auth_communicator.send_message(ChatMessage(payload="Hello!"))
        responses = await user2_comm.receive_all_json(wait_group=True)

        assert responses[0]["payload"] == "Hello!"
        assert responses[0]["is_mine"] == False

Real-World Example: Building a Chat App

Here's how simple it is to build a production-ready chat application:

1. Define Your Messages

from typing import Literal
from chanx.messages.base import BaseMessage, BaseGroupMessage

class ChatMessage(BaseMessage):
    action: Literal["chat"] = "chat"
    payload: str

class UserJoinedMessage(BaseGroupMessage):
    action: Literal["user_joined"] = "user_joined"
    payload: dict

ChatMessages = ChatMessage | PingMessage  # Include ping for health checks

2. Create Your Consumer

from chanx.generic.websocket import AsyncJsonWebsocketConsumer
from chanx.messages.incoming import PingMessage
from chanx.messages.outgoing import PongMessage

class ChatConsumer(AsyncJsonWebsocketConsumer[ChatMessages]):
    authentication_classes = [SessionAuthentication]
    permission_classes = [IsAuthenticated]

    async def build_groups(self) -> list[str]:
        room_id = self.scope["url_route"]["kwargs"]["room_id"]
        return [f"chat_room_{room_id}"]

    async def post_authentication(self):
        """Called after successful authentication"""
        await self.send_group_message(
            UserJoinedMessage(payload={"username": self.user.username})
        )

    async def receive_message(self, message: ChatMessages, **kwargs):
        match message:
            case PingMessage():
                await self.send_message(PongMessage())
            case ChatMessage(payload=text):
                # Save to database and broadcast
                await self.save_message(text)
                await self.send_group_message(message)

3. Set Up Routing

# chat/routing.py
from chanx.routing import path
from channels.routing import URLRouter

router = URLRouter([
    path("<int:room_id>/", ChatConsumer.as_asgi()),
])

# project/routing.py
from chanx.routing import include, path
from channels.routing import URLRouter

router = URLRouter([
    path("ws/chat/", include("chat.routing")),
])

4. Test It

class ChatRoomTest(WebsocketTestCase):
    ws_path = "/ws/chat/123/"

    async def test_user_can_join_and_chat(self):
        await self.auth_communicator.connect()
        await self.auth_communicator.assert_authenticated_status_ok()

        # Should receive user_joined message
        messages = await self.auth_communicator.receive_all_json()
        assert any(msg["action"] == "user_joined" for msg in messages)

        # Send a chat message
        await self.auth_communicator.send_message(ChatMessage(payload="Hello!"))
        responses = await self.auth_communicator.receive_all_json(wait_group=True)

        assert responses[0]["action"] == "chat"
        assert responses[0]["payload"] == "Hello!"

Why Developers Love Chanx

Complete Type Safety

# Generic type parameters for compile-time checking
class MyConsumer(AsyncJsonWebsocketConsumer[
    IncomingMessages,  # Required: Your message types
    ChannelEvents,     # Optional: Channel layer events
    Room              # Optional: Model for object permissions
]):
    queryset = Room.objects.all()  # For object-level permissions

Enhanced Routing

Django-style routing specifically designed for WebSockets:

from chanx.routing import path, re_path, include

# Use familiar Django patterns
router = URLRouter([
    path("room/<str:room_name>/", ChatConsumer.as_asgi()),
    re_path(r"^admin/(?P<id>\d+)/$", AdminConsumer.as_asgi()),
    path("api/", include("api.routing")),
])

Channel Events

Type-safe communication between consumers:

# Send events from views, tasks, or other consumers
ChatConsumer.send_channel_event(
    "chat_room_123",
    NotificationEvent(payload={"message": "System update"})
)

# Handle in consumer
async def receive_event(self, event: NotificationEvent):
    match event:
        case NotificationEvent():
            await self.send_message(SystemMessage(payload=event.payload))

Getting Started

pip install chanx

Essential links:

📚 Documentation - Comprehensive guides and examples
💻 GitHub - Source code and issues
🚀 Complete Example - Production-ready chat app

Quick setup:

# settings.py
INSTALLED_APPS = [
    'channels',
    'rest_framework', 
    'chanx.playground',  # For WebSocket testing UI
]

CHANX = {
    'SEND_COMPLETION': True,  # Important for testing
    'SEND_AUTHENTICATION_MESSAGE': True,
}

Perfect for AI Applications

Chanx is especially powerful for AI chatbots and streaming applications:

async def handle_ai_chat(self, user_message: str):
    """Stream AI response token by token"""
    async for token in self.get_ai_stream(user_message):
        await self.send_message(AIStreamingMessage(payload=token))

Community and Feedback

Chanx is actively maintained and used in production applications. The community is growing, and I'm always looking for feedback:

What challenges are you facing with Django Channels?
Which features would be most valuable to you?
How can we make WebSocket development even easier?

Conclusion

Django Channels is powerful, but building production WebSocket applications shouldn't require reinventing the wheel every time. Chanx provides the missing pieces:

✅ Authentication - DRF integration out of the box

✅ Type Safety - Catch errors at development time

✅ Testing - Multi-user scenarios made simple

✅ Developer Tools - WebSocket playground for debugging

✅ Group Messaging - Pub/sub patterns simplified

✅ Production Ready - Battle-tested in real applications

Whether you're building a chat application, real-time collaboration tool, or AI-powered interface, Chanx helps you ship faster with fewer bugs.

Try it out and let me know what you think! 🚀

What's your experience with Django Channels? Have you run into similar challenges? Share your thoughts in the comments!

🚀 Streamline Your Python & Django Development with Production-Ready Cookiecutter Templates

Huy Nguyen — Mon, 09 Jun 2025 15:18:53 +0000

TL;DR: I've created a comprehensive cookiecutter template collection that generates production-ready Python apps, PyPI packages, Django REST APIs, and DRF packages with modern tooling, best practices, and zero configuration hassle.

The Problem: Starting Projects Shouldn't Be This Hard

How many times have you started a new Python project and spent hours setting up the same boilerplate code? Configuring pyproject.toml, setting up pre-commit hooks, writing GitHub Actions, configuring Docker, setting up Django with all the modern best practices...

The list goes on. And then you realize you forgot to configure type checking, or your test coverage setup is broken, or you're missing that one crucial piece of tooling that makes development smooth.

I've been there. We've all been there.

The Solution: One Template to Rule Them All (Actually, Four)

That's why I created cookiecutter-python — a curated collection of four specialized cookiecutter templates that cover the most common Python development scenarios:

🐍 Python App - For General-Purpose Applications

Perfect for CLI tools, data processing scripts, or any standalone Python application.

📦 Python Package - For PyPI Publishing

Ready-to-publish package structure with documentation, CI/CD, and multiple license options.

🌐 Django REST App - For Full-Stack Web APIs

Complete Django REST Framework setup with authentication, database, optional Celery/WebSockets, and cloud deployment support.

🧩 DRF Package - For Reusable Django Components

Lightweight structure for building and distributing Django REST Framework extensions.

What Makes These Templates Special?

✨ Modern Tooling Out of the Box

Each template is carefully configured with specialized tooling for its use case:

🔧 Universal Tools (All Templates):

UV for lightning-fast dependency management with intelligent dependency groups
Ruff for blazing-fast linting and formatting
Black for consistent code formatting
Dual type checking with both mypy and pyright for maximum type safety
Pre-commit hooks for automated quality checks
pytest with parallel execution (pytest-xdist) and coverage reporting
GitHub Actions CI/CD pipelines

📦 Package Templates (PyPackage & DRF Package) Add:

Commitizen for conventional commits and automated versioning
Interrogate for docstring coverage monitoring with badge generation
Sphinx ecosystem for professional documentation (myst-parser, ReadTheDocs theme)
Automated publishing workflows to PyPI

🌐 Django Templates (DRF & DRF Package) Add:

Factory Boy for realistic test data generation
Faker for generating fake data
django-stubs + djangorestframework-stubs for comprehensive Django type checking
django-debug-toolbar for development debugging
IPython for enhanced Django shell experience
Freezegun for time-based testing

🏗️ Production-Ready Architecture

The Django templates include:

PostgreSQL integration with connection pooling
Redis support for Celery and WebSockets
JWT authentication with django-rest-auth
API documentation with Swagger/ReDoc
Docker containerization
Cloud storage support (AWS S3, GCP, Azure)
Email providers integration (SendGrid, Mailgun, etc.)

🎯 Zero Configuration Philosophy

Each generated project is immediately runnable. No additional setup required. Just generate, install dependencies, and start developing.

Quick Start Guide

Prerequisites

First, you'll need to install cookiecutter. I recommend using Homebrew (macOS) or pipx for a clean installation:

macOS (Recommended):

brew install cookiecutter

Linux/Windows with pipx:

pipx install cookiecutter

Alternative (with pip):

python3 -m pip install --user cookiecutter

Why not just pip install cookiecutter? Since we'll be using UV for Python dependency management in the generated projects, keeping cookiecutter isolated prevents potential conflicts and keeps your global Python environment clean.

Generate Your Project

cookiecutter gh:huynguyengl99/cookiecutter-python

You'll be prompted to select your template type:

Select a template
1 - Python app (A cookiecutter template for a normal python app)
2 - Python package (A cookiecutter template for a python package)  
3 - DRF (A cookiecutter template for a django rest framework app)
4 - DRF package (A cookiecutter template for a drf package)
Choose from [1/2/3/4] (1):

Start Developing Immediately

For a Django REST App:

cd your-project
uv sync                    # Install dependencies
docker compose up -d       # Start PostgreSQL/Redis
scripts/manage.sh migrate  # Run migrations
scripts/manage.sh runserver # Start development server

Your API documentation is immediately available at:

Swagger UI: http://localhost:8000/api/schema/swg/
ReDoc: http://localhost:8000/api/schema/redoc/

Deep Dive: What Each Template Provides

🐍 Python App Template

Perfect for: CLI tools, data processing, automation scripts

Includes:

Modern pyproject.toml configuration
Docker setup for easy deployment
Comprehensive testing framework
Code quality tools (Ruff, Black, mypy, pyright)
GitHub Actions for CI/CD

Generated Structure:

my-app/
├── pyproject.toml
├── docker-compose.yml
├── Dockerfile
├── scripts/
│   └── lint.sh
└── my_app/
    └── __init__.py

📦 Python Package Template

Perfect for: Open-source libraries, reusable components

Includes:

PyPI-ready project structure
Sphinx documentation with ReadTheDocs integration
Multiple license options (MIT, BSD, Apache, GPL)
Automated versioning with Commitizen
Publishing workflow to PyPI

Generated Structure:

my-package/
├── pyproject.toml
├── LICENSE
├── docs/
├── tests/
├── .github/workflows/
└── my_package/
    └── __init__.py

🌐 Django REST App Template

Perfect for: Web APIs, SaaS backends, microservices

Configuration Options:

Database: PostgreSQL with multiple version options
Authentication: JWT with optional Google OAuth
Background Tasks: Optional Celery integration
Real-time: Optional WebSocket support with Channels
Cloud Storage: AWS S3, Google Cloud, Azure support
Email: 10+ provider integrations (SendGrid, Mailgun, etc.)
API Style: Optional camelCase conversion

Generated Structure:

my-api/
├── pyproject.toml
├── docker-compose.yml
├── Dockerfile
├── scripts/
│   └── manage.sh
└── my_api/
    ├── config/
    │   ├── settings/
    │   ├── urls.py
    │   └── wsgi.py
    ├── accounts/        # Custom user model
    ├── core/           # Utilities
    └── status/         # Health check

Key Features:

Custom User Model with email authentication
JWT Authentication with refresh token rotation
API Versioning ready structure
Comprehensive Testing with factories and fixtures
Admin Interface customization
Structured Logging with structured logs
Health Checks and monitoring endpoints

🧩 DRF Package Template

Perfect for: Django REST Framework extensions, reusable API components

Includes:

Sandbox Django project for testing
Documentation with Django integration
Package publishing to PyPI
Testing across multiple Django/DRF versions

Unique Feature: The sandbox directory serves dual purposes:

Testing Environment: Run tests against your package
Development Playground: Manual testing with a real Django app

Advanced Features That Set These Apart

🔧 Intelligent Dependency Management with UV

Each template uses UV's dependency groups for optimal development experience:

[dependency-groups]
dev = ["commitizen", "factory-boy", "pytest-django"]  # Core development
lint = ["black", "ruff", "mypy", "pyright"]           # Code quality  
test = ["pytest-cov", "pytest-xdist", "coverage"]    # Testing tools
docs = ["sphinx", "myst-parser", "interrogate"]      # Documentation

Smart defaults with uv sync:

Application templates: Auto-installs dev + lint groups
Package templates: Auto-installs all groups for comprehensive development
Selective installation: uv sync --group test for specific workflows

🛡️ Type Safety First

Every template includes comprehensive type checking with dual tools for maximum coverage:

mypy with specialized Django and DRF plugins for framework-specific type checking
pyright for advanced static analysis and fast feedback
django-stubs for comprehensive Django typing (Django templates)

This dual approach catches different categories of type issues and provides the most robust type safety available in the Python ecosystem.

📊 Quality Metrics & Automation

Package templates include sophisticated quality monitoring:

# Docstring coverage with automatic badge generation
interrogate --generate-badge docs/_static/ my_package

# Conventional commits with automated versioning
cz commit  # Interactive commit creation
cz bump    # Automatic version bumping and changelog

# Parallel testing for faster feedback
pytest -n5  # Runs tests across 5 parallel processes

Quality gates enforce standards:

80% docstring coverage requirement
100% type hint coverage with mypy strict mode
Zero linting violations with Ruff and Black
Conventional commit format for automated changelog generation

⚡ Modern Python Practices

PEP 621 compliant pyproject.toml
UV for dependency management (10x faster than pip)
Ruff for linting (100x faster than flake8)
Python 3.10+ with modern syntax support

🚀 Production Deployment Ready

Django templates include:

Multi-stage Docker builds for optimized images
Gunicorn configuration for production WSGI
Environment-based settings (dev/test/production)
Static file handling with WhiteNoise
Database connection pooling

Real-World Usage Examples

Scenario 1: Building a SaaS API

cookiecutter gh:huynguyengl99/cookiecutter-python
# Select: 3 - DRF
# Configure: PostgreSQL, JWT auth, Celery, SendGrid emails, AWS S3

cd my-saas-api
uv sync
docker compose up -d
scripts/manage.sh migrate
scripts/manage.sh createsuperuser
scripts/manage.sh runserver

Result: Full-featured API with user authentication, background tasks, email integration, and cloud storage. Ready for production deployment.

Scenario 2: Publishing a Python Library

cookiecutter gh:huynguyengl99/cookiecutter-python
# Select: 2 - Python package
# Configure: MIT license, GitHub username, PyPI publishing

cd my-library
uv sync
pytest  # Tests pass immediately
scripts/lint.sh  # Code quality checks pass
cz commit  # Conventional commits

Result: Professional package structure ready for PyPI publishing with documentation, CI/CD, and automated releases.

Scenario 3: Building a DRF Extension

cookiecutter gh:huynguyengl99/cookiecutter-python
# Select: 4 - DRF package

cd my-drf-extension
uv sync
docker compose up -d  # Test database
pytest sandbox  # Test against real Django app
python sandbox/manage.py runserver  # Manual testing

Result: Professional DRF package with testing sandbox and publishing workflow.

Best Practices Baked In

🧪 Testing Excellence

Each template includes sophisticated testing infrastructure:

🏃‍♂️ Performance-Optimized Testing:

Parallel execution with pytest-xdist (5 parallel processes by default)
Smart test discovery with proper Django integration
Coverage reporting with branch coverage and XML output for CI integration

🏭 Test Data Generation (Django Templates):

# Factory Boy integration for realistic test data
from accounts.factories import UserFactory

def test_user_creation():
    user = UserFactory.create(email="test@example.com")
    assert user.is_active

⏰ Time-Based Testing:

# Freezegun for testing time-dependent code
from freezegun import freeze_time

@freeze_time("2023-01-01")
def test_timestamp_behavior():
    # Test behavior at specific time
    pass

🔧 Advanced Testing Features:

pytest-mock for sophisticated mocking
pytest-django for Django-specific fixtures and database handling
Factory Boy with custom factory metaclass for type-safe model factories
Coverage exclusions for migrations, settings, and other non-testable code

📝 Documentation Standards

Package templates include professional documentation tooling:

📖 Sphinx Documentation:

Automatic API documentation generation
ReadTheDocs integration with automated builds
MyST parser for Markdown support in reStructuredText projects
Cross-references and intersphinx linking

📊 Documentation Quality Monitoring:

Interrogate for docstring coverage monitoring
Automatic badge generation showing documentation coverage percentage
80% coverage requirement enforced in CI/CD
SVG badges integrated into documentation and README

# Check docstring coverage
interrogate -vv my_package

# Generate coverage badge
interrogate --generate-badge docs/_static/

📋 API Documentation (Django Templates):

Swagger UI and ReDoc auto-generation from code
OpenAPI 3.0 specification export
Interactive API testing directly in documentation

🔄 CI/CD Pipeline

GitHub Actions workflows include:

🧪 Comprehensive Testing:

Multi-version testing across Python 3.10-3.13
Parallel test execution with pytest-xdist for faster feedback
Coverage reporting with Codecov integration and XML output
Matrix testing across multiple dependency versions (Django templates)

✅ Code Quality Gates:

Linting pipeline with Ruff for import sorting and style checks
Dual type checking with both mypy and pyright
Code formatting verification with Black
TOML file validation and sorting with toml-sort

📦 Automated Publishing (Package Templates):

Semantic versioning with Commitizen integration
Automated PyPI publishing on tagged releases
GitHub releases with automated changelog generation
Build artifact caching for faster CI runs

🔒 Security & Quality:

Dependency vulnerability scanning
Pre-commit hook validation in CI
Build reproducibility with UV lock files

🎨 Code Quality

Pre-commit hooks automatically run:

Ruff for linting and import sorting
Black for code formatting
toml-sort for TOML file organization
Type checking with mypy/pyright

Common Questions

Q: Why four separate templates instead of one configurable template?

A: Each template is optimized for its specific use case. A Python package has different needs than a Django API. Separate templates mean:

Cleaner code without excessive conditionals
Faster generation with only relevant files
Better maintenance with focused concerns
Easier customization for specific needs

Q: Why UV instead of pip/poetry?

A: UV is incredibly fast (10-100x faster than pip) and handles both Python version management and dependency resolution. It's the future of Python package management.

Q: Can I customize the generated templates?

A: Absolutely! The templates are designed to be starting points. All configuration is in standard files (pyproject.toml, settings.py, etc.) that you can modify as needed.

Q: What about database migrations in Django templates?

A: The Django templates include a custom user model and initial migrations. After generation, run scripts/manage.sh migrate and you're ready to go.

Future Roadmap

I'm continuously improving these templates based on community feedback:

FastAPI template for modern async APIs
Next.js + Django full-stack template
Kubernetes deployment configurations
More cloud provider integrations
Additional authentication providers

Getting Started Today

Ready to streamline your Python development? Here's how to get started:

Install cookiecutter: pip install cookiecutter
Generate your project: cookiecutter gh:huynguyengl99/cookiecutter-python
Choose your template and configure options
Start developing immediately!

Useful Links

📂 Repository: github.com/huynguyengl99/cookiecutter-python
📖 Documentation: Full README with detailed setup instructions
🐛 Issues: Report bugs or request features
💡 Discussions: Share your use cases and get help

Conclusion

These cookiecutter templates represent hundreds of hours of research, testing, and refinement to create the ideal starting point for Python projects. Whether you're building a simple CLI tool or a complex Django API, you can focus on your core business logic instead of wrestling with configuration.

The templates embody modern Python best practices:

Type safety with comprehensive type checking
Code quality with automated formatting and linting
Testing excellence with comprehensive test setups
Production readiness with Docker and deployment configs
Developer experience with helpful scripts and documentation

Give them a try for your next project. I'm confident they'll save you hours of setup time and help you ship better code faster.

What are you waiting for? Let's build something amazing together! 🚀

Have you used these templates? Found them helpful? Have suggestions for improvements? I'd love to hear about your experience! Drop a comment below or open an issue on GitHub.

Easy Multilingual Page (Scales to Over 50 Languages)

Huy Nguyen — Fri, 21 Jun 2024 14:17:13 +0000

Hi all,

So, a few months back, I kicked off a project to create a multilingual website. Let me tell you, managing content in multiple languages is a real headache. It’s doable if you’re only dealing with 3 or 4 languages, but once you hit 30+, it’s a whole different ball game trying to keep everything updated and consistent.

To make life easier, I decided to bring in a CMS for my Astro-based site. I dug into frameworks like Wagtail and Strapi since I’m familiar with Python and Node.js, but man, those were tough nuts to crack. Plus, I wanted a centralized place for all my content instead of having to jump between different pages for each language. This way, I can easily compare content across languages without getting lost.

And here's the kicker: ChatGPT is shaping up to be a solid translator, but no one’s integrated it into any frameworks yet. So, with my Django and Astrowind know-how (Astrowind is this cool UI built on Astro and Tailwind, and it’s open source), I whipped up a small Django library/framework to act as a headless CMS. I also tweaked the Astrowind source to pull in content from the CMS with multilingual support.

Check out this demo if you wanna see it in action:
https://django-astrowind.netlify.app/en

Not much has changed from the original Astrowind (https://astrowind.vercel.app/), except now you can switch languages on the fly, and the content is managed through a CMS with hashed caching.

If you’re interested in using it, I’ve put together a tutorial to help you set it up on your own machine:
https://django-headless-cms.readthedocs.io/en/latest/quick-start.html

Hope you dig it. And I hope my little project can be of some help to you guys.

Introducing Django Headless CMS: A Powerful and Flexible CMS Solution

Huy Nguyen — Thu, 20 Jun 2024 06:39:52 +0000

Introduction

Are you looking for an effortless way to create and manage a headless CMS? Look no further! I'm excited to introduce Django Headless CMS, a robust, open-source content management system designed to simplify the process of managing and delivering content across multiple platforms. Built on Django, this package leverages the sturdy foundation of the Django framework while providing a headless approach, making it ideal for modern web applications.

Why Choose Django Headless CMS?

Why choose Django-headless-cms over alternatives like Wagtail, Django-CMS, Strapi, or Contentful?

Headless CMS with minimal configuration: Unlike Wagtail and Django-CMS, which are primarily headed CMS solutions.
Responsive UI: Preferred over Strapi for its user interface.
Python & Django-based: Built on a robust framework with numerous extensions.
Open Source: Unlike Contentful and other paid services, it allows you to self-host your CMS.
Integration: Easily integrates with many existing Python and Django libraries.
Centralized multi-language support: Reduces redundancy and allows different content across multiple languages.

Key Features

Django Headless CMS comes packed with features to enhance your content management experience:

Schema Migrations: Manage content schema as database migrations, making it easier to sync from development to production environments.
Versioning Content: Revert to any previously saved version.
Publish/Draft Content: Manage published and draft content.
Markdown Editor Support: Enhanced content editing experience, useful for Posts/Articles.
Multi-language Support: Even for Markdown fields.
Auto Translate/Force Re-translate: Use ChatGPT or build your own translation interface.
Recursive Actions: Apply actions like Publish, Translate, and Force Re-translate to referenced objects.
Optimized Queries: Auto prefetch and select related queries for optimization.
Filter Published Objects: Easily filter to show only published content.
Auto Admin: Simplify admin page setup with features like:
- Sortable inline Many-to-Many (M2M) relationships.
- Sortable generic inlines.
- Display publish status of child objects.
Auto Serializer: Simplify serializer creation, including nested relations. Override specific serializers as needed.
Rapid API Development: Build APIs (Views/Viewsets) quickly and easily with auto serializers and optimized queries.
Easy Data Import/Export: Use the admin interface or management commands.
Auto-generated API Documentation & Playground: Automatically generate API documentation and an interactive playground.

Quick Start

To get started with Django Headless CMS, follow the tutorial from the docs:

Quick Start Guide

Demo

Want to see a quick demo? By the end of this tutorial, you will have a CMS that can be used to build a multi-lingual page that looks like this: Django Astrowind Demo

Some features:

Publish/Unpublish/Recursively publish:

Multi-language & markdown editor:

Drag-to-sort related items:
Auto-translate to multiple languages:

And other cool features. Read more in the docs.

Conclusion

After experimenting with various CMS frameworks, I built Django Headless CMS and Django Astrowind to meet my specific needs and address issues faced by others in the community.

For more information, explore the Django Headless CMS documentation and the Django Astrowind repository.