Django for ISchoolers: Difference between revisions

 

TODO: Actually write my own dang installation instructions.

 

Prior to starting this tutorial, please install Python, git, pip, virtualenv, Django, and South on your computer. There's instructions for all of those at [http://pystar.org/setup_machine.html http://pystar.org/setup_machine.html].

Once you've got pip and virtualenv installed, in your terminal, go into the folder you want to keep this tutorial code in and type (one line at a time):

 

$ virtualenv --no-site-packages django-tutorial-env

 

 

(django-tutorial-env)$ pip install south

 

This will make and activate a virtual python environment for just this tutorial app. While this is a bit overkill if you only have one Django app at a time on your system, giving each Python app you work on its own environment is a good best practices just in case e.g. you're working on multiple apps, which use different versions of Django or other libraries, and you don't want them to conflict with each other.

=== Activate your environment in your terminal ===

 

 

=== Set up your git repository ===

 

 

We'll be using the master branch (the default name for the main branch of code, which you're in right now) for syncing up throughout the class in case you get lost. You'll need to make your own branches for playing with the code on your computer, so that it doesn't interfere w. re-syncing later.

Think of branches in git as alternate timelines--you "branch" off of the main timeline of changes to the code into a separate timeline. You can try out a new feature or code setup in a branch, without overwriting or getting in the way of yourself or anybody else working on the code as-is. Sometimes a new idea doesn't work out, and you delete the branch or just let it sit around. Sometimes the new feature works, though, and if so you can merge it into the "real" timeline. You can make as many branches as you want, and branches of branches. You can even share branches with others (though we won't be doing that today). Git's branching system (and its non-centralized architecture generally) make it easy to try out new ideas in code without having to ask permission of everyone else on the project first.

 

 

 

=== Create your Django project ===

Let's create your first Django project, called "mysite".

 

 

You'll see we made a folder called "mysite", with some files in it. Let's check them out!

 

$ cd mysite

$ ls

settings.py

urls.py

 

These files are:

** Run the command:

 

 

** Review the output in your terminal. It should look similar to:

 

0 errors found.

 

Django version 1.2, using settings 'myproject.settings'

Development server is running at http://127.0.0.1:8000/

 

