getting-started.mo

Owner: Tycho Tatitscheff

Note: Please create an issue or even a Pull Request with your feedback, typo correction.

Context

During this standard, we will take the example of a book library management app.

We will thus create a MAB project (BAM, reversed) and a Library app containing a Book and a Author Models.

We will create an Admin using Django Admin Framework and a rest API, using Django Rest Framework.

Prerequisites (~10 min)

• Have HomeBrew installed (ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)) (~3 min)

• Have $PATH environment variable prioritizing Homebrew package (export PATH=/usr/local/bin:/usr/local/sbin:$PATH in .bashrc or similar) (~3 min)

• Have Python 3.6 installed (brew install python3): 3.6 is needed for [f"{variable} text" syntax] (https://cito.github.io/blog/f-strings/), if you have version 3.x (x lower then 6, just use the old format "{} text".format(variable) (~2 min)

• Have virtualenv installed (pip3 install virtualenv) (~1 min)

• If you use Visual Studio Code, read this article (~5 min)

Steps (~35 min)

Important Note: You should commit between each steps, as you have a shippable application at the end of each steps. This will help you reverting if you delete important stuff.

Initialise a new python project (~5 min)

• Create a directory for the project: mkdir ~/Code/django_formation

• Go to the directory: cd ~/Code/django_formation

• Init a git directory: git init

• Create a python env for your project virtualenv -p $(which python3) .venv

• Add this python env to project .gitignore: echo ".venv" > .gitignore

• Activate the virtualenv source .venv/bin/activate

CHECK 1: You should see the name of the env in front or your terminal prompt

CHECK 2: Python should now points to your env:

(.venv) ➜  django git:(master) ✗ which python
~/Code/django_formation/django/.venv/bin/python

CHECK 3: you should have a .env and a .git folder, plus a .gitignore file

(.venv) ➜  django git:(master) ✗ ls -lath
drwxr-xr-x   9 user  staff   306B Aug  3 14:18 .git
drwxr-xr-x   5 user  staff   170B Aug  3 14:18 .
-rw-r--r--   1 user  staff     6B Aug  3 14:18 .gitignore
drwxr-xr-x   7 user  staff   238B Aug  3 14:16 .venv
drwxr-xr-x  67 user  staff   2.2K Aug  3 14:03 ..

Install django (~1 min)

• Install django with pip: pip install django

• Save the dependencies to a lockfile: pip freeze > requirements.txt

CHECK 1: you should have a requirements.txt containing:

(.venv) ➜  django git:(master) ✗ cat requirements.txt
Django==1.11.4
pytz==2017.2

CHECK 2: django commands should be available django-admin.py

Create a project and a first application (~4 min)

• Start new project MAB (Mobile Application Backend, or BAM reversed): django-admin.py startproject mab . (Note the trailing '.' character)

• Go to mab: cd mab

  NOTE: this way of organizing app inside project is not the default, but, in a smaller extends, it is the recommended way for django by Two Scoops of Django, the best book in the world about good practise with django.

• Create a first app Library (that will store and manage BAM books): django-admin.py startapp library

• Add 'mab.library' to the INSTALLED_APPS, in the settings.py (DO NOT REPLACE THE WHOLE FILE)

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'mab.library'
]

• Go back to root of the project: cd ~/Code/django_formation

• Migrate the database: python manage.py migrate

  NOTE: In order to keep the method of operation simple, we use the built in sqlite adapters. You can read more to change it the beautiful documentation.

• Create the django super user: python manage.py createsuperuser and fill with a username, an email and a very-secret(™) password

CHECK:

• Run the server: python manage.py runserver

• Access http://127.0.0.1:8000 and see the "It worked page"

• Access http://127.0.0.1:8000/admin, connect and see the admin page with the username/password created above

Add the first model (~5 min)

NOTE: for editing Python code, I recommend using Pycharm. The debugging and auto complete features helps a lot. There is a community edition that is free to use. That being said, @yann committed on making VSCode great again, even for python. Stay tuned.

• Open mab/library/models.py in Pycharm (or other, if you still resists).

• Lets start with a model Author: a model derive from models.Model, and for project documentation have a small docstring explaining what it is

from django.db import models

class Author(models.Model):
    """Represent the author of a book"""
    pass

• Lets add the first fields in the Author models: there is a lot of available fields in django.db.models and even more available in platform specifics modules (eg, postgres array or json fields), or in external plugins

from django.db import models

class Author(models.Model):
    """Represent the author of a book"""
    first_name = models.CharField(
        max_length=20, 
        verbose_name="The first name of the author", 
        null=False, 
        blank=False
    )
    last_name = models.CharField(
        max_length=20, 
        verbose_name="The first name of the author",
        null=False,
        blank=False
    )
    created = models.DateTimeField(
        auto_now_add=True, 
        verbose_name="The creation date of the author in database"
    )
    modified = models.DateTimeField(
        auto_now=True, 
        verbose_name="The modification date of the author in database"
    )

NOTE: it is a good practice to add created and modified fields to models, and add a verbose name.

• Create auto-magically the migrations: python manage.py makemigrations

• Migrate the database: python manage.py migrate

CHECK 1:

• Launch python manage.py showmigrations: you should see a table with django internal migrations and your migration for library app

CHECK 2:

• Install https://sqlitestudio.pl
• Open the migrated sqlite file

