📚 Unidad ISS-00 · Entorno y proyecto Django — capa 🧠 APRENDER

🛠 Construir este bloque → · ✅ Condiciones de cierre (GATE) · 📝 Evaluación

Capa Página Para qué

🧠 Aprender esta página comprender, explicar y relacionar

🛠 Construir Entorno y proyecto Django ejecutar, programar y verificar

✅ GATE Cierre de la unidad condición para pasar al bloque siguiente

Mapa de correspondencias. Cada fila enlaza el mismo tema en las dos capas; los enlaces apuntan a secciones reales del material.

Tema	🧠 Aprender (esta página)	🛠 Construir (ISS técnico)
Objetivo	1. Objetivos de Aprendizaje	Objetivo
Recorrido	3. Comandos CLI Explicados Paso a Paso	Construcción
Cierre	7. Criterios de Aceptación (AC), Verificación y Evidencias (EVI)	Criterios de aceptación · GATE
Evaluación	9. Preguntas Profundas para Defensa Oral	GATE

🖥 Presentación del ISS

Presentación de la unidad. Diapositivas de ISS-00 — Entorno y proyecto Django (15 diapositivas). Se visualiza aquí, dentro del sitio.

⛶ Ver presentación completa ⬇ Archivo editable (.pptx)

15 diapositivas · se visualiza dentro del sitio.

🎬 Video explicativo

Recorrido audiovisual de la unidad. El video recorre el ISS técnico de ISS-00 — Entorno y proyecto Django, bloque por bloque.

9:25 min · narración en español · subtítulos activables desde el reproductor.

Infografía

Infografía de la unidad

Guía de Estudio Exhaustiva: ISS-00 — Entorno y Proyecto Django

1. Objetivos de Aprendizaje

El objetivo técnico fundamental de la unidad ISS-00 es preparar la infraestructura base del sistema creando un entorno virtual aislado e inicializando el proyecto Django denominado config, sin incorporar aún modelos de negocio, librerías adicionales ni variables de entorno de base de datos.

Resumen de Objetivos y Requisitos

Aislamiento del Entorno: Construir un entorno virtual (.venv) para aislar las dependencias del proyecto del intérprete global del sistema operativo.
Generación CLI: Inicializar el proyecto base Django exclusivamente a través de la interfaz de línea de comandos (CLI), garantizando que archivos críticos como manage.py no sean redactados a mano.
Inicialización Limpia: Generar la estructura básica del proyecto sin incluir aplicaciones ni modelos de negocio.
Versión Objetivo de Python: Python 3.12.
Versión Objetivo de Django: Django 5.2.17 (Django==5.2.17).
Estado Inicial del Directorio: El directorio del proyecto debe estar completamente vacío antes de iniciar el proceso de bootstrapped.
Conectividad a Red: Se requiere acceso activo a Internet para la descarga e instalación del paquete Django vía pip.

2. Conceptos Esenciales y Vocabulario Técnico

ORM (Object-Relational Mapper)

Mapeador Objeto-Relacional incluido de forma predeterminada dentro del paquete Django==5.2.17. Permite la abstracción e interacción con bases de datos relacionales mediante clases y objetos de Python. En esta unidad base (ISS-00) el ORM se inicializa en su estado mínimo sin definir modelos de negocio.

Django Admin

Interfaz gráfica de administración integrada en Django (django.contrib.admin), provista de manera predeterminada para la gestión del sistema y accesible desde la configuración inicial de rutas de la aplicación.

CLI (Command Line Interface)

Mecanismo de interacción por línea de comandos utilizado para la creación, configuración y gestión del proyecto. Incluye utilidades del sistema (python3 -m venv), comandos del paquete instalado (django-admin) y scripts administrativos generados (manage.py).

DJANGO_SETTINGS_MODULE

Variable de entorno de Django que especifica el módulo Python de configuración que debe cargar el framework. En este proyecto es definida automáticamente por manage.py apuntando a config.settings.

.venv

