Django Tutorial: Getting Started with Django

You’ll want a programming text editor. If you have an editor preference feel free to stick with it but if you haven’t used a programming editor before I recommend trying out PyCharm Community Edition which is the best free IDE for Django development. See here for the download. If you’d like a lighter-weight tool I recommend Sublime Text as a good coding editor.

NOTE

If you already have a $EDITOR you love you can just keep using what you’re used to.

I always use IPython – the improved interactive Python shell – whenever I can. The Django framework evidently shares my fondness for IPython – if you install it Django will automatically use it as the Python shell of choice.

If you want to use it as well you can pip install ipython. Don’t worry if this doesn’t work for you however – it isn’t necessary to complete this tutorial.

This tutorial is not long enough to teach git. But if you already know about git I encourage you to use git to track your changes. My completed source code is available and any fixes for bugs in the sample code will be published there.

So what can we do so far?

Because Django is a web framework you have to run an HTTP server to see your work in progress. Fortunately Django comes with a development HTTP server – it shouldn’t be used in production for various performance and security reasons but you can use it while working on your project.

You start the development HTTP server with the manage.py script.

Open http://127.0.0.1:8000/ in your browser of choice.

The manage.py utility gets used a lot – to start utilities like the server and to generate code. You’ll want to keep a terminal window open in the project directory to have convenient access to the manage.py utility.

TIP

You’re going to always want to keep a separate terminal window open just to keep the runserver command running.

The first step in creating most Django apps is modeling your data. Models, I’m sure you will be suprised to know, go inmodels.py. The startapp command helped us out by generating the file

That’s a helpful comment - but we’re responsible for creating our models. Let’s add a little code and define just whatmodels mean in Django. Put this code in your models.py:

In Django models are Python classes which extend django.db.models.Model. If you aren’t used to object oriented programming in Python this may sound scary (and if you are experienced it may occur to you that this is a pretty strange class!)

Not to worry – Django uses class definitions as a DSL (Domain Specific Language) for configuring various parts of the framework and classes like this will soon become a familiar sight.

A models.Model class roughly corresponds to a table in a database. Django can figure out from our Book class how to create a book table in our database. Each of the class attributes like title and isbn will become columns in the booktable with the type taken from the Field class.

NOTE

Django defines a rich set of classes that represent various kinds of database columns. See here for the complete list.

We’ve got tables, let’s create some data! The model classes that we create not only define the tables in the database but also provide an convenient Pythonic API for accessing data in the tables. This API is referred to as Django’s ORM, or Object Relational Mapper. This API makes it easy to run simple queries even if you aren’t familiar with SQL, the underlying language that relational databases speak.

We’ll write code using the ORM later but we can start out exploring it interactively. To get a Python shell that has oursettings loaded and access to all our code we can use the shell command from the manage.py utility.

I’ve got IPython installed so Django uses it when I run the shell command. Don’t panic if you just see the standard Python prompt with >>> – just type the code to the right of the colon to follow along.

On line 1 I import our model class and on line 2 I’m creating an instance of it. Model classes can be called with keyword arguments that match the column names. We can also assign to the attributes of the Book instance but its important to save the right kind of data. Because read_on was a DateTimeField I need to be sure to give it a Python datetime object which I can get from the datetime module. Still in the shell:

On line 5 I call the .save() method. This method actually talks to the database for us and runs an SQL INSERT statement that puts our data into the book table. Interestingly on line 6 you can see that our book instance now has a new property, one we didn’t explicitly define on our Book model class. (The Out[6] is the output from line 6 – you don’t need to type this.)

Django’s default behavior is to add a PRIMARY KEY column to our table named id. This attribute is unset on the object before we called the save() method as our data isn’t yet in the database. Afterwards it shows us the unique id of this record in the book table.

NOTE

Don’t worry if you use IPython and see a RuntimeWarning about the datetime – this isn’t really a bug and has been fixed in the development version of Django

We can check to see if our data actually got into the database by using the Querying API. Each model subclass has a.objects attribute with query methods like .all() and .filter().

If you know SQL the .all() method issues a SELECT * from book query while the .filter() method adds a WHEREclause to the query. The results of most query methods are an iterable of model instances:

It’s important to realize that most model methods return a QuerySet object. It may look like a list in the console but its really just an SQL statement until it’s evaluated. We can peek at the .query property to see this:

Even if you know SQL line 9 is a lot nicer to write than the query output on line 10! We can make a new query by calling additional query methods on a queryset:

You can use the order_by() method to modify the order of the records – or you could call filter() again to make a more complicated query.