• See the new table

Complete with other models (~1 min)

• Edit the models.py file so it looks like:

from django.db import models

SUBJECTS_ENUMS = (
    ('front', 'Front End'),
    ('back', 'Backend'),
    ('devops', 'Dev-Ops'),
    ('lean', 'Lean'),
    ('agile', 'Agile'),
)


class Author(models.Model):
    """Represent the author of a book"""
    first_name = models.CharField(max_length=20, verbose_name="The first name of the author", null=False, blank=False)
    last_name = models.CharField(max_length=20, verbose_name="The first name of the author", null=False, blank=False)
    created = models.DateTimeField(auto_now_add=True, verbose_name="The creation date of the author in database")
    modified = models.DateTimeField(auto_now=True, verbose_name="The modification date of the author in database")

    def __str__(self):
        # The name of the object
        return f"{self.first_name} {self.last_name}"


class Book(models.Model):
    title = models.CharField(max_length=40, null=False, blank=False, verbose_name="The title of the book")
    isbn = models.CharField(max_length=13, null=False, blank=False, verbose_name="The ISBN number")
    author = models.ForeignKey(Author, null=False, verbose_name="Link to the author of the book")
    subject = models.CharField(max_length=10, choices=SUBJECTS_ENUMS, null=False, blank=False, verbose_name="Main subject of the book")
    buy_date = models.DateField(verbose_name="The date when BAM buy the book")
    created = models.DateTimeField(auto_now_add=True, verbose_name="The creation date of the author in database")
    modified = models.DateTimeField(auto_now=True, verbose_name="The modification date of the author in database")

    def __str__(self):
        # The name of the object
        return f"{self.title}"

• Make migrations and migrate

Generate the admin (~1 min)

• Open admin.py

from django.contrib import admin
from .models import Author, Book

admin.site.register(Author)
admin.site.register(Book)

CHECK:

• Access http://127.0.0.1:8000/admin, connect and see the admin page

Customize the admin (~3 min)

• You can edit the admin to profit from django powerful admin

from django.contrib import admin
from .models import Book, Author


# The inline would list for every author the books they made
class BookInline(admin.TabularInline):
    model = Book
    readonly_fields = (
        'title',
        'isbn',
        'author',
        'subject',
        'buy_date',
        'created',
        'modified'
    )

    def has_add_permission(self, request, obj=None):
        return False

    def has_delete_permission(self, request, obj=None):
        return False


class AuthorAdmin(admin.ModelAdmin):
    # the field on edition page
    # (xxx, yyy), will put xxx and yyy on the same line
    fields = (
        ('first_name', 'last_name'),
        ('created', 'modified')
    )
    # the not editable field
    readonly_fields = (
        'created',
        'modified'
    )
    # pagination control on the list
    list_per_page = 10
    # fields available for full text search
    search_fields = ('first_name', 'last_name')
    # name of the list column
    list_display = ('first_name', 'last_name')
    # inlines
    inlines = (BookInline,)


class BookAdmin(admin.ModelAdmin):
    # the field on edition page
    # (xxx, yyy), will put xxx and yyy on the same line
    fields = (
        ('title', 'isbn'),
        'author',
        'subject',
        'buy_date',
        ('created', 'modified')
    )
    # the not editable field
    readonly_fields = (
        'created',
        'modified'
    )
    # pagination control on the list
    list_per_page = 10
    # Extra date selector
    date_hierarchy = 'buy_date'
    # fields available for full text search
    search_fields = ('title', 'subject')
    # name of the list column
    list_display = ('title', 'subject', 'buy_date', 'author')
    # filter side bar in list page
    list_filter = ('subject',)

admin.site.register(Author, AuthorAdmin)
admin.site.register(Book, BookAdmin)

CHECK:

• Access http://127.0.0.1:8000/admin, connect and see the admin page

Install REST Framework (~5 min)

• Run pip install djangorestframework

• Save the dependencies to a lockfile: pip freeze > requirements.txt

• Add 'rest_framework' to your INSTALLED_APPS setting.

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'mab.library',
    'rest_framework'
]

• Add django rest framework urls, in urls.py (optional)

from django.conf.urls import url, include
urlpatterns = [
    ...
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    ...
]

Write your first rest API (~10 min)

• Create a file rest.py in the same folder as models.py

• Copy the following

from rest_framework import routers, serializers, viewsets
from .models import Book

# Serializers define the API representation.
class BookSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Book
        fields = ('title', 'subject', 'buy_date')

# ViewSets define the view behavior.
class BookViewSet(viewsets.ModelViewSet):
    queryset = Book.objects.all()
    serializer_class = BookSerializer

# Routers provide an easy way of automatically determining the URL conf.
router = routers.DefaultRouter()
router.register(r'books', BookViewSet)

• Add router urls, in urls.py

from django.conf.urls import url, include
from django.contrib import admin
from mab.library import rest

urlpatterns = [
    url(r'^', include(rest.router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    url(r'^admin/', admin.site.urls),
]

Next steps

• GraphQL with django
• Screencast of django
• Best Book ever for django
• Awesome Django

Troubleshooting

• Django documentation is well organized: https://docs.djangoproject.com/en/1.11/
• Beware, at least 1/3 of the article are not about Python and really NSFW. Sam et Max blog is really the best resource for python learning in French, especially django.
• Django has a strong community on Reddit and blogs