Introduction to Django.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "<style>\n",
       ".reveal pre code {\n",
       "   max-height: 1000px;\n",
       "   font-size: 80%;\n",
       "   line-height: 100%;\n",
       "}\n",
       "</style>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from notebook.services.config import ConfigManager\n",
    "cm = ConfigManager()\n",
    "cm.update('livereveal', {\n",
    "        'scroll': True,\n",
    "        'width': '100%'\n",
    "})\n",
    "\n",
    "from IPython.core.display import HTML\n",
    "import urllib2\n",
    "HTML(\"\"\"\n",
    "<style>\n",
    ".reveal pre code {\n",
    "   max-height: 1000px;\n",
    "   font-size: 80%;\n",
    "   line-height: 100%;\n",
    "}\n",
    "</style>\n",
    "\"\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Introduction to Django\n",
    "\n",
    "<sub>by Joe Meilinger</sub>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Why use Django?\n",
    "\n",
    "- **GREAT** community support \n",
    "- Used by industry giants: Disqus, Instagram, Pinterest, The Onion, NASA, etc\n",
    "- Weathered the changes in industry over time, first public release back in 2005\n",
    "- Variety of community-supported plugins/modules available, see <https://djangopackages.org/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Batteries included approach\n",
    "\n",
    "- Opionated, MVC-ish oriented\n",
    "- Relational database backend required\n",
    "- Built in testing support\n",
    "- Routing engine\n",
    "- Powerful template processing\n",
    "- Built-in support for authentation (via `contrib` modules) as well as GIS features\n",
    "- Pairs very well with PostGIS (for GIS)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Things we'll be covering in this talk\n",
    "\n",
    "- Installing and getting started\n",
    "- Models\n",
    "- Python REPL\n",
    "- Django Administration\n",
    "- Views\n",
    "- Templates\n",
    "- Routing\n",
    "\n",
    "<div class=\"text-center\">There is a **ton** more to Django!</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "## The Example\n",
    "\n",
    "Very, very simple structure for being able to track the location of different types of trees."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Installing Django\n",
    "\n",
    "```bash\n",
    "pip install django\n",
    "pip install psycopg2  # for postgres support\n",
    "pip install ipython  # for more friendly REPL\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "## Install PostgreSQL\n",
    "\n",
    "- Mac: https://postgresapp.com\n",
    "- Windows: https://www.postgresql.org/download/windows/\n",
    "\n",
    "```bash\n",
    "psql -c \"create database treeseeker\"\n",
    "psql treeseeker -c \"create extension postgis\"\n",
    "```\n",
    "\n",
    "## Install GDAL\n",
    "\n",
    "- Mac: https://sandbox.idre.ucla.edu/sandbox/general/how-to-install-and-run-gdal OR `brew install gdal`\n",
    "- Windows: https://pythongisandstuff.wordpress.com/2016/04/13/installing-gdal-ogr-for-python-on-windows/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Create a barebones project\n",
    "\n",
    "In Django a \"project\" is our main application container that orchestrates \"apps\" contained within.\n",
    "\n",
    "```bash\n",
    "django-admin startproject treeseeker  # Create Django project\n",
    "cd treeseeker\n",
    "python manage.py startapp core  # House for our models/views/templates\n",
    "```\n",
    "\n",
    "Lets enable our app in the settings for our project (`treeseeker/settings.py`):\n",
    "\n",
    "```python\n",
    "INSTALLED_APPS = [\n",
    "    'django.contrib.admin',\n",
    "    'django.contrib.auth',\n",
    "    'django.contrib.contenttypes',\n",
    "    'django.contrib.sessions',\n",
    "    'django.contrib.messages',\n",
    "    'django.contrib.staticfiles',\n",
    "    'django.contrib.gis',  # <-- needed for GIS capabilities\n",
    "    'core'  # <-- our application\n",
    "]\n",
    "```\n",
    "\n",
    "While we are in there...lets wire up our Postgres database connection:\n",
    "\n",
    "```python\n",
    "DATABASES = {\n",
    "    'default': {\n",
    "        'ENGINE': 'django.contrib.gis.db.backends.postgis',\n",
    "        'NAME': 'treeseeker'\n",
    "    }\n",
    "}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Model/Template/View/Routes\n",
    "\n",
    "**Models:** contain entities (mostly persistent)\n",
    "\n",
    "**Views:** manipulate models, handle passing data to templates\n",
    "\n",
    "**Templates:** render HTML/visualize the models\n",
    "\n",
    "**Route:** direct the incoming requests to views based on URL structure"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "## Great!  What's next\n",
    "\n",
    "Completely based on user preference, but usually start with models:\n",
    "\n",
    "- Flesh out the persistent components of the site first\n",
    "- Using the Python interpreter allows for easy object creation and testing => `python manage.py shell`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Models\n",
    "\n",
    "`TreeSpecies` describes a single tree species\n",
    "\n",
    "`TreeSample` describes a single sample of a tree\n",
    "\n",
    "\n",
    "In `core/models.py`:\n",
    "\n",
    "```python\n",
    "from django.contrib.gis.db import models  # We're importing from gis since we're using a geometry\n",
    "\n",
    "class TreeSpecies(models.Model):\n",
    "    \"\"\" Describes a single species of tree \"\"\"\n",
    "    common_name = models.CharField(max_length=1024, null=True, blank=True)\n",
    "    genus = models.CharField(max_length=255)\n",
    "    species = models.CharField(max_length=255)\n",
    "\n",
    "    def __str__(self):\n",
    "        return '({} {}) {}'.format(self.genus, self.species, self.common_name)\n",
    "\n",
    "    @staticmethod\n",
    "    def from_csv(fname):\n",
    "        \"\"\" Loads species information from a CSV (as provided from www.theplantlist.org) \"\"\"\n",
    "        import csv\n",
    "        ret = []\n",
    "        reader = csv.DictReader(open(fname))\n",
    "        for r in reader:\n",
    "            ret.append(TreeSpecies(genus=r['Genus'], species=r['Species']))\n",
    "        return ret\n",
    "\n",
    "class TreeSample(models.Model):\n",
    "    \"\"\" Describes a single sample/observation of a tree \"\"\"\n",
    "    objects = models.GeoManager()\n",
    "    geom = models.PointField()  # The physical lat/lon of the tree\n",
    "    treespecies = models.ForeignKey(TreeSpecies, on_delete=models.CASCADE)\n",
    "    height = models.DecimalField(null=True, blank=True, max_digits=5, decimal_places=2)\n",
    "    crown_width = models.DecimalField(null=True, blank=True, max_digits=5, decimal_places=2)\n",
    "    collected_at = models.DateTimeField(auto_now_add=True)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## The Python read eval print loop (REPL)\n",
    "\n",
    "```bash\n",
    "python manage.py shell\n",
    "```\n",
    "\n",
    "Let's load some data!\n",
    "\n",
    "```bash\n",
    "> from core.models import TreeSpecies\n",
    "> trees = TreeSpecies.from_csv('../Fageceae.csv')  # Only loads into memory, not yet saved!\n",
    "> for t in trees:\n",
    ">     t.save()\n",
    "\n",
    "ProgrammingError: relation \"core_treespecies\" does not exist\n",
    "```\n",
    "\n",
    "What?!?!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Migrations -- versioning your database\n",
    "\n",
    "Django can automatically create migrations for you from your declared models!\n",
    "\n",
    "```bash\n",
    "python manage.py makemigrations\n",
    "```\n",
    "\n",
    "See `core/migrations/0001_initial.py`.  Now we can modify our local development database via:\n",
    "\n",
    "```bash\n",
    "python manage.py migrate\n",
    "python manage.py createsuperuser  # Lets create a superuser right now (for a future step)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Running locally\n",
    "\n",
    "```bash\n",
    "python manage.py runserver\n",
    "```\n",
    "\n",
    "Open browser to <http://localhost:8000>, automatically reloads when code changes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Adminstration for free!\n",
    "\n",
    "In `core/admin.py`:\n",
    "\n",
    "```python\n",
    "from django.contrib.gis import admin\n",
    "from core.models import TreeSample, TreeSpecies\n",
    "\n",
    "class TreeSampleAdmin(admin.OSMGeoAdmin):\n",
    "    list_display = ['treespecies', 'collected_at']\n",
    "    search_fields = ['treespecies__genus', 'treespecies__species', 'treespecies__common_name']\n",
    "\n",
    "class TreeSpeciesAdmin(admin.OSMGeoAdmin):\n",
    "    list_display = ['genus', 'species', 'common_name']\n",
    "    search_fields = ['genus', 'species', 'common_name']\n",
    "\n",
    "admin.site.register(TreeSample, TreeSampleAdmin)\n",
    "admin.site.register(TreeSpecies, TreeSpeciesAdmin)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Views\n",
    "\n",
    "In `core/views.py`:\n",
    "\n",
    "```python\n",
    "from django.shortcuts import render\n",
    "from django.views.generic import ListView, DetailView\n",
    "from core.models import TreeSpecies, TreeSample\n",
    "\n",
    "# Create your views here.\n",
    "\n",
    "class TreeSpeciesList(ListView):\n",
    "    model = TreeSpecies\n",
    "    template_name = 'index.html'\n",
    "\n",
    "class TreeSampleDetail(DetailView):\n",
    "    model = TreeSample\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Templates\n",
    "\n",
    "In `core/templates/index.html`:\n",
    "\n",
    "```python\n",
    "<!DOCTYPE html>\n",
    "<html lang=\"en\">\n",
    "  <body>\n",
    "    {% for species in object_list %}\n",
    "      {{ species }} - {{ species.treesample_set.count }}<br/>\n",
    "    {% empty %}\n",
    "      No species!\n",
    "    {% endfor %}\n",
    "  </body>\n",
    "</html>\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Routing\n",
    "\n",
    "In `core/urls.py`:\n",
    "\n",
    "```python\n",
    "from django.conf.urls import url, include\n",
    "from django.contrib import admin\n",
    "from .views import TreeSpeciesList\n",
    "\n",
    "urlpatterns = [\n",
    "    url(r'^$', TreeSpeciesList.as_view(), name='species-list'),\n",
    "]\n",
    "```\n",
    "\n",
    "In `treeseeker/urls.py`:\n",
    "\n",
    "```python\n",
    "from django.conf.urls import url, include\n",
    "from django.contrib import admin\n",
    "\n",
    "urlpatterns = [\n",
    "    url(r'^', include('core.urls')),\n",
    "    url(r'^admin/', admin.site.urls),\n",
    "]\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Next steps\n",
    "\n",
    "- Django Forms\n",
    "- Unit testing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Plugins to check out\n",
    "\n",
    "- API framework for Django: http://www.django-rest-framework.org/\n",
    "- General Django extensions: http://django-extensions.readthedocs.io/en/latest/ (lots of gems)\n",
    "- Debugging (in browser): http://django-debug-toolbar.readthedocs.io/en/latest/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "## Resources\n",
    "\n",
    "- https://www.djangoproject.com/\n",
    "- https://djangopackages.org/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Thank you!\n",
    "\n",
    "**@joemeilinger** on Twitter<br/>\n",
    "joemeilinger@gmail.com<br/>\n",
    "**meilinger** on STL Tech Slack organization => get your invite at https://stltech.herokuapp.com\n",
    "\n",
    "Also, if you're looking for some education and path to a career in Python, be sure to check out https://launchcode.org/apply"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}