TIP

You can also use the dbshell management command to open up your database CLI connected to the database in your settings for adhoc querying in SQL. (This is very convenient when using a remote database server like MySQL.) This still works with our sqlite database file but you have to have thesqlite command line utility installed. You can download precompiled sqlite-shell binaries for your platform here.

You can use the developer tools in a browser like Google’s Chrome to inspect the underlying conversation that is going on when the browser requests a page from a server. The browser sends formatted text that contains information about the request:

The response looks similar – an HTTP response has an initial line with a status code, some header lines, and the actual content of the response. Parsing the request and generating the response would be a little tricky!

By default Django will load templates from a directory named templates in your app. Later on we might want to customize settings.TEMPLATES but for now let’s just make make a directory in our books app.

We’ll start with a simple Hello World template. Create a new file with your text editor in the books/templates directory called index.html and add the following contents:

We have one last thing to do in order to run our view and see our template in the browser.

When an HTTP request comes in from the client Django consults its url routing table to decide which view should handle the request and return a response to the client.

We need to give Django a url that routes to our view. URLs are stored (you guessed it) in urls.py. Individual applications can have urls.py but by default there is one global urls.py created in the project configuration directory next to thesettings.py file. There is a long docstring at the top of this file that I’m leaving out but currently it looks like this:

urlpatterns is a list of mappings from URLs represented as regular expressions, or regex, to a particular view or another url configuration file. That is what is happening on line 5 which basically says that if an incoming URL starts withadmin/ the rest of the URL will be handed off to the admin app’s URL for routing.

Don’t worry if this part of Django looks a little complicated. Writing (and reading) regex can be tricky even if you have experience with them. Fortunately mostly here we can just copy existing examples.

Let’s route the front page of our web app to the view we just wrote. Let me show you how to modify the urls and then I’ll explain the code:

On line 4 we have to import the view we want.

On line 8 we added the new the rule. The pattern for an empty url is ^$ (the start of the string and end of string regex symbols with nothing between them) and the url function maps our pattern r'^$' to our view index.

Did it work? Reload your browser pointed at http://localhost:8000/

I know this isn’t very impressive yet – so lets put some data in our template. Edit your views.py to match mine:

On line 2 we need to import or model class and we can use Python’s relative import syntax to refer to the models.pymodule sitting right beside us.

On line 5 in our index view we add an ORM query to get all the books from the database and on line 6 we pass this data to the template using the context argument to the render shortcut. The dict of data we pass to render will be made available in our template.

And now we can edit our template to make it a little more interesting. Django templates aren’t limited to HTML – they can also include a language for adding output and logic. There’s a bit to learn here but fortunately it looks a lot like Python. Edit your index.html to match mine and I’ll explain:

On line 3 we’re starting an Unordered List with the <ul> tag. The {% and %} delimit what Django calls a template tag. Django comes with many built in tags that resemble Python syntax and you can learn to create your own custom tags as well. In this case the tag is a for loop, looping over the books variable just like you would in Python.

Because HTML isn’t very friendly to indentation delimited blocks the {% for %} tag has a matching {% endfor %} tag and you’ll find this is a common pattern. (As you might expect there’s also an {% if %} tag that looks a lot like Python’sif statement.)

For each book in books we create a List Item with the <li> tag containing the book title. The consecutive curly brace syntax {{ book.title }} is the template language’s equivalent of the print function in Python.

One last thing – the template language was designed to be as easy as possible to use so some syntactic limitations of Python are relaxed in the template language. Attributes that point to methods will automatically be called (no parens necessary) and both dictionary keys and list indexes can be addressed with dot syntax (some_list.0 isn’t valid Python but it’s fine in the template).

TIP

A lot of your early learning will involve mastering the Django template language. Just go ahead and bookmark this page.

Try reloading the front page!

Since we haven’t set up the admin on our models yet the only options available are Groups and Users. Let’s get our Bookmodel registered with the admin.

To do so we’ll edit our app’s admin.py (you may be noticing a trend with Django: a place for everything and everything in its place. It’s kind of nice once you’re used to it!)

As usual the startapp management command generated a skeleton file for us:

Let’s replace that helpful comment. The Django admin can be heavily customized (we’ll do a little customization in a minute) but you can also just import your models and register them. Let’s do that first! Edit your admin.py to look like this:

On line 3 we add the import of our model and on line 5 we register it with the admin.

Go ahead and reload your browser at the admin url http://localhost:8000/admin/

If all has gone well you should see a new Books section. Below it is a Books link with an Add and Change link beside it.

