Bài 03.2: Reusable Apps

Reusable Apps Concept

Tại Sao Cần Reusable Apps?

Reusable apps là apps được thiết kế để dùng lại trong nhiều projects khác nhau. Thay vì viết lại code, bạn có thể package và share apps.

Benefits:

# Scenario: Bạn đã viết authentication system tốt # ❌ WITHOUT reusable appproject1/  └── authentication/  # Copy-paste codeproject2/  └── authentication/  # Copy-paste againproject3/  └── authentication/  # Copy-paste again# Problem: Bug fixes phải update 3 chỗ! # ✅ WITH reusable appmycompany-auth/      # Package once  └── setup.py # Install everywhere:pip install mycompany-auth # Use in all projects:INSTALLED_APPS = ['mycompany_auth']

Real-world Examples:

# Famous reusable Django apps: # 1. django-allauth - AuthenticationINSTALLED_APPS += ['allauth', 'allauth.account'] # 2. django-rest-framework - APIsINSTALLED_APPS += ['rest_framework'] # 3. django-debug-toolbar - DebuggingINSTALLED_APPS += ['debug_toolbar'] # 4. django-crispy-forms - Form renderingINSTALLED_APPS += ['crispy_forms'] # 5. django-celery-beat - Task schedulingINSTALLED_APPS += ['django_celery_beat']

Characteristics of Good Reusable Apps

1. Single Responsibility

# ✅ GOOD - Focused responsibilityblog/              # Only handles blog posts  ├── models.py    # Post, Category, Tag  ├── views.py     # Blog views  └── urls.py      # Blog URLs comments/          # Separate app for comments  ├── models.py    # Comment model  ├── views.py     # Comment views  └── forms.py     # Comment forms # ❌ BAD - Too many responsibilitiesmega_app/          # Does everything  ├── models.py    # Posts, Comments, Users, Products...  ├── views.py     # Too many views  └── ...

2. Minimal Dependencies

# ✅ GOOD - Minimal external dependencies# blog/requirements.txtDjango>=4.2Pillow>=10.0  # Only for image handling # ❌ BAD - Too many dependencies# blog/requirements.txtDjango>=4.2celery>=5.3redis>=5.0elasticsearch>=8.0tensorflow>=2.13  # Why???

3. Configurable

# ✅ GOOD - Settings configurable# blog/settings.pyfrom django.conf import settings BLOG_POSTS_PER_PAGE = getattr(settings, 'BLOG_POSTS_PER_PAGE', 10)BLOG_ALLOW_COMMENTS = getattr(settings, 'BLOG_ALLOW_COMMENTS', True)BLOG_MODERATE_COMMENTS = getattr(settings, 'BLOG_MODERATE_COMMENTS', False) # Users can override:# mysite/settings.pyBLOG_POSTS_PER_PAGE = 20BLOG_MODERATE_COMMENTS = True # ❌ BAD - Hard-coded values# blog/views.pyposts = Post.objects.all()[:10]  # Always 10, can't change!

4. Well-Documented

# ✅ GOOD - Clear documentation"""Django Blog App=============== Installation:    pip install django-myblog Configuration:    INSTALLED_APPS += ['myblog']        # Optional settings:    BLOG_POSTS_PER_PAGE = 10    BLOG_ALLOW_COMMENTS = True Usage:    # urls.py    urlpatterns = [        path('blog/', include('myblog.urls')),    ]""" # ❌ BAD - No documentation# Just code without explanation

5. Independent Database Models

# ✅ GOOD - Self-contained models# blog/models.pyfrom django.db import modelsfrom django.contrib.auth import get_user_model User = get_user_model()  # Use project's User model class Post(models.Model):    author = models.ForeignKey(User, on_delete=models.CASCADE)    # ... other fields # ❌ BAD - Hard-coded dependenciesfrom myproject.accounts.models import CustomUser  # Won't work in other projects! class Post(models.Model):    author = models.ForeignKey(CustomUser, on_delete=models.CASCADE)

Django's Reusable Apps Ecosystem

# Popular categories: # Authentication & Authorization- django-allauth           # Social authentication- django-guardian          # Per-object permissions- django-two-factor-auth   # 2FA support # Admin Interface- django-grappelli         # Admin UI improvements- django-admin-interface   # Responsive admin- django-jet               # Modern admin UI # APIs- djangorestframework      # REST APIs- django-graphene          # GraphQL APIs- django-tastypie          # RESTful APIs # Forms & UI- django-crispy-forms      # Form rendering- django-widget-tweaks     # Form customization- django-autocomplete-light # Autocomplete widgets # Content Management- django-cms               # Content management- wagtail                  # CMS framework- mezzanine                # CMS # E-commerce- django-oscar             # E-commerce framework- django-shop              # Shopping cart- saleor                   # GraphQL-first e-commerce # Development Tools- django-debug-toolbar     # Debugging- django-extensions        # Management commands- django-silk              # Profiling # Task Queue- celery                   # Async tasks- django-celery-beat       # Periodic tasks- django-rq                # Redis Queue # Search- django-haystack          # Search abstraction- django-elasticsearch-dsl # Elasticsearch- django-watson            # Full-text search

