# creacion-de-aplicaciones-web-en-django-y-python

Creación de Aplicaciones Web en Django y Python

Volver a la portada del curso
Lectura (Markdown)

Estructura de un Proyecto

Sección 2 · Estructura de un Proyecto Django

Estructura de un proyecto Django

Dos comandos bastan para tener la base de la tienda web de PyShop: django-admin startproject y python manage.py startapp. Entre los dos crean una docena de archivos. Saber qué hace cada uno te ahorra horas: casi todos los errores de principiante («la plantilla no existe», «la tabla no existe», «la URL no responde») vienen de un archivo que falta o de una app sin registrar.

Proyecto y app: dos niveles distintos

Un proyecto es la instalación completa: la configuración, las rutas principales y la base de datos. Una app es un paquete de Python con una responsabilidad concreta (modelos, vistas y plantillas de un tema). Un proyecto contiene varias apps, y una app bien hecha puede reutilizarse en otro proyecto. En el curso, el proyecto se llama pyshop y la primera app, catalogo.

python -m django --version        # 5.2.18
django-admin startproject pyshop .
python manage.py startapp catalogo

El punto final de startproject pyshop . indica que el proyecto se cree en la carpeta actual. Sin él, Django crea una carpeta pyshop/ extra que contiene otra pyshop/, y la estructura se vuelve confusa.

Lo que crea cada comando

manage.py
pyshop/__init__.py
pyshop/asgi.py
pyshop/settings.py
pyshop/urls.py
pyshop/wsgi.py
catalogo/__init__.py
catalogo/admin.py
catalogo/apps.py
catalogo/migrations/__init__.py
catalogo/models.py
catalogo/tests.py
catalogo/views.py
  • manage.py: la puerta de entrada a los comandos (runserver, migrate, startapp, test…). Fija la variable DJANGO_SETTINGS_MODULE en "pyshop.settings" y le pasa el comando a Django.
  • pyshop/settings.py: toda la configuración del proyecto.
  • pyshop/urls.py: la tabla de rutas principal (ROOT_URLCONF).
  • pyshop/wsgi.py y asgi.py: los puntos de entrada para los servidores de producción, síncronos (WSGI) o asíncronos (ASGI).
  • catalogo/models.py, views.py y admin.py: los modelos, las vistas y el registro en el panel de administración.
  • catalogo/apps.py: la clase CatalogoConfig que describe la app.
  • catalogo/migrations/: aquí se guardan las migraciones que generará makemigrations.
  • catalogo/tests.py: el lugar de las pruebas automáticas.

Ojo: startapp no crea urls.py. El archivo catalogo/urls.py se escribe a mano, y lo mismo pasa con forms.py y la carpeta templates/.

settings.py, pieza por pieza

El settings.py recién generado trae DEBUG = True, 6 apps en INSTALLED_APPS (admin, auth, contenttypes, sessions, messages y staticfiles) y 7 entradas en MIDDLEWARE. Las claves que más vas a tocar:

  • INSTALLED_APPS: las apps activas. Una app que no está aquí no tiene migraciones ni plantillas que Django encuentre.
  • DATABASES: por defecto, SQLite en el archivo db.sqlite3, sin servidor aparte.
  • TEMPLATES: dónde se buscan las plantillas. Con APP_DIRS: True se busca en la carpeta templates/ de cada app; DIRS agrega carpetas del proyecto.
  • LANGUAGE_CODE y TIME_ZONE: idioma de los mensajes de Django y zona horaria.
  • DEBUG, SECRET_KEY y ALLOWED_HOSTS: seguridad. Con DEBUG = True los errores muestran páginas detalladas, útiles en desarrollo y peligrosas en producción.

En PyShop la configuración queda así (fragmento de pyshop/settings.py):

import os

SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "solo-para-desarrollo-cambiala")
DEBUG = os.environ.get("DJANGO_DEBUG", "1") == "1"

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "catalogo",
]

LANGUAGE_CODE = "es"
TIME_ZONE = "America/Mexico_City"

Leer SECRET_KEY y DEBUG de variables de entorno desde el principio evita subir secretos al repositorio y deja el proyecto listo para el despliegue de la última sección. Con LANGUAGE_CODE = "es", los mensajes de error de los formularios y del login salen en español.

Conectar las rutas

pyshop/urls.py delega las rutas de la tienda en la app con include:

from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("cuentas/", include("django.contrib.auth.urls")),
    path("", include("catalogo.urls")),
]

Cada app mantiene sus propias rutas y el proyecto solo decide bajo qué prefijo se montan. Dentro de catalogo/urls.py, la línea app_name = "catalogo" crea un espacio de nombres: la lista de productos se llama "catalogo:lista" y no choca con otra vista lista de otra app.

Para comprobar que todo está en orden, python manage.py check revisa la configuración sin arrancar el servidor. En el proyecto de PyShop responde «System check identified no issues (0 silenced).»

Trampas comunes

  • Olvidar registrar la app en INSTALLED_APPS: makemigrations no la ve y sus plantillas no se encuentran.
  • Buscar un urls.py en la app recién creada. No existe hasta que lo escribes.
  • Omitir el punto en startproject pyshop . y terminar con carpetas anidadas.
  • Dejar la SECRET_KEY escrita en el código y subirla a un repositorio público.
  • Correr manage.py desde otra carpeta: se ejecuta desde la carpeta donde está el archivo.

El notebook estructura-y-modelos ejecuta startproject y startapp en una carpeta temporal y muestra el árbol de archivos. Úsalo para ubicar cada archivo de esta lectura antes de escribir modelos.

Recursos