Primeros pasos
Instalar y crear el proyecto
Instala Django vía pip. Un proyecto guarda la configuración y las URLs; una app es un módulo reutilizable con modelos y vistas.
pip install django
django-admin startproject myproject
cd myproject
python manage.py startapp myappEjecutar el servidor de desarrollo
Inicia el servidor de desarrollo integrado con autorrecarga. Nunca lo uses en producción.
python manage.py runserver
# Default: http://127.0.0.1:8000
python manage.py runserver 8080
python manage.py runserver 0.0.0.0:8000Migraciones y superusuario
makemigrations genera los archivos de migración a partir de los cambios en los modelos. migrate los aplica a la base de datos. createsuperuser crea una cuenta de administrador.
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuserEstructura del proyecto
manage.py es la herramienta de línea de comandos. El paquete interno guarda la configuración del proyecto; el directorio de la app guarda el código a nivel de app.
myproject/
manage.py # CLI utility
myproject/
settings.py # Configuration
urls.py # Root URL dispatcher
wsgi.py # WSGI entry point
asgi.py # ASGI entry point
myapp/
models.py # Database models
views.py # View functions
admin.py # Admin registrationFundamentos de settings
INSTALLED_APPS lista las apps activas. En producción fija DEBUG=False y configura ALLOWED_HOSTS.
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'myapp',
]
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': BASE_DIR / 'db.sqlite3',
}
}
DEBUG = True
ALLOWED_HOSTS = []Campos del modelo
Definir un modelo
Cada clase de modelo se mapea a una tabla de la base de datos. Cada campo se mapea a una columna. __str__ define el nombre visible.
from django.db import models
class Article(models.Model):
title = models.CharField(max_length=200)
body = models.TextField()
published = models.DateTimeField(auto_now_add=True)
def __str__(self):
return self.titleTipos de campo comunes
CharField exige max_length. auto_now_add fija la fecha al crear; auto_now la actualiza en cada guardado. EmailField/URLField añaden validación.
name = models.CharField(max_length=100)
description = models.TextField(blank=True)
price = models.DecimalField(max_digits=10, decimal_places=2)
quantity = models.IntegerField(default=0)
is_active = models.BooleanField(default=True)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
email = models.EmailField(unique=True)
url = models.URLField(blank=True)Opciones de campo
null es a nivel de base de datos; blank es a nivel de validación. choices crea un desplegable en formularios y admin.
title = models.CharField(
max_length=200,
null=True, # DB allows NULL
blank=True, # Form allows empty
default='',
choices=[('draft', 'Draft'), ('pub', 'Published')],
help_text='Article title',
verbose_name='Article Title',
)Opciones de Meta
ordering fija el orden por defecto. db_table sobrescribe el nombre de tabla autogenerado. constraints aplica reglas a nivel de base de datos.
class Meta:
ordering = ['-created_at']
db_table = 'articles'
verbose_name_plural = 'Articles'
constraints = [
models.UniqueConstraint(
fields=['title', 'author'],
name='unique_title_per_author',
)
]Funciones y propiedades del modelo
Sobrescribe save() para lógica previa al guardado. @property añade atributos calculados. Llama siempre a super().save().
class Article(models.Model):
title = models.CharField(max_length=200)
views = models.IntegerField(default=0)
def __str__(self):
return self.title
def save(self, *args, **kwargs):
self.title = self.title.strip()
super().save(*args, **kwargs)
@property
def is_popular(self):
return self.views > 1000Relaciones del modelo
ForeignKey (muchos a uno)
ForeignKey crea una relación muchos a uno. related_name habilita las consultas inversas: author.books.all().
class Author(models.Model):
name = models.CharField(max_length=100)
class Book(models.Model):
author = models.ForeignKey(
Author,
on_delete=models.CASCADE,
related_name='books',
)
title = models.CharField(max_length=200)OneToOneField
OneToOneField crea un enlace uno a uno. Se accede vía user.profile o profile.user.
class Profile(models.Model):
user = models.OneToOneField(
User,
on_delete=models.CASCADE,
)
bio = models.TextField()ManyToManyField
ManyToManyField crea una tabla de unión automáticamente. Añadir/quitar: course.students.add(student).
class Student(models.Model):
name = models.CharField(max_length=100)
class Course(models.Model):
students = models.ManyToManyField(Student, blank=True)
title = models.CharField(max_length=200)Opciones de on_delete
CASCADE elimina los hijos cuando se elimina el padre. SET_NULL exige null=True. PROTECT lanza ProtectedError.
# CASCADE - delete related objects
author = models.ForeignKey(Author, on_delete=models.CASCADE)
# SET_NULL - set to NULL (field must be nullable)
author = models.ForeignKey(Author, on_delete=models.SET_NULL, null=True)
# PROTECT - prevent deletion
author = models.ForeignKey(Author, on_delete=models.PROTECT)
# SET_DEFAULT - set to default value
author = models.ForeignKey(Author, on_delete=models.SET_DEFAULT, default=1)Consulta de objetos relacionados
El acceso directo usa el nombre del campo. El acceso inverso usa related_name (o modelname_set por defecto).
# Forward query
book.author.name
# Reverse query (uses related_name)
author.books.all()
author.books.filter(title__contains='Django')
# Add/remove in M2M
course.students.add(student1, student2)
course.students.remove(student1)
course.students.clear()
# Check membership
student in course.students.all()QuerySet del ORM
Crear y guardar objetos
create() guarda inmediatamente. get_or_create devuelve (objeto, created_bool) — obtiene o crea de forma atómica.
# Method 1: Create and save separately
article = Article(title='Hello', body='World')
article.save()
# Method 2: Create in one step
article = Article.objects.create(title='Hello', body='World')
# Method 3: get_or_create
obj, created = Article.objects.get_or_create(
title='Hello', defaults={'body': 'World'}
)Recuperar un solo objeto
get() lanza DoesNotExist si no lo encuentra, MultipleObjectsReturned si hay varios. Usa first() para obtener uno con seguridad.
# Get by primary key
article = Article.objects.get(pk=1)
# Get by field
article = Article.objects.get(title='Hello')
# First/last (returns None if empty)
first = Article.objects.first()
last = Article.objects.last()
# Latest/earliest by field
latest = Article.objects.latest('created_at')Filtrar y excluir
filter() devuelve un QuerySet (perezoso). Encadenar aplica lógica AND. Los QuerySets solo se evalúan al iterarlos.
# Filter
Article.objects.filter(title__contains='Django')
Article.objects.filter(published=True)
# Exclude
Article.objects.exclude(views__lt=100)
# Chain filters (AND)
Article.objects.filter(author=1).exclude(draft=True)Field lookups
Los lookups usan sintaxis de doble guion bajo. Comunes: exact, contains, icontains, gt, gte, lt, lte, in, startswith, range.
Article.objects.filter(title__icontains='django') # case-insensitive
Article.objects.filter(views__gte=100) # >=
Article.objects.filter(views__in=[100, 200, 300]) # IN
Article.objects.filter(created_at__year=2024) # date lookup
Article.objects.filter(title__startswith='Hello') # LIKE 'Hello%'
Article.objects.filter(title__isnull=True) # IS NULLOrdenar y rebanar
El slicing aplica LIMIT a nivel de base de datos. La indexación negativa no está soportada en los QuerySets.
# Order by
Article.objects.order_by('-created_at') # descending
Article.objects.order_by('author', '-views')
# Slice (LIMIT/OFFSET)
Article.objects.all()[:5] # first 5
Article.objects.all()[5:10] # offset 5, limit 5
Article.objects.order_by('-views')[:3] # top 3
# Distinct
Article.objects.values('author').distinct()Actualizar y eliminar
update() es eficiente para cambios masivos. save(update_fields=[...]) evita condiciones de carrera. delete() hace cascada por defecto.
# Bulk update
Article.objects.filter(draft=True).update(draft=False)
# Single update (only save this field)
article.title = 'New Title'
article.save(update_fields=['title'])
# Delete
article.delete() # returns (count, {model: count})
Article.objects.filter(views=0).delete() # bulk deleteORM avanzado
Expresiones F
F() referencia el valor de una columna de la base de datos, habilitando actualizaciones atómicas sin cargar el objeto en Python.
from django.db.models import F
# Atomic increment (no race condition)
Article.objects.filter(pk=1).update(views=F('views') + 1)
# Compare two fields
Article.objects.filter(views__gt=F('min_views'))
# Arithmetic on fields
Article.objects.annotate(ratio=F('views') / F('likes'))Objetos Q para consultas complejas
Los objetos Q habilitan la lógica OR (|), AND (&) y NOT (~). Sin Q, múltiples llamadas filter() solo aplican AND.
from django.db.models import Q
# OR
Article.objects.filter(Q(title__contains='Django') | Q(title__contains='Flask'))
# AND with NOT
Article.objects.filter(Q(published=True) & ~Q(views=0))
# OR + AND
Article.objects.filter(
(Q(author=1) | Q(author=2)) & Q(published=True)
)Agregación
aggregate() devuelve un diccionario de totales. annotate() añade valores calculados por objeto.
from django.db.models import Count, Sum, Avg, Max, Min
# Single aggregate
total = Article.objects.aggregate(total=Count('id'))
avg_views = Article.objects.aggregate(Avg('views'))
# Per-group aggregate
Author.objects.annotate(
article_count=Count('article'),
total_views=Sum('article__views'),
)Annotate
annotate() añade campos calculados por objeto. Puedes hacer filter() y order_by() sobre campos anotados.
from django.db.models import Count, Avg
# Add computed field to each object
authors = Author.objects.annotate(article_count=Count('book'))
# Filter on annotated field
Author.objects.annotate(
avg_rating=Avg('book__rating')
).filter(avg_rating__gte=4.0)select_related y prefetch_related
select_related usa SQL JOIN (FK directa). prefetch_related usa una segunda consulta (inversa/M2M). Ambos previenen las consultas N+1.
# select_related (FK/OneToOne - single query with JOIN)
books = Book.objects.select_related('author').all()
# book.author.name -> no extra query
# prefetch_related (M2M/reverse - second query)
authors = Author.objects.prefetch_related('books').all()
# author.books.all() -> no extra query
# Deep prefetch
Author.objects.prefetch_related('books', 'books__reviews').all()Vistas basadas en funciones
Vista de función básica
Una vista recibe un HttpRequest y devuelve un HttpResponse. render() carga una plantilla y la rellena con el contexto.
from django.shortcuts import render
from django.http import HttpResponse
def hello(request):
return HttpResponse("Hello, World!")
def home(request):
context = {'title': 'Home', 'items': [1, 2, 3]}
return render(request, 'home.html', context)Objeto HttpRequest
request.GET/POST son QueryDict (usa .get() por seguridad). request.user es el usuario autenticado o AnonymousUser.
def my_view(request):
method = request.method # 'GET' or 'POST'
get_data = request.GET.get('q') # query param
post_data = request.POST.get('name')
path = request.path # '/articles/1/'
user = request.user # current user
files = request.FILES # uploaded files
meta = request.META.get('HTTP_HOST')Tipos de HttpResponse
JsonResponse serializa a JSON. redirect() acepta una ruta de URL o una URL con nombre y argumentos.
from django.http import HttpResponse, JsonResponse
from django.shortcuts import redirect
def json_view(request):
return JsonResponse({'status': 'ok', 'count': 42})
def redirect_view(request):
return redirect('/home/')
return redirect('article_detail', pk=1)
def csv_view(request):
response = HttpResponse(content_type='text/csv')
response['Content-Disposition'] = 'attachment; filename="data.csv"'
return responseDecoradores de vistas
login_required redirige a los usuarios no autenticados a LOGIN_URL. require_POST/GET restringen los verbos HTTP.
from django.contrib.auth.decorators import login_required
from django.views.decorators.http import require_POST, require_GET
@login_required
def dashboard(request):
return render(request, 'dashboard.html')
@require_POST
def submit(request):
pass # Only accepts POST
@require_GET
def search(request):
pass # Only accepts GETVista de subida de archivos
request.FILES contiene los archivos subidos. Usa .chunks() para archivos grandes y evitar cargar el archivo entero en memoria.
def upload_file(request):
if request.method == 'POST':
uploaded = request.FILES['file']
Document.objects.create(file=uploaded)
# Or save manually
with open(f'media/{uploaded.name}', 'wb') as f:
for chunk in uploaded.chunks():
f.write(chunk)
return redirect('success')
return render(request, 'upload.html')Vistas basadas en clases
TemplateView
TemplateView renderiza una plantilla estática. Sobrescribe get_context_data() para añadir contexto extra.
from django.views.generic import TemplateView
class AboutView(TemplateView):
template_name = 'about.html'
def get_context_data(self, **kwargs):
context = super().get_context_data(**kwargs)
context['title'] = 'About Us'
return contextListView
ListView pagina automáticamente y proporciona object_list y page_obj en el contexto. Sobrescribe get_queryset() para filtrar.
from django.views.generic import ListView
class ArticleListView(ListView):
model = Article
template_name = 'article_list.html'
context_object_name = 'articles'
paginate_by = 10
def get_queryset(self):
return Article.objects.filter(published=True)DetailView
DetailView obtiene un solo objeto por pk o slug desde la URL. Sobrescribe get_object() para una obtención personalizada.
from django.views.generic import DetailView
class ArticleDetailView(DetailView):
model = Article
template_name = 'article_detail.html'
context_object_name = 'article'
def get_object(self):
return Article.objects.get(
slug=self.kwargs['slug'], published=True
)CreateView y UpdateView
CreateView/UpdateView manejan la visualización del formulario, la validación y el guardado. Sobrescribe form_valid() para añadir lógica antes de guardar.
from django.views.generic.edit import CreateView, UpdateView
class ArticleCreateView(CreateView):
model = Article
fields = ['title', 'body', 'author']
template_name = 'article_form.html'
success_url = '/articles/'
class ArticleUpdateView(UpdateView):
model = Article
fields = ['title', 'body']
template_name = 'article_form.html'Mixins
Los mixins añaden comportamiento reutilizable a las vistas basadas en clases. Django proporciona LoginRequiredMixin, PermissionRequiredMixin.
from django.contrib.auth.mixins import LoginRequiredMixin
class OwnerRequiredMixin:
def get_queryset(self):
return super().get_queryset().filter(owner=self.request.user)
class ArticleListView(LoginRequiredMixin, OwnerRequiredMixin, ListView):
model = Article
paginate_by = 10Enrutado de URLs
Configuración de URLs básica
path() mapea un patrón de URL a una vista. name= habilita la búsqueda inversa de URL. <int:pk> captura un entero.
from django.urls import path
from myapp import views
urlpatterns = [
path('', views.home, name='home'),
path('about/', views.about, name='about'),
path('article/<int:pk>/', views.article_detail, name='article_detail'),
]Incluir las URLs de la app
include() delega la coincidencia de URLs al urls.py de una app. app_name crea un espacio de nombres para el reverso de URLs.
# myproject/urls.py
from django.urls import path, include
urlpatterns = [
path('admin/', admin.site.urls),
path('blog/', include('blog.urls')),
path('api/', include('api.urls')),
]
# blog/urls.py
app_name = 'blog'
urlpatterns = [
path('', views.list, name='list'),
path('<int:pk>/', views.detail, name='detail'),
]Convertidores de path
Los convertidores de path castea automáticamente los segmentos de la URL. Usa re_path para patrones regex complejos.
path('article/<int:pk>/') # integer
path('article/<slug:slug>/') # slug string
path('article/<str:title>/') # non-slash string
path('user/<uuid:user_id>/') # UUID
path('file/<path:filepath>/') # any string including /
# Regex path (re_path)
from django.urls import re_path
re_path(r'^article/(?P<year>[0-9]{4})/$', views.year_archive)URLs con nombre y reverse()
Las URLs con nombre permiten referenciar rutas por nombre en lugar de fijar rutas a mano. reverse() genera URLs en Python.
# urls.py
path('article/<int:pk>/', views.detail, name='article_detail')
# In views.py
from django.urls import reverse
url = reverse('article_detail', kwargs={'pk': 42})
# Returns '/article/42/'
# In templates
<a href="{% url 'article_detail' pk=article.pk %}">Read</a>Espacios de nombres de URLs
Los espacios de nombres previenen colisiones de nombres entre apps. El espacio de nombres debe coincidir con el app_name de la app.
# myproject/urls.py
path('blog/', include(('blog.urls', 'blog'), namespace='blog'))
# blog/urls.py
app_name = 'blog'
urlpatterns = [
path('<int:pk>/', views.detail, name='detail'),
]
# Usage
reverse('blog:detail', kwargs={'pk': 1})
# Template: {% url 'blog:detail' pk=1 %}Plantillas (DTL)
Herencia de plantillas
extends hereda de una plantilla base. Los blocks definen regiones sobrescribibles. Una plantilla solo puede extender a un padre.
{# base.html #}
<html>
<body>
{% block content %}{% endblock %}
{% block sidebar %}{% endblock %}
</body>
</html>
{# article.html #}
{% extends 'base.html' %}
{% block content %}
<h1>{{ article.title }}</h1>
{% endblock %}Variables y tags
{{ }} muestra variables. {% %} ejecuta tags. forloop.counter empieza en 1; forloop.counter0 en 0.
{# Variables #}
{{ article.title }}
{{ user.get_full_name }}
{{ article.tags.0 }}
{# Tags #}
{% if article.published %}
Published
{% elif article.draft %}
Draft
{% else %}
Archived
{% endif %}
{% for item in items %}
{{ forloop.counter }}: {{ item }}
{% empty %}
No items
{% endfor %}Filtros de plantilla
Los filtros modifican la salida de las variables usando la sintaxis de pipe |. Algunos aceptan argumentos tras dos puntos. Los filtros se pueden encadenar.
{{ name|lower }}
{{ text|truncatewords:30 }}
{{ date|date:"Y-m-d" }}
{{ value|default:"N/A" }}
{{ list|length }}
{{ text|striptags }}
{{ price|floatformat:2 }}
{{ value|add:5 }}Tags de plantilla integrados
csrf_token es obligatorio en cada formulario POST. include renderiza una subplantilla. load importa librerías de tags personalizadas.
{% url 'article_detail' pk=1 %}
{% csrf_token %}
{% load static %}
{% include 'header.html' %}
{% with total=items|length %}
{{ total }}
{% endwith %}
{% now "Y-m-d" %}
{% blocktrans %}Hello{% endblocktrans %}Tags de plantilla personalizados
Los tags viven en el directorio app/templatetags/. @register.simple_tag para funciones; @register.filter para modificadores de valores.
# templatetags/my_tags.py
from django import template
register = template.Library()
@register.simple_tag
def multiply(a, b):
return a * b
@register.filter
def cut(value, arg):
return value.replace(arg, '')
# In template:
{% load my_tags %}
{% multiply 3 4 %}
{{ "hello world"|cut:" " }}Formularios
Definir un formulario
forms.Form crea un formulario independiente. Cada campo genera automáticamente widgets HTML. Los tipos de campo aportan validación.
from django import forms
class ContactForm(forms.Form):
name = forms.CharField(max_length=100)
email = forms.EmailField()
message = forms.CharField(widget=forms.Textarea)
subject = forms.ChoiceField(
choices=[('general', 'General'), ('bug', 'Bug Report')],
)ModelForm
ModelForm construye automáticamente un formulario a partir de un modelo. fields/exclude controlan qué campos aparecen. widgets personaliza el HTML.
class ArticleForm(forms.ModelForm):
class Meta:
model = Article
fields = ['title', 'body', 'author']
# Or: fields = '__all__'
# Or: exclude = ['created_at']
widgets = {
'body': forms.Textarea(attrs={'rows': 10}),
}
labels = {'title': 'Article Title'}Validación de formularios
clean_<campo>() valida un solo campo. clean() valida el formulario entero. Lanza ValidationError en caso de fallo.
class SignupForm(forms.Form):
username = forms.CharField(max_length=50)
password = forms.CharField(widget=forms.PasswordInput)
def clean_username(self):
username = self.cleaned_data['username']
if User.objects.filter(username=username).exists():
raise forms.ValidationError("Username taken.")
return username
def clean(self):
cleaned = super().clean()
# Cross-field validation
return cleanedRenderizar el formulario en la plantilla
as_p/as_table/as_ul renderizan automáticamente los campos en su totalidad. Para un layout personalizado, renderiza los campos uno a uno. csrf_token es obligatorio para POST.
<form method="post">
{% csrf_token %}
{{ form.as_p }}
{{ form.as_table }}
{{ form.as_ul }}
{# Manual rendering #}
{{ form.title.label_tag }}
{{ form.title }}
{{ form.title.errors }}
<button type="submit">Submit</button>
</form>Procesar el formulario en la vista
Pasa request.POST para enlazar el formulario. is_valid() ejecuta la validación. save(commit=False) devuelve un objeto sin guardar.
def article_create(request):
if request.method == 'POST':
form = ArticleForm(request.POST)
if form.is_valid():
article = form.save(commit=False)
article.author = request.user
article.save()
form.save_m2m()
return redirect('article_detail', pk=article.pk)
else:
form = ArticleForm()
return render(request, 'form.html', {'form': form})Widgets del formulario
widgets controlan el renderizado HTML. Pasa un dict attrs para clases CSS, placeholders o tipos de input HTML5.
class UploadForm(forms.Form):
title = forms.CharField(
widget=forms.TextInput(attrs={'class': 'form-control'})
)
file = forms.FileField(widget=forms.ClearableFileInput)
date = forms.DateField(widget=forms.DateInput(attrs={'type': 'date'}))
tags = forms.MultipleChoiceField(
choices=TAG_CHOICES,
widget=forms.CheckboxSelectMultiple,
)Sitio de administración
Registrar el modelo en el admin
Se prefiere @admin.register sobre admin.site.register. Los modelos deben registrarse para aparecer en la interfaz de administración.
from django.contrib import admin
from .models import Article
# Simple registration
admin.site.register(Article)
# With custom ModelAdmin
@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
list_display = ('title', 'author', 'published')Personalización de ModelAdmin
list_display muestra columnas en la vista de lista. list_filter añade filtros laterales. search_fields habilita un cuadro de búsqueda.
@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
list_display = ('title', 'author', 'status')
list_filter = ('status', 'author', 'created_at')
search_fields = ('title', 'body')
ordering = ('-created_at',)
list_editable = ('status',)
list_per_page = 25
date_hierarchy = 'created_at'
readonly_fields = ('views', 'created_at')Admin con inlines
Los inlines editan modelos relacionados en la misma página que el padre. extra=1 muestra una fila vacía por defecto.
class ReviewInline(admin.TabularInline):
model = Review
extra = 1
@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
inlines = [ReviewInline]
# TabularInline: compact table format
# StackedInline: full form fields stackedAcciones personalizadas del admin
Las acciones aparecen en el desplegable de la página de lista. Reciben request y queryset. message_user muestra un mensaje flash.
@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
actions = ['publish_selected']
@admin.action(description='Publish selected')
def publish_selected(self, request, queryset):
updated = queryset.update(published=True)
self.message_user(request, f'{updated} articles published.')Configuración del sitio de administración
Sobrescribe site_header/site_title para la marca. Para varios sitios de admin, crea instancias personalizadas de AdminSite.
admin.site.site_header = 'My Site Admin'
admin.site.site_title = 'Admin Portal'
admin.site.index_title = 'Dashboard'
# Custom admin site
from django.contrib.admin import AdminSite
my_site = AdminSite(name='myadmin')
my_site.register(Article, ArticleAdmin)
# urls.py
path('myadmin/', my_site.urls)Autenticación
Modelo User integrado
El modelo User de Django tiene username, password (hasheada), email, first_name, last_name y flags de permisos.
from django.contrib.auth.models import User
user = User.objects.get(username='admin')
user.is_staff # can access admin
user.is_superuser # has all permissions
user.is_active # account enabled
user.set_password('newpass') # hash password
user.save()
user.check_password('secret') # returns True/FalseLogin y logout
authenticate() verifica las credenciales (devuelve User o None). login() crea la sesión. logout() la borra.
from django.contrib.auth import authenticate, login, logout
def login_view(request):
user = authenticate(request, username='admin', password='pass')
if user is not None:
login(request, user)
return redirect('dashboard')
return render(request, 'login.html')
def logout_view(request):
logout(request)
return redirect('home')Registro de usuarios
UserCreationForm maneja username, password y la confirmación de contraseña con validación integrada.
from django.contrib.auth.forms import UserCreationForm
def register(request):
if request.method == 'POST':
form = UserCreationForm(request.POST)
if form.is_valid():
user = form.save()
login(request, user) # auto-login after register
return redirect('home')
else:
form = UserCreationForm()
return render(request, 'register.html', {'form': form})Decorador login_required
login_required redirige a LOGIN_URL (por defecto /accounts/login/). Para CBVs, usa LoginRequiredMixin.
from django.contrib.auth.decorators import login_required
@login_required
def profile(request):
return render(request, 'profile.html')
@login_required(login_url='/custom-login/')
def settings(request):
return render(request, 'settings.html')
# Class-based view mixin
from django.contrib.auth.mixins import LoginRequiredMixin
class DashboardView(LoginRequiredMixin, ListView):
login_url = '/login/'
model = ArticleGestión de contraseñas
update_session_auth_hash evita el cierre de sesión tras cambiar la contraseña. Los validadores de contraseña aplican reglas en toda la aplicación.
from django.contrib.auth import update_session_auth_hash
# Change password
user.set_password('newpass123')
user.save()
update_session_auth_hash(request, user) # keep user logged in
# Using form
from django.contrib.auth.forms import PasswordChangeForm
form = PasswordChangeForm(user, request.POST)
if form.is_valid():
form.save()Modelo de usuario personalizado
Hereda de AbstractUser para añadir campos. Fija AUTH_USER_MODEL pronto — cambiarlo más tarde es difícil.
from django.contrib.auth.models import AbstractUser
class CustomUser(AbstractUser):
bio = models.TextField(blank=True)
avatar = models.ImageField(upload_to='avatars/', blank=True)
phone = models.CharField(max_length=20, blank=True)
# settings.py
AUTH_USER_MODEL = 'myapp.CustomUser'
# Admin
from django.contrib.auth.admin import UserAdmin
@admin.register(CustomUser)
class CustomUserAdmin(UserAdmin):
passMiddleware
Middleware integrado
¡El orden importa! SecurityMiddleware primero, luego sesiones, luego auth. Las comprobaciones CSRF corren antes del procesamiento de la vista.
MIDDLEWARE = [
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.middleware.common.CommonMiddleware',
'django.middleware.csrf.CsrfViewMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'django.contrib.messages.middleware.MessageMiddleware',
'django.middleware.clickjacking.XFrameOptionsMiddleware',
]Middleware de función personalizado
El middleware de función usa el patrón de factoría de estilo nuevo. get_response llama al siguiente middleware o a la vista.
def simple_middleware(get_response):
def middleware(request):
# Code before view (request phase)
response = get_response(request)
# Code after view (response phase)
return response
return middleware
# Example: timing middleware
import time
def timing_middleware(get_response):
def middleware(request):
start = time.time()
response = get_response(request)
response['X-Duration'] = str(time.time() - start)
return response
return middlewareMiddleware basado en clases
__init__ corre una vez al arrancar. __call__ corre por cada petición. process_view puede devolver una respuesta para saltarse la vista.
class MyMiddleware:
def __init__(self, get_response):
self.get_response = get_response
def __call__(self, request):
# Request phase (before view)
response = self.get_response(request)
# Response phase (after view)
return response
def process_view(self, request, view_func, args, kwargs):
return None # or HttpResponse to short-circuitOrden y flujo del middleware
Las peticiones pasan por el middleware de arriba abajo; las respuestas suben de abajo arriba. Pon el middleware de seguridad primero.
# Request phase: top to bottom
# Response phase: bottom to top
MIDDLEWARE = [
'A', # req: 1st -> resp: last
'B', # req: 2nd -> resp: 2nd
'C', # req: 3rd -> resp: 1st
]
# Request flows: A -> B -> C -> view
# Response flows: view -> C -> B -> ACasos de uso del middleware
El middleware puede cortocircuitar (devolver HttpResponse temprano) o adjuntar datos a request para usarlos en las vistas.
# IP restriction
class IPBlockMiddleware:
BLOCKED_IPS = ['192.168.1.100']
def __call__(self, request):
if request.META['REMOTE_ADDR'] in self.BLOCKED_IPS:
return HttpResponseForbidden('Blocked')
return self.get_response(request)
# Add context to request
class UserPrefMiddleware:
def __call__(self, request):
request.is_mobile = 'Mobile' in request.META.get('HTTP_USER_AGENT', '')
return self.get_response(request)Archivos estáticos y multimedia
Configuración de archivos estáticos
STATIC_URL es el prefijo de URL. STATICFILES_DIRS son las ubicaciones fuente (desarrollo). STATIC_ROOT es el destino de recolección en producción.
# settings.py
STATIC_URL = '/static/'
STATICFILES_DIRS = [BASE_DIR / 'static'] # dev location
STATIC_ROOT = BASE_DIR / 'staticfiles' # collectstatic output
# Project structure:
# static/
# css/style.css
# js/app.js
# img/logo.pngServir estáticos en desarrollo
Django solo sirve automáticamente los archivos estáticos cuando DEBUG=True. En producción, usa un servidor web (nginx) o WhiteNoise.
# urls.py (dev only)
from django.conf import settings
from django.conf.urls.static import static
urlpatterns = [
path('admin/', admin.site.urls),
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
# Only active when DEBUG=TrueUsar estáticos en plantillas
{% load static %} es obligatorio. {% static %} resuelve al nombre de archivo con hash en producción con ManifestStaticFilesStorage.
{% load static %}
<link rel="stylesheet" href="{% static 'css/style.css' %}">
<img src="{% static 'img/logo.png' %}" alt="Logo">
<script src="{% static 'js/app.js' %}"></script>
{# Dynamic static path #}
{% get_static_prefix as STATIC_URL %}
<img src="{{ STATIC_URL }}img/{{ theme }}.png">Configuración de archivos multimedia
MEDIA_ROOT es la ruta del sistema de archivos; MEDIA_URL es el prefijo de URL. upload_to puede ser una cadena de ruta o una función.
# settings.py
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'
# urls.py (dev)
urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
# Model with file upload
class Document(models.Model):
file = models.FileField(upload_to='documents/')
image = models.ImageField(upload_to='images/')
# Access
doc.file.url # '/media/documents/file.pdf'
doc.file.path # '/full/path/to/file.pdf'Comando collectstatic
Ejecuta collectstatic antes del despliegue. WhiteNoise permite a Django servir los archivos estáticos en producción sin nginx.
# Collect all static files into STATIC_ROOT
python manage.py collectstatic
# With clearing
python manage.py collectstatic --clear
# Production with WhiteNoise
# pip install whitenoise
MIDDLEWARE = [..., 'whitenoise.middleware.WhiteNoiseMiddleware', ...]
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'Signals
Signals integradas
Las signals permiten que apps desacopladas reaccionen a acciones. post_save se dispara tras completarse save(); pre_save antes.
from django.db.models.signals import (
post_save, pre_save, post_delete, pre_delete,
m2m_changed,
)
from django.contrib.auth.signals import (
user_logged_in, user_logged_out,
)
# Common signals:
# pre_save / post_save - before/after model save
# pre_delete / post_delete - before/after model delete
# m2m_changed - M2M relationship changes
# user_logged_in / user_logged_outConectar receptores de signals
@receiver conecta la función a la signal. sender limita a un modelo concreto. created es True solo con objetos nuevos.
from django.db.models.signals import post_save
from django.dispatch import receiver
@receiver(post_save, sender=User)
def create_profile(sender, instance, created, **kwargs):
if created:
Profile.objects.create(user=instance)
@receiver(post_save, sender=User)
def save_profile(sender, instance, **kwargs):
instance.profile.save()Desconectar signals
disconnect() es útil en pruebas o cuando necesitas impedir acciones en cascada. Proporciona siempre tanto receiver como sender.
from django.db.models.signals import post_save
# Disconnect
post_save.disconnect(
receiver=create_profile,
sender=User,
)
# Temporarily disconnect in tests
post_save.disconnect(handler, sender=Article)
# ... do stuff without signal ...
post_save.connect(handler, sender=Article)Signals personalizadas
Define las signals a nivel de módulo. send() notifica a cada receptor. Los kwargs se pasan a cada receptor conectado.
from django.dispatch import Signal, receiver
# Define a custom signal
order_created = Signal()
# Send the signal
order_created.send(
sender=Order,
order=order_instance,
user=request.user,
)
# Receive
@receiver(order_created, sender=Order)
def send_notification(sender, order, user, **kwargs):
pass # Send email notificationCasos de uso y trampas de las signals
Importa los manejadores de signals en AppConfig.ready() para asegurar que se conectan al arrancar. Evita operaciones lentas — usa Celery para trabajo asíncrono.
# Good: Profile auto-creation
@receiver(post_save, sender=User)
def ensure_profile(sender, instance, created, **kwargs):
if created:
Profile.objects.get_or_create(user=instance)
# Register in AppConfig.ready()
# apps.py
class MyAppConfig(AppConfig):
name = 'myapp'
def ready(self):
from . import signals # noqaCaché
Configuración de caché
Redis es lo recomendado para producción. LocMemCache es local al proceso (sin compartir entre workers).
# settings.py - Memcached
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.memcached.PyMemcacheCache',
'LOCATION': '127.0.0.1:11211',
}
}
# Redis
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.redis.RedisCache',
'LOCATION': 'redis://127.0.0.1:6379',
}
}
# Local memory (dev)
CACHES = {
'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}
}API de caché de bajo nivel
cache.get() devuelve None para claves ausentes. Usa get_or_set para la atomicidad de set-if-not-exists.
from django.core.cache import cache
# Set
cache.set('key', 'value', timeout=300) # 5 minutes
cache.set_many({'a': 1, 'b': 2}, timeout=60)
# Get
value = cache.get('key') # None if missing
value = cache.get('key', 'default') # with default
data = cache.get_many(['a', 'b']) # dict
# Delete
cache.delete('key')
cache.clear() # delete all
# get_or_set (atomic)
value = cache.get_or_set('key', 'value', 300)Caché de plantillas
{% cache %} guarda fragmentos HTML renderizados. Añade argumentos variables (ID de usuario, página) para evitar contenido cacheado incorrecto.
{% load cache %}
{# Cache block for 500 seconds #}
{% cache 500 sidebar %}
<div class="sidebar">
{{ expensive_data }}
</div>
{% endcache %}
{# Cache with varying key #}
{% cache 500 user_sidebar request.user.id %}
Welcome, {{ request.user.username }}
{% endcache %}Caché por vista
cache_page cachea toda la HttpResponse. La clave de caché incluye la URL, así que cada URL tiene su propia entrada de caché.
from django.views.decorators.cache import cache_page
@cache_page(60 * 15)
def article_list(request):
return render(request, 'list.html', {'articles': Article.objects.all()})
# With cache key prefix
@cache_page(60 * 15, key_prefix='articles')
def article_detail(request, pk):
...
# Class-based view
from django.utils.decorators import method_decorator
class ArticleListView(ListView):
@method_decorator(cache_page(60 * 15))
def dispatch(self, *args, **kwargs):
return super().dispatch(*args, **kwargs)Estrategias de caché
vary_on_headers crea entradas de caché separadas por valor de header. Para APIs, varía por Accept-Language o Authorization.
# Per-view cache with Vary headers
from django.views.decorators.vary import vary_on_headers
@cache_page(60 * 15)
@vary_on_headers('User-Agent')
def api_data(request):
...
# Model-level caching
def get_articles():
articles = cache.get('all_articles')
if articles is None:
articles = list(Article.objects.all())
cache.set('all_articles', articles, 300)
return articlesPruebas
Escribir pruebas
TestCase envuelve las pruebas en una transacción de base de datos (con rollback). SimpleTestCase es para pruebas sin acceso a la base de datos (más rápidas).
from django.test import TestCase, SimpleTestCase
from .models import Article
class ArticleModelTest(TestCase):
def setUp(self):
self.article = Article.objects.create(
title='Test', body='Content'
)
def test_str(self):
self.assertEqual(str(self.article), 'Test')
def test_field_default(self):
self.assertEqual(self.article.views, 0)
# SimpleTestCase: no DB access
class MathTest(SimpleTestCase):
def test_addition(self):
self.assertEqual(1 + 1, 2)Probar con el test client
self.client simula peticiones HTTP sin arrancar un servidor. .login() autentica para las peticiones siguientes.
class ViewTest(TestCase):
def setUp(self):
self.user = User.objects.create_user('test', '[email protected]', 'pass')
def test_login(self):
response = self.client.post('/login/', {
'username': 'test', 'password': 'pass'
})
self.assertEqual(response.status_code, 302)
def test_protected_view(self):
self.client.login(username='test', password='pass')
response = self.client.get('/dashboard/')
self.assertEqual(response.status_code, 200)Pruebas de modelos y QuerySets
Los datos de prueba se crean en setUp() y se revierten tras cada prueba. Usa .count() e indexación para verificar los resultados.
class ArticleQuerySetTest(TestCase):
def setUp(self):
Article.objects.create(title='A', views=100, published=True)
Article.objects.create(title='B', views=50, published=False)
def test_published_filter(self):
published = Article.objects.filter(published=True)
self.assertEqual(published.count(), 1)
def test_ordering(self):
articles = Article.objects.order_by('-views')
self.assertEqual(articles[0].title, 'A')Pruebas de URLs y formularios
reverse() construye URLs a partir de nombres. resolve() comprueba a qué vista se mapea una URL. Prueba los formularios pasando un dict data=.
from django.urls import reverse, resolve
class URLTest(TestCase):
def test_article_list_url(self):
url = reverse('article_list')
response = self.client.get(url)
self.assertEqual(response.status_code, 200)
def test_resolve(self):
url = reverse('article_detail', kwargs={'pk': 1})
self.assertEqual(resolve(url).func, views.article_detail)
class FormTest(TestCase):
def test_valid_form(self):
form = ArticleForm(data={'title': 'Hi', 'body': '...'})
self.assertTrue(form.is_valid())Fixtures y comandos de prueba
Las fixtures cargan datos de prueba desde archivos JSON. Ejecuta pruebas concretas por ruta de app, clase o función.
# Create fixture
python manage.py dumpdata myapp.Article --indent=2 > fixtures/articles.json
# Use in test
class FixtureTest(TestCase):
fixtures = ['articles.json']
def test_data_loaded(self):
self.assertEqual(Article.objects.count(), 10)
# Run tests
python manage.py test
python manage.py test myapp
python manage.py test myapp.tests.ArticleModelTestDjango REST Framework
Instalar y configurar DRF
Añade rest_framework a INSTALLED_APPS. Configura la autenticación/permisos por defecto en el diccionario de ajustes REST_FRAMEWORK.
pip install djangorestframework
# settings.py
INSTALLED_APPS = [..., 'rest_framework', 'rest_framework.authtoken']
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': [
'rest_framework.authentication.TokenAuthentication',
'rest_framework.authentication.SessionAuthentication',
],
'DEFAULT_PERMISSION_CLASSES': [
'rest_framework.permissions.IsAuthenticated',
],
}Serializers
ModelSerializer genera automáticamente los campos a partir del modelo. source= extrae de objetos relacionados. validate_<campo>() añade validación.
from rest_framework import serializers
class ArticleSerializer(serializers.ModelSerializer):
author_name = serializers.CharField(source='author.username', read_only=True)
class Meta:
model = Article
fields = ['id', 'title', 'body', 'author', 'author_name']
read_only_fields = ['id', 'author_name']
def validate_title(self, value):
if len(value) < 5:
raise serializers.ValidationError("Title too short.")
return valueViewSets
ModelViewSet proporciona CRUD (list, create, retrieve, update, destroy). Sobrescribe get_queryset() para filtrar.
from rest_framework import viewsets, permissions
class ArticleViewSet(viewsets.ModelViewSet):
queryset = Article.objects.all()
serializer_class = ArticleSerializer
permission_classes = [permissions.IsAuthenticatedOrReadOnly]
def get_queryset(self):
qs = super().get_queryset()
author = self.request.query_params.get('author')
if author:
qs = qs.filter(author__username=author)
return qs
def perform_create(self, serializer):
serializer.save(author=self.request.user)Routers
DefaultRouter genera automáticamente los patrones de URL y una vista raíz de API. basename se usa para nombrar URLs si el queryset es dinámico.
from rest_framework.routers import DefaultRouter
from .views import ArticleViewSet
router = DefaultRouter()
router.register(r'articles', ArticleViewSet, basename='article')
# router.register(r'users', UserViewSet)
# urls.py
urlpatterns = [
path('api/', include(router.urls)),
]
# Generates: /api/articles/, /api/articles/{id}/Autenticación
El token auth usa un único token estático. JWT emite tokens de acceso + refresco. SimpleJWT es la librería JWT más popular.
# Token Authentication
from rest_framework.authtoken.views import obtain_auth_token
urlpatterns = [
path('api/token/', obtain_auth_token),
]
# JWT Authentication (pip install djangorestframework-simplejwt)
from rest_framework_simplejwt.views import (
TokenObtainPairView, TokenRefreshView,
)
urlpatterns = [
path('api/token/', TokenObtainPairView.as_view()),
path('api/token/refresh/', TokenRefreshView.as_view()),
]Permisos
SAFE_METHODS son GET/HEAD/OPTIONS. has_object_permission comprueba el acceso por objeto. get_permissions() permite reglas por acción.
from rest_framework import permissions
class IsOwnerOrReadOnly(permissions.BasePermission):
def has_object_permission(self, request, view, obj):
if request.method in permissions.SAFE_METHODS:
return True # GET, HEAD, OPTIONS
return obj.author == request.user
# Built-in: IsAuthenticated, IsAdminUser,
# IsAuthenticatedOrReadOnly, AllowAny
# Per-action
class ArticleViewSet(viewsets.ModelViewSet):
permission_classes = [IsOwnerOrReadOnly]
def get_permissions(self):
if self.action == 'create':
return [permissions.IsAuthenticated()]
return super().get_permissions()Despliegue y seguridad
Ajustes de producción
Nunca subas SECRET_KEY al control de versiones. Usa variables de entorno. DEBUG=False evita fugas de información en las páginas de error.
# settings.py
DEBUG = False
ALLOWED_HOSTS = ['example.com', 'www.example.com']
SECRET_KEY = os.environ['SECRET_KEY']
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'mydb',
'USER': os.environ['DB_USER'],
'PASSWORD': os.environ['DB_PASS'],
'HOST': 'localhost',
'PORT': '5432',
}
}Archivos estáticos en producción
collectstatic reúne los archivos estáticos en STATIC_ROOT. WhiteNoise sirve archivos comprimidos con gzip y con hash desde el propio Django.
# Collect static files
python manage.py collectstatic --noinput
# WhiteNoise for serving static
MIDDLEWARE = [..., 'whitenoise.middleware.WhiteNoiseMiddleware', ...]
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'
# Or with nginx:
# location /static/ { alias /path/to/staticfiles/; }Ajustes de seguridad
SSL_REDIRECT fuerza HTTPS. HSTS indica a los navegadores que usen siempre HTTPS. X_FRAME_OPTIONS previene el clickjacking.
# settings.py
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SECURE_CONTENT_TYPE_NOSNIFF = True
X_FRAME_OPTIONS = 'DENY'
CSRF_TRUSTED_ORIGINS = ['https://example.com']Despliegue WSGI/ASGI
Gunicorn es sincrónico (Django tradicional). Uvicorn soporta ASGI (vistas asíncronas, websockets). Usa un gestor de procesos.
# Gunicorn (WSGI)
# pip install gunicorn
gunicorn myproject.wsgi:application --bind 0.0.0.0:8000 --workers 3
# Uvicorn (ASGI, for async/websockets)
# pip install uvicorn
uvicorn myproject.asgi:application --host 0.0.0.0 --port 8000 --workers 4
# Supervisor config
[program:django]
command=gunicorn myproject.wsgi:application
directory=/app
autostart=true
autorestart=trueLista de verificación de producción
check --deploy ejecuta la lista de verificación de despliegue de Django. Señala ajustes de seguridad faltantes y problemas de preparación para producción.
# Run security check
python manage.py check --deploy
# Key items:
# - DEBUG = False
# - ALLOWED_HOSTS set
# - SECRET_KEY from env
# - HTTPS enabled (SECURE_SSL_REDIRECT)
# - HSTS configured
# - collectstatic run
# - Database (PostgreSQL/MySQL)
# - Caching (Redis/Memcached)
# - Error monitoring (Sentry)Fragmentos de Django relacionados
Copy-paste ready code for common tasks.
Model Definition
Define a Django model with field types and meta options.
ORM QuerySet
Filter, exclude, annotate and chain QuerySets.
Class-Based Views
Use generic class-based views for common CRUD flows.
URL Routing
Wire URLs to views with path converters and includes.
ModelForms
Build forms from models with validation and widgets.
Template Tags
Use built-in tags and filters in Django templates.
Admin Customization
Customize the Django admin with list_display and actions.
Authentication
Login, logout, and protect views with auth decorators.
Was this helpful?