01_introduccion_a_django.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[![imagenes/pythonista.png](imagenes/pythonista.png)](https://pythonista.io)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introducción a Django."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[*Django*](https://www.djangoproject.com/) es el marco de trabajo (framework) para desarrollo de aplicaciones web basado en Python de mayor popularidad y uno de los más [populares en general](https://hotframeworks.com/).\n",
    "\n",
    "Su lema es: \"El framework web para perfeccionistas con plazos de entrega\".\n",
    "\n",
    "A diferencia de microframeworks como [*Flask*](http:https://flask.pocoo.org/), *Django* viene con una basta cantidad de módulos y funcionalidades disponibles desde la instalación.\n",
    "\n",
    "Entre otras cosas, *Django* cuenta con las siguientes funcionalidades:\n",
    "\n",
    "* Instalación y configuración sencilla y rápida.\n",
    "* Cuenta con un *ORM* (Object Relational Mapper) avanzado.\n",
    "* Utiliza plantillas (templates) para desplegar aplicaciones.\n",
    "* Soporta múltipes idiomas.\n",
    "* Diseñado para aprovechar el paradigma de desarrollo dirigido por pruebas (*TDD*).\n",
    "* Se apega al patrón [*MVC*](https://es.wikipedia.org/wiki/Modelo%E2%80%93vista%E2%80%93controlador) mediante la implementación del concepto  \"*Model View Template*\".\n",
    "* Hace énfasis en la seguridad.\n",
    "* Es escalable.\n",
    "* Es muy versátil, ya que es una excelente plataforma para:\n",
    "    * Desarrollar aplicaciones web.\n",
    "    * Desarrollar API web.\n",
    "    * Desarrollo de aplicaciones móviles.\n",
    "\n",
    "La [documentación](https://docs.djangoproject.com/) del proyecto es extensa y aún cuando el idioma por defecto es el inglés, gran parte de ella está en [español](https://docs.djangoproject.com/es/2.1/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Instalación.\n",
    "\n",
    "*Django* puede ser instalado con ```pip``` desde su repositorio en https://pypi.org/project/Django/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**\n",
    "\n",
    "La siguiente celda instalará la versión más reciente de *Django*.\n",
    "\n",
    "**Nota:** En caso de utilizar esta notebook en un entorno distinto al del la máquina virtual de Pythonista<sup>®</sup>, tome en cuenta que debe de contar con ```pip``` instalado y con los permisos necesarios para instalar el paquete correspondiente.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "!pip install django"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Proyectos (*projects*) y aplicaciones (*apps*) de *Django*.\n",
    "\n",
    "Al desarrollar aplicaciones web en *Django* se entiende lo siguiente:\n",
    "\n",
    "* Un proyecto se refiere a un producto completo que será desplegado por el *framework*. Por lo general un proyecto corresponde a un sitio web.\n",
    "* Una aplicación es un componente autocontenido de un proyecto y por lo general corresponde a una *URL* dentro del sitio."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## El comando ```django-admin```.\n",
    "\n",
    "Este comando es el encargado de la administración general de los proyectos basados en *Django* y es instalado de forma automática cuando se instala el paquete.\n",
    "\n",
    "La sintaxis de uso del comando es la siguiente al ejecutarse desde una terminal.\n",
    "\n",
    "\n",
    "```\n",
    "django-admin <subcomando> <argumentos>\n",
    "```\n",
    "\n",
    "Donde:\n",
    "\n",
    "* ```<subcomando>``` corresponde a una instrucción específica.\n",
    "* ```<argumentos>``` corersponde a una secuencia de valores específicos."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda despelgará la localización donde se encuentra ```django-admin```. \n",
    "\n",
    "\n",
    "**Nota:** El comando ```which``` es propio de sistemas basados en *GNU/Linux*. En caso de que se ejecute el siguiente comando en un entorno distinto al de la VM proporcionada por Pythonista®, es posible que tenga que instalarlo. En otros sistemas no es posible ejecutar este comando."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!which django-admin"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda despelgará la función de ayuda de ```django-admin```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!django-admin help"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!django-admin help startproject"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Despliegue de la estructura inicial de un proyecto.\n",
    "\n",
    "El comando ```django-admin startproject``` creará la estructura inicial de un proyecto, usando la siguiente sintaxis:\n",
    "\n",
    "```\n",
    "django-admin startproject <nombre>\n",
    "```\n",
    "\n",
    "Donde:\n",
    "\n",
    "* ```<nombre>``` corresponde al nombre del proyecto y cuya estructura será creada dentro de un subdirectorio del mismo nombre."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda realizará lo siguiente:\n",
    "\n",
    "   * Creará el subdirectorio ```tutorial``` en el directorio en el que se encuentra actualmente esta *notebook*.\n",
    "   * Desplegará la estructura mínima de archivos y de subdirectorios de un proyecto de *Django*."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "!django-admin startproject tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### La estructura por defecto de un proyecto de *Django*.\n",
    "\n",
    "A continuación se mostrará la estructura creada dentro del subdirectorio [```tutorial```](tutorial)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!tree tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La estructura resultante sería algo similar a lo siguiente:\n",
    "\n",
    "```\n",
    "tutorial\n",
    "├── manage.py\n",
    "└── tutorial\n",
    "    ├── __init__.py\n",
    "    ├── settings.py\n",
    "    ├── urls.py\n",
    "    └── wsgi.py\n",
    "```\n",
    "\n",
    "* Se puede apreciar que en el directorio ```tutorial``` se encuentran:\n",
    "    * El script ```manage.py```\n",
    "    * Otro subdirectorio de nombre ```tutorial``` con la estructura de un paquete de *Python*."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## El *script* ```manage.py```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Este *script* hace uso de forma indirecta de ```django-admin``` para la gestión de un proyecto en particular con cualquiera de la siguientes sintaxis.\n",
    "\n",
    "```\n",
    "./manage.py <subcomando> <parámetros>\n",
    "```\n",
    "o\n",
    "```\n",
    "python manage.py <subcomando> <parámetros>\n",
    "```\n",
    "\n",
    "Donde:\n",
    "\n",
    "* ```<subcomando>``` corresponde a una instrucción específica.\n",
    "* ```<argumentos>``` corersponde a una secuencia de valores específicos.\n",
    "\n",
    "**Nota:** Es necesario ejecutar el *script* ```manage.py``` desde el directorio en el que dicho script se encuentra. A partir de este momento se dará por hecho lo anterior."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda moverá la ejecución de la *notebook* al directorio ```tutorial```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%cd tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda desplegará el contenido del *script* ```manage.py```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pycat manage.py"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* En vista de que el directorio de ejecución de esta *notebook* fue cambiado al subdirectorio ```tutorial```, se ejecutará el *script* ```manage.py``` de la forma siguiente:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python manage.py help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creación de una aplicación.\n",
    "\n",
    "Para crear una aplicación se utiliza el siguiente comando especificando el directorio en el que se encontrará la aplicación dentro del directorio del proyecto.\n",
    "\n",
    "```\n",
    "./manage.py startapp <nombre>\n",
    "```\n",
    "o\n",
    "```\n",
    "python manage.py startapp <nombre>\n",
    "```\n",
    "\n",
    "Donde:\n",
    "\n",
    "* ```<nombre>``` corresponde al nombre de la aplicación y cuya estructura será creada dentro de un subdirectorio del mismo nombre."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Ejemplo:**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* La siguiente celda creará el sistema de archivos de una aplicación localizada en un nuevo subdirectorio llamado ```main``` en el directorio ```prueba```."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!tree"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "!python manage.py startapp main"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!tree"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "scrolled": true
   },
   "source": [
    "La estructura de archivos del directorio ```tutorial``` resultante sería algo similar a lo siguiente:\n",
    "\n",
    "```\n",
    "tutorial/\n",
    "├── main\n",
    "│   ├── admin.py\n",
    "│   ├── apps.py\n",
    "│   ├── __init__.py\n",
    "│   ├── migrations\n",
    "│   │   └── __init__.py\n",
    "│   ├── models.py\n",
    "│   ├── tests.py\n",
    "│   └── views.py\n",
    "├── manage.py\n",
    "└── tutorial\n",
    "    ├── __init__.py\n",
    "    ├── settings.py\n",
    "    ├── urls.py\n",
    "    └── wsgi.py\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Arranque  del servidor de aplicaciones de  un proyecto.\n",
    "\n",
    "```\n",
    "./manage.py runserver <rango de transmisión>:<puerto>\n",
    "```\n",
    "o\n",
    "```\n",
    "python manage.py runserver <máscara transmisión>:<puerto>\n",
    "```\n",
    "\n",
    "Donde:\n",
    "\n",
    "* ```<máscara de transmisión>``` corresponde a una máscara *IP*, un dominio o un *host* que serán las direcciones autorizadas para acceder al servidor de *Django*. \n",
    "* ```<puerto>``` corresponde al número de puerto desde el cual será accesible el servidor de *Django*.\n",
    "\n",
    "**Notas:**\n",
    "\n",
    "* Si no se especifica el rango de transmisión, el servidor de *Django* sólo será accesible para ```localhost```.\n",
    "* Si no se especifica el puerto, el servidor de *Django* estará disponible en el puerto ```8000```.\n",
    "* Para que el servidor de *Django* esté disponible para todas las direcciones *IP*, se definirá el rango de transmisión ```0.0.0.0```."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Arranque desde la *notebook*.\n",
    "\n",
    "En caso de usar una *notebook* desde una máquina virtual proporcionada por *Pythonista<sup>®</sup>*, es posible iniciar el servidor web de *Django* ejecutando las siguientes celdas. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!python manage.py runserver 0.0.0.0:8000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Arranque desde una terminal.\n",
    "\n",
    "#### Carga del entorno.\n",
    "\n",
    "* En caso de que se acceda a la terminal de la máquina virtual proporcionada por *Pythonista<sup>®</sup>*, es necesario cargar el entormno con el siguiente comando.\n",
    "\n",
    "```\n",
    "source ~/pythonista/bin/activate\n",
    "```\n",
    "#### Inicio del servidor.\n",
    "\n",
    "* Desde la terminal ubicar el *shell* en el directorio ```tutorial```, en el cual se encuentra el *script* ```manage.py```.\n",
    "\n",
    "```\n",
    "python manage.py runserver 0.0.0.0:8000\n",
    "```\n",
    "\n",
    "**Nota:** \n",
    "Es necesario que el *firewall* de su equipo esté configurado para transmitir desde el puerto ```8000```. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "scrolled": true
   },
   "source": [
    "Una vez iniciado el servidor, la terminal regresará algo similar a lo siguiente:\n",
    "\n",
    "``` \n",
    "Watching for file changes with StatReloader\n",
    "Performing system checks...\n",
    "\n",
    "System check identified no issues (0 silenced).\n",
    "\n",
    "You have 17 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): admin, auth, contenttypes, sessions.\n",
    "Run 'python manage.py migrate' to apply them.\n",
    "\n",
    "November 07, 2019 - 04:21:12\n",
    "Django version 2.2.7, using settings 'tutorial.settings'\n",
    "Starting development server at http:https://0.0.0.0:8000/\n",
    "Quit the server with CONTROL-C.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Lo anterior indicaría que el servidor inició correctamente y el servicio puede ser accedido desde http:https://localhost:8000. El navegador desplegará algo similar a la siguiente imagen:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"imagenes/01/inicio.png\" width=\"700px\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### La aplicación de administración de *Django*.\n",
    "\n",
    "Además de la *URL* principal del servidor de *Django*, es posible acceder a la aplicación de administración del sitio, la cual se localiza en http:https://localhost:8000/admin y se vería de la siguiente forma:\n",
    "\n",
    "<img src=\"imagenes/01/admin.png\" width=\"700px\">\n",
    "\n",
    "**Nota:** La aplicación de administración requiere que se definan usuarios con los roles y permisos correspondientes, por lo que aún cuando está habilitada, no es funcional."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Finalización de la ejecución del servicio.\n",
    "\n",
    "Para detener la ejecución del servidor es necesario teclear <kbd>Ctrl</kbd><kbd>C</kbd>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: center\"><a rel=\"license\" href=\"http:https://creativecommons.org/licenses/by/4.0/\"><img alt=\"Licencia Creative Commons\" style=\"border-width:0\" src=\"https://i.creativecommons.org/l/by/4.0/80x15.png\" /></a><br />Esta obra está bajo una <a rel=\"license\" href=\"http:https://creativecommons.org/licenses/by/4.0/\">Licencia Creative Commons Atribución 4.0 Internacional</a>.</p>\n",
    "<p style=\"text-align: center\">&copy; José Luis Chiquete Valdivieso. 2021.</p>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}