The admin interface is an automatically generated CRUD (Create/Read/Update/Delete) interface. We can use it to search and browse records, to edit or delete existing records, and to create new ones. Let’s try creating a new Book. Click on theAdd link – it should direct you to http://localhost:8000/admin/books/book/add/ which looks like this:

Yes I’m adding another book – you should too! The admin presents sensible widgets based on our model field types and includes some basic validation (try leaving a field blank and hitting Save).

When you’ve successfully saved a book you’ll be taken to the list view that shows all the records. Unfortunately it doesn’t look very good right now as each entry just says “Book object”.

Next we need to create a project wide base.html template. So far we’ve relied on the templates directory we made in our app. Now make a project-level templates directory. It should sit next to your app folder.

We’ll need to add this location to the settings.TEMPLATES setting. The only line you need to change is the DIRSdirective on line 4 in the snippet below. It should look like this:

Now we can add a new template. Create a file base.html in your project level templates directory. Copy the following source into this file and I’ll explain the new concept it introduces.

Most of this is just HTML boilerplate needed to have an HTML5 page suitable for Bootstrap. The bootstrap3 app doesn’t provide any models or views – it just gives us template tags to add the css/javascript resources in our page.

What is interesting is the new {% block %} template tag we’re using. This allows us to take advantage of template inheritance to organize our html.

We don’t want to add the HTML boilerplate to every template we create. It is better to have a base.html template that can be reused by multiple templates in multiple apps. But how can our existing index.html template use this template?

The answer is template inheritance. By defining a block in both templates and having the index.html extend thebase.html template we can get the surrounding content from the base.html when we render the index.htmltemplate.

It’s important to note that only content in the child template which is in a block of the same name in the parent template will show up on the page. (If you ever wonder why stuff you put in your template just doesn’t show up – make sure you have your block names all lined up!)

Let’s edit the index template to extend the base template. Change your index.html template to look like this:

The new additions are the extends tag which must be at the top of the template and establishes the relationship between index.html and base.html. I also added a {% block content %} around the html so that it shows up in the base template. Finally I added a few bootstrap-specific classes to dress up our header and list a little bit. Reload your front page – it should look a little better!

Because there are multiple places to look for a template (each app/templates directory + the top level project templates directory) it is a good practice to always use the app name when loading app templates. We should move our index.html file one level deeper into a new directory books/templates/books. Then our view could pass to render the path books/index.html template and it wouldn’t run the risk of picking up an index.html defined in some other Django app.

TIP

You’ll want to install django-debug-toolbar. This invaluable tool lets you tell during development what templates were used to render the page. It can also tell you about database queries, total server-side rendering time and more.

Let’s add a field to the Book model

Whenever we make changes to our models we need to make sure the database is updated. Remember – we do that by creating a migration script and running it.

Let’s add a detail view for our book review. But what should the URL be?

Django allows us to put a variables in the url to allow for dynamic urls. We can add an additional url to our urls.py and point it to a new view that accepts an argument.

The pattern inside the parentheses in the new regex captures any sequence of digits followed by a trailing slash. The parentheses around this pattern creates a regex group. The new view we create must accept a positional argument and the group contents will be passed to it. Despite the fact that we know it will be digits, this value will be passed as a string.

TIP

Python supports named groups in regexes and you can use these names to pass named arguments in your view. See here for more sophisticated ways of doing things.

Our new view in views.py might look like:

I’m using an additional shortcut function that does a query and raises an Http404 exception if it can’t find the matching item. The django.shortcuts module is full of useful tidbits like this.

And finally we need a new template. The detail template might look like this:

I’m using Bootstrap breadcrumb navigation in the header here and I’ll add matching html to the index as well. The tag that displays the book.notes value uses what Django calls a template filter to show a default message if .notes is not yet filled in. Template filters are handy for many html/string sorts of tasks.

TIP

You’ll want to get acquainted with the built in template tags and filters. See here.

I’m also building a link to Amazon to buy any books I really enjoyed. The link will should work if you use the tradional 10-digit ISBN numbers.

My index template got a few improvements as well:

Mainly I’ve added the breadcrumb navigation for consistency. I also wrapped the book titles in a link to the detail page for the book. The url as we’ve defined it looks like /{{ book.id }}/. This isn’t the ideal way to specify urls – eventually you’ll learn to use model methods to provide consistent urls without repetition.

NOTE

In the interests of simplicity I’m doing some things wrong. Django has great facilities for naming urls, specifying prefixes, grouping them by app, internationalizing the URL and dynamically looking up the url pattern in the template with the {% url %} tag. It’s a lot but eventually you’ll want to read the url documentation carefully.