Designing Reusable Apps

Principle 1: Loose Coupling

Avoid hard dependencies:

# ❌ BAD - Tight coupling# comments/models.pyfrom blog.models import Post  # Direct import! class Comment(models.Model):    post = models.ForeignKey(Post, on_delete=models.CASCADE) # Problem: Comments app needs blog app to work! # ✅ GOOD - Generic foreign keyfrom django.contrib.contenttypes.fields import GenericForeignKeyfrom django.contrib.contenttypes.models import ContentType class Comment(models.Model):    """Generic comment - works with any model."""    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)    object_id = models.PositiveIntegerField()    content_object = GenericForeignKey('content_type', 'object_id')        text = models.TextField()    created = models.DateTimeField(auto_now_add=True) # Now works with any model:# - Blog posts# - Products# - News articles# - etc.

Use signals instead of direct calls:

# ❌ BAD - Direct function call# blog/views.pyfrom notifications.utils import send_notification  # Tight coupling! def create_post(request):    post = Post.objects.create(...)    send_notification(post.author, "Post created")  # Direct call # ✅ GOOD - Use signals# blog/views.pyfrom django.db.models.signals import post_savefrom django.dispatch import receiver class Post(models.Model):    # ... fields # blog/signals.py@receiver(post_save, sender=Post)def notify_post_created(sender, instance, created, **kwargs):    if created:        # Other apps can listen to this signal        pass # notifications/handlers.py (separate app)from blog.models import Post @receiver(post_save, sender=Post)def send_post_notification(sender, instance, created, **kwargs):    if created:        send_notification(instance.author, "Post created")

Principle 2: Configuration Over Code

# ✅ GOOD - App settings# blog/conf.pyfrom django.conf import settings class BlogSettings:    """Centralized blog settings."""        @property    def POSTS_PER_PAGE(self):        return getattr(settings, 'BLOG_POSTS_PER_PAGE', 10)        @property    def ALLOW_ANONYMOUS_COMMENTS(self):        return getattr(settings, 'BLOG_ALLOW_ANONYMOUS_COMMENTS', False)        @property    def MODERATE_COMMENTS(self):        return getattr(settings, 'BLOG_MODERATE_COMMENTS', True)        @property    def UPLOAD_PATH(self):        return getattr(settings, 'BLOG_UPLOAD_PATH', 'blog/uploads/')        @property    def IMAGE_SIZES(self):        default = {            'thumbnail': (150, 150),            'medium': (300, 300),            'large': (800, 800),        }        return getattr(settings, 'BLOG_IMAGE_SIZES', default) blog_settings = BlogSettings() # blog/views.pyfrom .conf import blog_settings class PostListView(ListView):    model = Post    paginate_by = blog_settings.POSTS_PER_PAGE  # Configurable! # Users can customize:# mysite/settings.pyBLOG_POSTS_PER_PAGE = 20BLOG_ALLOW_ANONYMOUS_COMMENTS = TrueBLOG_IMAGE_SIZES = {    'thumbnail': (200, 200),    'large': (1200, 1200),}

Principle 3: Template Flexibility

# Directory structure:blog/  └── templates/      └── blog/          ├── base.html           # Base template          ├── post_list.html      # List view          ├── post_detail.html    # Detail view          └── includes/           # Reusable components              ├── post_card.html              └── comment_form.html # blog/templates/blog/base.html{% extends "base.html" %}  {# User's base template #} {% block content %}  {% block blog_content %}{% endblock %}{% endblock %} # Allow template override:# Project can override by creating:# mysite/templates/blog/post_list.html# This will be used instead of app's template

Template naming conventions:

{# ✅ GOOD - Namespaced templates #}blog/templates/blog/post_list.htmlblog/templates/blog/post_detail.htmlblog/templates/blog/includes/post_card.html {# ❌ BAD - Generic names (conflicts!) #}blog/templates/list.htmlblog/templates/detail.html

Principle 4: URL Namespacing

# ✅ GOOD - Namespaced URLs# blog/urls.pyfrom django.urls import pathfrom . import views app_name = 'blog'  # Namespace! urlpatterns = [    path('', views.PostListView.as_view(), name='post_list'),    path('<slug:slug>/', views.PostDetailView.as_view(), name='post_detail'),    path('category/<slug:slug>/', views.CategoryView.as_view(), name='category'),] # Usage in templates:{% url 'blog:post_list' %}{% url 'blog:post_detail' slug=post.slug %} # Usage in views:from django.urls import reverseurl = reverse('blog:post_detail', kwargs={'slug': post.slug}) # ❌ BAD - No namespaceapp_name = None  # Missing!# URLs like 'post_list' can conflict with other apps

Principle 5: Extensibility

Make models extensible:

# ✅ GOOD - Abstract base model# blog/models.pyfrom django.db import models class AbstractPost(models.Model):    """Abstract post model - can be extended."""    title = models.CharField(max_length=200)    slug = models.SlugField(unique=True)    content = models.TextField()    created = models.DateTimeField(auto_now_add=True)        class Meta:        abstract = True  # This is important!        def __str__(self):        return self.title class Post(AbstractPost):    """Concrete implementation."""    author = models.ForeignKey('auth.User', on_delete=models.CASCADE)    published = models.BooleanField(default=False) # Users can extend:# mysite/myblog/models.pyfrom blog.models import AbstractPost class CustomPost(AbstractPost):    """Extended with custom fields."""    author = models.ForeignKey('accounts.CustomUser', on_delete=models.CASCADE)    views_count = models.IntegerField(default=0)    rating = models.DecimalField(max_digits=3, decimal_places=2)    # ... custom fields

Provide hooks:

# ✅ GOOD - Method hooks# blog/views.pyclass PostCreateView(CreateView):    model = Post    form_class = PostForm        def form_valid(self, form):        """Hook point for customization."""        response = super().form_valid(form)        self.post_save_hook(form.instance)  # Hook!        return response        def post_save_hook(self, post):        """Override this in subclass."""        pass # Users can customize:# mysite/views.pyfrom blog.views import PostCreateView class MyPostCreateView(PostCreateView):    def post_save_hook(self, post):        # Custom logic        send_notification(post.author)        log_activity(post)

Packaging Reusable Apps

Step 1: Prepare App Structure

# Create package structuredjango-myblog/                    # Package root├── README.md                     # Documentation├── LICENSE                       # License file├── setup.py                      # Package configuration├── MANIFEST.in                   # Include non-Python files├── requirements.txt              # Dependencies├── myblog/                       # App directory│   ├── __init__.py│   ├── models.py│   ├── views.py│   ├── urls.py│   ├── admin.py│   ├── forms.py│   ├── conf.py                  # Settings│   ├── templates/│   │   └── myblog/│   │       ├── post_list.html│   │       └── post_detail.html│   ├── static/│   │   └── myblog/│   │       ├── css/│   │       └── js/│   └── migrations/│       └── __init__.py├── tests/                        # Tests│   ├── __init__.py│   ├── test_models.py│   ├── test_views.py│   └── test_forms.py└── docs/                         # Documentation    ├── index.md    ├── installation.md    └── configuration.md

Step 2: Create setup.py

# django-myblog/setup.pyfrom setuptools import setup, find_packages with open("README.md", "r", encoding="utf-8") as fh:    long_description = fh.read() setup(    name="django-myblog",    version="1.0.0",    author="Your Name",    author_email="your.email@example.com",    description="A reusable Django blog application",    long_description=long_description,    long_description_content_type="text/markdown",    url="https://github.com/yourusername/django-myblog",        packages=find_packages(),    include_package_data=True,  # Include templates, static files        classifiers=[        "Development Status :: 4 - Beta",        "Framework :: Django",        "Framework :: Django :: 4.2",        "Intended Audience :: Developers",        "License :: OSI Approved :: MIT License",        "Operating System :: OS Independent",        "Programming Language :: Python",        "Programming Language :: Python :: 3",        "Programming Language :: Python :: 3.10",        "Programming Language :: Python :: 3.11",        "Topic :: Internet :: WWW/HTTP",        "Topic :: Internet :: WWW/HTTP :: Dynamic Content",    ],        python_requires=">=3.10",    install_requires=[        "Django>=4.2",        "Pillow>=10.0",    ],        extras_require={        "dev": [            "pytest>=7.4",            "pytest-django>=4.5",            "black>=23.0",            "flake8>=6.0",        ],    },        zip_safe=False,)

Step 3: Create MANIFEST.in

# django-myblog/MANIFEST.in# Include templatesrecursive-include myblog/templates * # Include static filesrecursive-include myblog/static * # Include documentationinclude README.mdinclude LICENSEinclude requirements.txt # Exclude compiled Python filesglobal-exclude *.pycglobal-exclude __pycache__

Step 4: Create README.md

# Django MyBlog A reusable Django blog application with modern features. ## Features - ✅ Blog posts with rich text editor- ✅ Categories and tags- ✅ Comments system- ✅ SEO-friendly URLs- ✅ RSS feeds- ✅ Sitemap support ## Installation ```bashpip install django-myblog

Quick Start

Add to INSTALLED_APPS:

INSTALLED_APPS = [    # ...    'myblog',]

Include URLs:

urlpatterns = [    # ...    path('blog/', include('myblog.urls')),]

Run migrations:

python manage.py migrate

Configuration

Optional settings:

# settings.pyBLOG_POSTS_PER_PAGE = 10BLOG_ALLOW_COMMENTS = TrueBLOG_MODERATE_COMMENTS = False

Documentation

Full documentation: https://django-myblog.readthedocs.io/

License

MIT License

 ### Step 5: Build and Distribute ```bash# Install build toolspip install build twine # Build packagepython -m build # Output:# dist/#   ├── django_myblog-1.0.0-py3-none-any.whl#   └── django-myblog-1.0.0.tar.gz # Test installation locallypip install dist/django_myblog-1.0.0-py3-none-any.whl # Upload to PyPIpython -m twine upload dist/* # Now others can install:pip install django-myblog

Step 6: Version Management

# myblog/__init__.py__version__ = '1.0.0' # Follow semantic versioning:# MAJOR.MINOR.PATCH # 1.0.0 → 1.0.1  (Bug fix)# 1.0.1 → 1.1.0  (New feature, backward compatible)# 1.1.0 → 2.0.0  (Breaking changes)

Best Practices

1. Testing

# tests/test_models.pyimport pytestfrom django.test import TestCasefrom myblog.models import Post @pytest.mark.django_dbclass TestPostModel(TestCase):    def setUp(self):        self.post = Post.objects.create(            title="Test Post",            slug="test-post",            content="Test content"        )        def test_post_creation(self):        assert self.post.title == "Test Post"        assert str(self.post) == "Test Post"        def test_get_absolute_url(self):        url = self.post.get_absolute_url()        assert url == "/blog/test-post/" # Run tests:pytest tests/

2. Documentation

# Good docstringsclass Post(models.Model):    """    Blog post model.        Attributes:        title: Post title (max 200 chars)        slug: URL-friendly version of title        content: Post content (HTML allowed)        created: Auto-set when post is created        updated: Auto-updated when post changes        Example:        >>> post = Post.objects.create(        ...     title="My Post",        ...     slug="my-post",        ...     content="Hello World"        ... )        >>> print(post.get_absolute_url())        /blog/my-post/    """    pass

3. Versioning Strategy

# Keep changelog# CHANGELOG.md ## [1.2.0] - 2025-10-28 ### Added- RSS feed support- Sitemap generation ### Changed- Improved admin interface- Better mobile responsiveness ### Fixed- Bug in comment pagination- Timezone handling ## [1.1.0] - 2025-09-15 ### Added- Category support- Tag filtering

4. Dependency Management

# requirements.txt - Minimal dependenciesDjango>=4.2,<5.0Pillow>=10.0,<11.0 # requirements-dev.txt - Development dependencies-r requirements.txtpytest>=7.4pytest-django>=4.5black>=23.0flake8>=6.0coverage>=7.3

Bài Tập

Bài 1: Analyze Reusable App

Task: Cài đặt và phân tích django-crispy-forms:

pip install django-crispy-forms

Questions:

App structure như thế nào?
Settings có thể configure gì?
Làm thế nào để extend/customize?

Bài 2: Create Simple Reusable App

Task: Tạo reusable "django-ratings" app:

Requirements:

Generic rating system (1-5 stars)
Works with any model (Generic Foreign Key)
Configurable settings
Include tests

Structure:

django-ratings/├── setup.py├── README.md├── ratings/│   ├── models.py      # Rating model│   ├── views.py       # Rating views│   └── templatetags/  # {% rating_stars %}└── tests/

Bài 3: Package Your App

Task: Package app từ Bài 2:

Create setup.py
Create MANIFEST.in
Build package: python -m build
Test installation locally

Bài 4: Documentation

Task: Write comprehensive README.md including:

Installation instructions
Quick start guide
Configuration options
Usage examples
API documentation

Tài Liệu Tham Khảo

Advanced tutorial: How to write reusable apps
Django Packages - Directory of reusable apps
Packaging Python Projects
Semantic Versioning

Previous: Bài 03: Django Apps | Next: Bài 04: URLs và Routing

#packaging

Django Apps - Reusable Apps