Directorio del entorno virtual aislado que contiene los binarios del intérprete de Python y las librerías instaladas mediante pip, impidiendo la contaminación o conflictos con los paquetes globales del sistema operativo.

django-admin

Herramienta CLI suministrada por el paquete Django. Se utiliza de forma exclusiva durante la fase bootstrap inicial (para ejecutar startproject) antes de que exista el script local manage.py. Una vez generado el proyecto, manage.py asume el rol principal de ejecutor administrativo.

manage.py

Script raíz generado automáticamente por el comando CLI django-admin startproject. Actúa como el envoltorio administrativo local del proyecto y fija la variable DJANGO_SETTINGS_MODULE="config.settings". Bajo ninguna circunstancia debe redactarse ni modificarse manualmente en este ISS.

URLconf

Módulo raíz de configuración de URLs ubicado en config/urls.py. Representa el punto de entrada para todas las peticiones HTTP que llegan al sistema, definiendo la constante ROOT_URLCONF = "config.urls" y estableciendo la lista inicial urlpatterns con la ruta path("admin/", admin.site.urls).

3. Comandos CLI Explicados Paso a Paso

A continuación se detalla la secuencia exacta de comandos requerida para la construcción de la unidad ISS-00:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "Django==5.2.17"
django-admin startproject config .
python -m pip freeze > requirements.txt
python -m django --version

Tabla Explicativa de Comandos

Comando	Propósito Tecno-Pedagógico	Entorno de Ejecución (Sistema vs .venv)
`python3 -m venv .venv`	Crea la estructura del entorno virtual `.venv`. Se ejecuta una sola vez usando el Python del sistema base.	Sistema Base
`source .venv/bin/activate`	Activa el entorno virtual en la sesión actual del terminal, modificando el prompt a `(.venv)`.	Transición a .venv
`python -m pip install "Django==5.2.17"`	Descarga e instala estrictamente la versión 5.2.17 de Django dentro del entorno virtual activo.	.venv
`django-admin startproject config .`	Ejecuta la generación del proyecto base. El punto `.` final fuerza a colocar `manage.py` en la raíz y la configuración en `config/`.	.venv
`python -m pip freeze > requirements.txt`	Congela y registra las dependencias y versiones instaladas exactamente en el entorno dentro del archivo `requirements.txt`.	.venv
`python -m django --version`	Comprueba y confirma la versión exacta del paquete Django instalado en el entorno virtual.	.venv

4. Archivos del Proyecto y sus Responsabilidades

Estructura del Árbol de Directorios (ISS-00)

ISS-00/
├── manage.py
├── .gitignore
├── requirements.txt
└── config/
    ├── __init__.py
    ├── settings.py
    ├── urls.py
    ├── wsgi.py
    └── asgi.py

Responsabilidad Técnica de cada Archivo

manage.py: Script administrativo del proyecto generado de forma íntegra por la CLI. Establece la variable DJANGO_SETTINGS_MODULE=config.settings y actúa como la interfaz principal para comandos de gestión en el proyecto.
config/__init__.py: Archivo en blanco que declara el directorio config/ como un paquete ejecutable e importable de Python.
config/settings.py: Módulo de configuración por defecto generado por startproject. Contiene las declaraciones iniciales del proyecto: clave secreta temporal, aplicaciones instaladas por defecto, middlewares, configuración de URLconf y la base de datos predeterminada (SQLite).
config/urls.py: Módulo URLconf raíz. Representa la puerta de entrada para todas las peticiones HTTP que ingresan a la aplicación. En esta etapa declara ROOT_URLCONF = "config.urls" e incluye únicamente la ruta hacia el panel de administración (admin/).
config/wsgi.py: Punto de entrada para servidores web compatibles con WSGI (Web Server Gateway Interface), utilizado para despliegues sincrónicos en producción.
config/asgi.py: Punto de entrada para servidores web compatibles con ASGI (Asynchronous Server Gateway Interface), habilitando capacidades asincrónicas.
requirements.txt: Archivo de control de dependencias que lista las librerías con sus versiones fijadas (en este ISS, únicamente Django==5.2.17).
.gitignore: Archivo de reglas de exclusión para el control de versiones con Git. No es generado automáticamente por Django y debe ser creado manualmente para evitar la inclusión indeseada de entornos virtuales, archivos compilados, bases de datos locales o credenciales. Debe contener exactamente las siguientes reglas:

cat > .gitignore <<'EOF'
.venv/
__pycache__/
*.py[cod]
.env
db.sqlite3
*.log
.idea/
.vscode/
staticfiles/
media/
.pytest_cache/
htmlcov/
.coverage
EOF

5. Flujo de Inicialización de Django

El proceso de bootstrapping del proyecto sigue un ciclo de vida lineal y estricto que garantiza el aislamiento de dependencias y la correcta estructura de directorios:

[Python del Sistema] ──> Crear .venv ──> Activación (source .venv/bin/activate) ──> [Intérprete .venv] ──> Instalar Django 5.2.17 ──> Invocación django-admin ──> Scaffolding (config .) ──> Creación manual .gitignore

Mecanismo de Transición del Intérprete

Ejecución Inicial: python3 -m venv utiliza por única vez el intérprete global del sistema operativo para generar el directorio .venv y su estructura binaria interna.
Activación de la Sesión: El comando source .venv/bin/activate modifica la variable de entorno PATH en la sesión de terminal activa, haciendo que las llamadas a python o pip se resuelvan hacia .venv/bin/.
Garantía de Aislamiento: Ejecutar las instalaciones de paquetes mediante python -m pip garantiza que las librerías se ubiquen dentro de .venv/lib/python3.12/site-packages/. Si se ejecutara python3 -m pip del sistema base sin haber activado el entorno, los paquetes quedarían instalados de forma global fuera del proyecto.
Nota Pedagógica sobre la Transición entre Unidades: En esta unidad (ISS-00), la activación manual del entorno mediante source .venv/bin/activate es estrictamente obligatoria para todas las operaciones de CLI, ya que manage.py existe en su forma predeterminada tal como fue generado por startproject. En la unidad subsecuente (ISS-01), se introduce una envoltura automatizada (use_project_python()) dentro de manage.py que detecta el intérprete y redirige la ejecución automáticamente hacia .venv/bin/python. Hasta que dicho mecanismo sea implementado en ISS-01, la activación manual es la única garantía de ejecución aislada.

6. Errores Frecuentes y Buenas Prácticas

Errores Comunes vs. Solución / Buena Práctica

Errores Comunes	Solución / Buena Práctica
Instalar paquetes globalmente: Ejecutar `pip install` o `python3 -m pip` sin haber activado previamente el entorno virtual.	Confirmar visualmente que el prompt de la terminal muestre `(.venv)` y ejecutar `source .venv/bin/activate`. Garantizar el uso de `python -m pip`.
Omisión del punto final `.`: Ejecutar `django-admin startproject config` omitiendo el punto final de directorio.	Incluir explícitamente el punto al final del comando (`django-admin startproject config .`). Esto coloca `manage.py` directamente en la raíz y evita la creación de directorios anidados innecesarios como `storelab/storelab/`.
Asumir que Django crea `.gitignore`: Esperar que la CLI de Django genere automáticamente el archivo de exclusión de Git.	Crear el archivo `.gitignore` manualmente mediante script de consola (por ejemplo, con `cat > .gitignore <<'EOF'`) o editor de texto, asegurando excluir explícitamente `.venv/` y `.env`.
Redacción manual de `manage.py`: Intentar escribir, modificar o estructurar manualmente el script `manage.py` durante el ISS-00.	Permitir que la CLI (`django-admin startproject`) genere el archivo `manage.py` de forma íntegra e idéntica a la especificación oficial.

7. Criterios de Aceptación (AC), Verificación y Evidencias (EVI)