Your detail page ought to look something like this:

If you transferred your Django project code to another server you still wouldn’t be able to run it unless you also remembered to pip install all of the requirements for our project. Do you remember all the packages we’ve installed in our venv?

Fortunately you don’t have to – pip remembers! Run the following command in your console with your venv activated from your project folder. You should end up with a requirements.txt file next to your manage.py.

This file contains the list of packages we’ve installed with their version numbers. Open it up and inspect it in your editor – it should look like this:

We can recreate our dependencies on the server by creating a new virtual environment and using pip to install from our requirements file. For the moment let’s just leave the requirements.txt file there.

TIP

If you’re pushing your project to Github it is convention to check your requirements.txt file in as well to document your dependencies.

So far we haven’t talked about the problem of static files. Static files are the resources (javascript, css, images, etc) that are needed to render your pages.

Our main site is actually avoiding this problem completely by loading Bootstrap design resources from a 3rdparty url – a CDN or Content Delivery Network – instead of serving the files directly.

However the admin app does have static resources associated with it – and they seem to be showing up fine! How does this work so far?

When Django is in development mode (settings.DEBUG = True) Django will serve static resources. It finds these files in an app-level static directory – just like it automatically loads templates from an app level template directory. The settings.STATIC_URL controls the URL prefix for these files. It is currently set to /static/ so if your browser asks for the url /static/example.txt Django would look in each installed app’s static folder and when it finds a file called example.txt it serves it up.

This is very convenient during development – but it’s kind of expensive and not how we actually want to serve files. A better way would be to put all the files in a single directory and let a real web server serve them.

Fortunately Django comes with tools to help us do exactly that. Our settings file needs a new directive STATIC_ROOT – let’s add it after the existing STATIC_URL directive at the bottom of your settings.py:

This calculates the path to a static directory that sits along side our project folder. Lets go ahead and create this directory.

We can now run a management command to find all the static files included in our installed apps and copy them to to this folder.

As you can see the collectstatic command finds many static files (all from the admin app) and copies them to theSTATIC_ROOT folder. We don’t need to do that while doing development work – but we will need to do this when we deploy.

It would be best to keep our code in git, set up a github account, and use git clone to transfer our code. Feel free to do that if you already know how!

If you haven’t used git before – well one skill at a time. We’ll just zip up our code and transfer it over via the web interface to the files in our dashboard.

We want a zip archive of the entire project directory. Feel free to right-click on the project folder and select Compress from the pop-up menu to do it the easy way. Or from the console if you have the zip command available run:

Now upload this file to your PythonAnywhere account. Click on the Files tab and then the Choose File button near the bottom of the page. Browse to the zip file you just made and upload it.

Now click on the Consoles tab in your PythonAnywhere account and then click on the bash link. This opens up a “bash console” in your home directory on the remote server. Of course it’s really running in your browser and is really just a very slick web app! Click on the shell and unzip the file from your remote command line:

Now we need to re-create our virtual environment with its dependencies. The commands are slightly different on the server (which supports multiple Python versions) but it results in the same basic environment – a virtual env with our requirements installed.

We also need a static directory with the static files collected – this looks just like it did on our development box.

Now click on the Web tab (you can always hit the PythonAnywhere logo to get back to your dashboard) and hit the Add a new web app link on the left. The wizard will inform you that your domain name will be yourname.pythonanywhere.com. In my case my username is simeonfranklin. Click the next button and select Manual configuration link (do not click the Django option!) and select Python 3.4 on the next screen and hit the Next button one more time.

Whew – that was a lot of button clicking but now we’re almost there. We just need to configure the the virtual environment, the wsgi file, and the static files.

Click on the Virtualenv section and type the path to the virtual env. For me that looks like/home/simeonfranklin/DJANGO – you’ll need to substitute your own username.

Be sure to click the check mark to save your entry.

We need to do the same process for the Static files section – entering /static/ for the URL and/home/simeonfranklin/static for the directory. This will allow the files we gathered with collectstatic to be served by PythonAnywhere’s HTTP server.

Finally we have to configure the wsgi file. Pronounced whiskey (at least when I pronounce it!) this is a protocol that allows us to embed an application in an HTTP server. Unfortunately we can’t just point at the wsgi file that was generated in our project.

Instead click on the WSGI configuration file link in the Code section. Delete all the code in the editor that loads and paste the following code in:

Hit the Save button, click back to the dashboard, click on the Web tab, and hit the big green Reload Button. A lot of button clicks I know – but hopefully you can now visit your domain and see success!