* Now that the server’s running, visit [http://127.0.0.1:8000/ http://127.0.0.1:8000/] with your Web browser. You’ll see a “Welcome to Django” page, in pleasant, light-blue pastel. It worked!

* Observe the logging that happens in the terminal where your server is running:

 

 

which has the format:

 

 

* Navigate to http://127.0.0.1:8000/some/url/. What changes in the terminal log?

Each commit is a checkpoint in time, containing the '''diff'''--the "difference", all of the changes you made to your code base -- between that commit and the commit before it. Different branches in git share the commits made prior to the branching-off point, then each have their own commit history.

 

 

# On branch my-chunk-1

#

# settings.py

# urls.py

 

"Untracked files" means that git has noticed some new files inside its folder, but you haven't told git explicitly that you want it to "listen" for, and track, changes in those files.

 

* Add all the files to the repo, in the local directory:

 

 

What does git status say now?

* git commit to commit those files:

 

# -m -> what is the 'message' for the commit

git commit -m "Initial commit of Django project from the IOLab Django workshop"

 

 

Huzzah! We committed our changes so far. Now let's make some more changes!

* git add and commit it:

 

# even though git knows to "listen" to settings.py now, it still won't add it to the 'staging area' for your commit unless you tell it to explicitly with git add

git add settings.py

git commit -m "made myself an admin"

 

===Set up the Database===

Keep looking at settings.py: The DATABASES variable is a dictionary (note the ‘{}’ characters) with one key: default.

 

DATABASES = {

'default': {

'PORT': '', # Set to empty string for default. Not used with sqlite3.

}

 

Notice that the value of default is itself another dictionary with information about the site’s default database.

* Set your app to use a sqlite database, in the ENGINE attribute. Sqlite is great for development because is stores its data in one normal file on your system and therefore is really simple to move around with your app. It's not sturdy enough to use for a website in production, though.

 

 

* Set your app to use a file called 'database.db' to store information for this project.

 

 

Does database.db exist right now? (No, but that's okay. It'll get created automatically when it's needed.)

* Add South to our list of installed apps. (We'll need it later.)

 

'django.contrib.auth',

'django.contrib.contenttypes',

# 'django.contrib.admindocs',

'south',

 

* Each of these applications makes use of at least one database table, so we need to create the tables in the database before we can use them. To do that, run the following command:

 

 

The syncdb command looks at the INSTALLED_APPS setting and creates any necessary database tables according to the database settings in your settings.py file. You’ll see a message for each database table it creates.

* Make scaffolding for the app:

 

 

That’ll create a directory qandabear to house our Q & A application.

* Verify what is new.

 

 

* Examine the layout of qandabear (we will do more of this in following sections).

 

$ ls qandabear

qandabear/

tests.py

views.py

 

* Install the Q&A app into the project. Edit the settings.py file again, and change the INSTALLED_APPS setting to include the string ‘qandabear’ as the last entry.

* Save and commit the settings.py file.

At the end of each 'chunk', I'm going to push our progress so far to the tutorial git repository. If you're doing this tutorial in class, please switch back to the master branch, then pull my changes.

 

 

This will make it so that everyone starts out each chunk with the same working code, so even if you get stuck or confused in one session, you can still keep up. (Since I don't have any TAs to help debug or answer questions, and we don't have that much time.)

Remember that *you* shouldn't be putting your modifications inside the master branch, though! (Otherwise, you'd have to overwrite them at the next chunk checkpoint, and that would be sad.) Instead, make a new branch for chunk 2 based off the master code you just downloaded, and let's get going!

 

 

<!-- == Test-driven development, part one ==

===Adding URLs to our urls.py===

 

 

* Write our URL mapping. Edit the file mysite/urls.py so it looks like this:

 

(r'^questions/$', 'qandabear.views.index'),

(r'^questions/(\d+)/$', 'qandabear.views.question'),

# Uncomment the next line to enable the admin:

# url(r'^admin/', include(admin.site.urls)),

 

# which regex pattern is tripped?

# what function is then called?

Review: When somebody requests a page from your Web site – say, “/questions/23/”, Django will load the urls.py Python module, because it’s pointed to by the ROOT_URLCONF setting. It finds the variable named urlpatterns and traverses the regular expressions in order. When it finds a regular expression that matches – r'^questions/(\d+)/$' – it loads the function question() from qandabear/views.py. Finally, it calls that module’s detail() function like so:

 

 

The ‘23’ part comes from (\d+). Using parentheses around a pattern “captures” the text matched by that pattern and sends it as an argument to the view function; the \d+ is a regular expression to match a sequence of digits (i.e., a number).

== views.py ==

 

* Fetch “http://127.0.0.1:8000/questions/” in your browser. You should get a pleasantly-colored error page with the following message:

 

 

Tried index in module qandabear.views. Error was: 'module'

 

 

 

>>> import qandabear.views # imports fine also!

>>> dir(qandabear.views) # what is in there!

>>> inspect.getsourcefile(qandabear.views)

# something like

 

So, a mystery? Where is the view!? It’s nowhere! The URL parsing is going fine, but there is no one listening at the other end of the phone! This ViewDoesNotExist error happened because you haven’t written a function index() in the module questions/views.py.

* Write some views. Open qandabear/views.py and put the following Python code in it:

 

 

def index(request):

 

This is a very simple view.

* Add a few more views by adding to the views.py file. These views are slightly different, because they take an argument or two (which, remember, is passed in from whatever was captured by the regular expression in the URLconf):

 

return HttpResponse("You're looking at question %s." % (question_id,))

 

def edit_answer(request, question_id, answer_id):

 

* Save views.py.

Edit the qandabear/models.py file so it looks like this:

 

 

class Question(models.Model):

question = models.ForeignKey(Question)

answer = models.TextField()

 

* Save the models.py file.

* On the command line, write:

 

 

As you can see, that’s created a migrations directory for us, and made a new migration inside it.

* All we need to do now is apply our new migration:

 

 

Great! Now our database file knows about qandabear and its new models, and if we need to change our models, South is set up to handle those changes. We’ll come back to South later.

 

 

* Add and commit all your work, including the migrations folder that South generated for you.

Now, let’s hop into the interactive Python shell and play around with the free API ("Application programming interface" -- APIs aren't just data doodads that hip web startups provide for you, they're an important concept in software architecture.) that Django gives you. To invoke the Python shell, use this command:

 

 

We’re using this instead of simply typing “python”, because manage.py sets up the project’s environment for you. “Setting up the environment” involves two things:

* Import the model classes we just wrote:

 

 

* List all the current Questions:

 

>>> Question.objects.all()

 

How many questions is this?

=== Add our first Question ===

 

>>> q = Question(text="What is the Weirdest Cookbook Ever?")

 

 

* Save the Question instance into the database. You have to call save() explicitly.

 

 

* Get the id of the Question instance. Because it’s been saved, it has an ID in the database now!

 

>>> q.id

 

* Access the database columns (Fields, in Django parlance) as Python attributes:

 

>>> q.text

"What is the Weirdest Cookbook Ever?"

>>> q.pub_date

datetime.datetime(2011, 12, 1, 3, 3, 55, 841929)

 

* Send the Question back in time:

 

>>> import datetime

>>> q.pub_date = datetime.datetime(2011, 4, 1, 0, 0)

>>> q.save()

>>> q.pub_date

 

* Ask Django to show a list of all the Question objects available:

 

 

===Fix The Hideous Default Representation===

Wait a minute! <Question: Question object> is an utterly unhelpful, truly wretched, beyond contemptable representation of this object. Let’s fix that by editing the Question model. Use your text editor to open the qandabear/models.py file and adding a __unicode__() method to both Question and Answer:

 

# ...

def __unicode__(self):

if len(self.text) > 37:

summary = summary + '...'

 

It’s important to add __unicode__() methods to your models, not only for your own sanity when dealing with the interactive prompt, but also because if you use Django's automatically-generated admin, these representations are used there too.

Enough of these normal python methods! Let's build in some useful functionality to our models in qandabear/models.py.

 

# ...

class Question(models.Model):

# ...

def was_published_today(self):

 

 

* Save these changes to the models.py file.

Start a new Python interactive shell by running python manage.py shell:

 

>>> from qandabear.models import Question, Answer

Verify our __unicode__() addition worked:

>>> questions[0].id # remember python lists start with element 0.

1

 

If you try to search for a question that does not exist, filter will give you the empty list. The get method will always return one hit, or raise an exception.

 

>>> Question.objects.filter(text="Who framed Roger Rabbit?")

[]

...

DoesNotExist: Question matching query does not exist.

 

 

Observe: there is a Question in the database, but it has no Answers! Let's fix that.

 

>>> q = Question.objects.get(id=1)

>>> q.answer_set.all()

>>> a

<Answer: Mini-Mart A La Carte>

 

Go in reverse! Find the question a particular answer belongs to:

 

>>> a.question

<Question: What is the Weirdest Cookbook Ever?>

 

Because a Question can have more than one Answer, Django creates the answer_set attribute on each Question. You can use that to look at the list of available Answer, or to create them.

 

>>> q.answer_set.all()

[<Answer: To Serve Man>, <Answer: The Original Road Kill Cookbook>, <Answer: Mini-Mart A La Carte>]

>>> q.answer_set.count()

3

 

Can one be a Answer for a Question that doesn’t yet exist?:

 

>>> koan.question_id

>>> koan.question

 

 

=== Changing your models ===

 

 

 

class Answer(models.Model):

question = models.ForeignKey(Question)

votes = models.IntegerField(default=0)

pub_date = models.DateTimeField(auto_now_add=True)

 

The default parameter lets us set a default value for this field if an answer's vote count isn't explicitly specified. Most new answers are going to have zero votes, so we set our default to 0.

 

 

$ python manage.py schemamigration qandabear --auto

 

* Apply the migration.

 

$ python manage.py migrate qandabear

Running migrations for qandabear:

- Loading initial data for qandabear.

No fixtures found.

 

Success!

 

You know the drill!

 

<!--

 

== Views with actual data ==

 

= Chunk 4 =

 

== Django templates 101 ==

 

 

 

= Bonus points =

 

== Static files (aka: Django for designers) ==

 

== AJAX and Django ==

 

== Test-driven development, part two ==

 

 

== Authentication and Users (and reusing apps) ==

 

== Deploying to a real live server ==