AC-00-01: La ejecución de python -m django --version imprime exactamente la cadena 5.2.17.
- Verificación: Ejecutar en el terminal dentro del entorno activo:
```
python -m django --version
```
- Evidencia: EVI-00-01 (Django 5.2.17 instalado correctamente en .venv).
AC-00-02: Existen los archivos manage.py y config/urls.py en sus ubicaciones estructurales correspondientes.
- Verificación: Ejecutar el chequeo de consistencia del sistema:
```
python manage.py check
```
  Aclaración Técnica: El comando python manage.py check ejecuta exitosamente en esta etapa haciendo uso de la configuración predeterminada de SQLite (db.sqlite3 en settings.py) generada automáticamente por startproject. Este motor por defecto no requiere servicios externos ni controladores adicionales durante la unidad ISS-00.
- Evidencia: EVI-00-02 (Árbol del paquete config/ generado correctamente por la CLI).
AC-00-03: Ausencia total de aplicaciones y modelos de negocio en la estructura del proyecto.
- Verificación: Inspección visual del árbol de directorios que confirma la inexistencia de aplicaciones o modelos de dominio personalizados en esta etapa.

8. Tabla de Decisión GATE

AC	Verificación	Evidencia	Resultado
AC-00-01	versión de Django	EVI-00-01	PASS
AC-00-02	archivos del proyecto	EVI-00-02	PASS
AC-00-03	ausencia de modelos de negocio	inspección del árbol en este ISS	PASS

9. Preguntas Profundas para Defensa Oral

¿Por qué el comando django-admin startproject config . incluye un punto . al final y qué estructura de directorios evita este patrón? Respuesta Modelo: El punto final ordena a django-admin tomar el directorio de trabajo actual como la raíz del proyecto, posicionando el script manage.py directamente en dicha raíz y creando el paquete de configuración config/ al mismo nivel. Este patrón evita la generación de estructuras de carpetas anidadas o redundantes (tales como storelab/storelab/), garantizando que los módulos settings, urls, wsgi y asgi posean un nombre estático y predecible dentro de la arquitectura del proyecto.
¿Qué diferencia técnica existe entre usar python3 -m venv y los comandos subsecuentes durante la fase de construcción? Respuesta Modelo: python3 -m venv invoca por única vez el intérprete de Python global del sistema operativo para estructurar e inicializar el directorio del entorno virtual en .venv. Los comandos subsecuentes se ejecutan tras activar el entorno (source .venv/bin/activate) utilizando la sintaxis python -m ..., lo que asegura de forma explícita la invocación del binario interno de .venv y garantiza que cualquier paquete o comando instalado mediante pip quede estrictamente aislado dentro del ámbito local del proyecto.
¿Por qué manage.py define DJANGO_SETTINGS_MODULE=config.settings y qué función cumple django-admin antes de su creación? Respuesta Modelo: django-admin es la herramienta CLI global disponible tras la instalación del paquete Django que permite realizar operaciones de bootstrapping a nivel de sistema antes de la existencia del proyecto. Una vez que se ejecuta startproject, la CLI crea el script local manage.py, el cual encapsula la configuración administrativa del proyecto definiendo explícitamente la variable de entorno DJANGO_SETTINGS_MODULE="config.settings". A partir de ese instante, manage.py pasa a ser la interfaz ejecutora primaria de los comandos de gestión.
¿Por qué .gitignore debe crearse manualmente y cuáles son los dos entornos/carpetas principales que jamás deben incluirse en el repositorio de código según el ISS-00? Respuesta Modelo: Django no genera automáticamente el archivo .gitignore al inicializar el proyecto mediante la CLI. Las dos carpetas/archivos principales que bajo ningún motivo deben versionarse en el repositorio son la carpeta .venv/ (que almacena binarios compilados y dependencias pesadas específicas de la máquina local) y el archivo .env (que contendrá variables de entorno sensibles, secretos criptográficos y credenciales de bases de datos en etapas posteriores).

Navegación de la ruta: ↑ Ruta Django · → ISS-00 · 🛠 Construir

Capa	Página	Para qué
🧠 Aprender	esta página	comprender, explicar y relacionar
🛠 Construir	Entorno y proyecto Django	ejecutar, programar y verificar
✅ GATE	Cierre de la unidad	condición para pasar al bloque siguiente