From 2052b508eb92c62fc0678efd4936c5ec1e0e735b Mon Sep 17 00:00:00 2001 From: Justin Bronn Date: Sun, 26 Aug 2007 01:10:53 +0000 Subject: gis: Made necessary modifications for unicode, manage refactor, backend refactor and merged 5584-6000 via svnmerge from [repos:django/trunk trunk]. git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@6018 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/tutorial01.txt | 69 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 43 insertions(+), 26 deletions(-) (limited to 'docs/tutorial01.txt') diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt index fdac9c554e..cf2b76e9be 100644 --- a/docs/tutorial01.txt +++ b/docs/tutorial01.txt @@ -22,10 +22,10 @@ installed. .. admonition:: Where to get help: If you're having trouble going through this tutorial, please post a message - to `django-users`_ or drop by `#django`_ on ``irc.freenode.net`` and we'll + to `django-users`_ or drop by `#django`_ on ``irc.freenode.net`` and we'll try to help. -.. _django-users: http://groups.google.com/group/django-users +.. _django-users: http://groups.google.com/group/django-users .. _#django: irc://irc.freenode.net/django Creating a project @@ -42,7 +42,7 @@ code, then run the command ``django-admin.py startproject mysite``. This will create a ``mysite`` directory in your current directory. .. note:: - + You'll need to avoid naming projects after built-in Python or Django components. In particular, this means you should avoid using names like ``django`` (which will conflict with Django itself) or ``site`` (which @@ -251,12 +251,12 @@ These concepts are represented by simple Python classes. Edit the from django.db import models class Poll(models.Model): - question = models.CharField(maxlength=200) + question = models.CharField(max_length=200) pub_date = models.DateTimeField('date published') class Choice(models.Model): poll = models.ForeignKey(Poll) - choice = models.CharField(maxlength=200) + choice = models.CharField(max_length=200) votes = models.IntegerField() The code is straightforward. Each model is represented by a class that @@ -279,7 +279,7 @@ name for ``Poll.pub_date``. For all other fields in this model, the field's machine-readable name will suffice as its human-readable name. Some ``Field`` classes have required elements. ``CharField``, for example, -requires that you give it a ``maxlength``. That's used not only in the database +requires that you give it a ``max_length``. That's used not only in the database schema, but in validation, as we'll soon see. Finally, note a relationship is defined, using ``models.ForeignKey``. That tells @@ -321,7 +321,7 @@ Now Django knows ``mysite`` includes the ``polls`` app. Let's run another comman python manage.py sql polls -You should see something similar to the following (the CREATE TABLE SQL statements +You should see something similar to the following (the CREATE TABLE SQL statements for the polls app):: BEGIN; @@ -341,7 +341,7 @@ for the polls app):: Note the following: * The exact output will vary depending on the database you are using. - + * Table names are automatically generated by combining the name of the app (``polls``) and the lowercase name of the model -- ``poll`` and ``choice``. (You can override this behavior.) @@ -371,8 +371,8 @@ If you're interested, also run the following commands: construction of your models. * ``python manage.py sqlcustom polls`` -- Outputs any custom SQL statements - (such as table modifications or constraints) that are defined for the - application. + (such as table modifications or constraints) that are defined for the + application. * ``python manage.py sqlclear polls`` -- Outputs the necessary ``DROP TABLE`` statements for this app, according to which tables already exist @@ -444,8 +444,8 @@ Once you're in the shell, explore the database API:: [] # Create a new Poll. - >>> from datetime import datetime - >>> p = Poll(question="What's up?", pub_date=datetime.now()) + >>> import datetime + >>> p = Poll(question="What's up?", pub_date=datetime.datetime.now()) # Save the object into the database. You have to call save() explicitly. >>> p.save() @@ -461,10 +461,10 @@ Once you're in the shell, explore the database API:: >>> p.question "What's up?" >>> p.pub_date - datetime.datetime(2005, 7, 15, 12, 00, 53) + datetime.datetime(2007, 7, 15, 12, 00, 53) # Change values by changing the attributes, then calling save(). - >>> p.pub_date = datetime(2005, 4, 1, 0, 0) + >>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0) >>> p.save() # objects.all() displays all the polls in the database. @@ -474,22 +474,39 @@ Once you're in the shell, explore the database API:: Wait a minute. ```` is, utterly, an unhelpful representation of this object. Let's fix that by editing the polls model (in -the ``polls/models.py`` file) and adding a ``__str__()`` method to both +the ``polls/models.py`` file) and adding a ``__unicode__()`` method to both ``Poll`` and ``Choice``:: class Poll(models.Model): # ... - def __str__(self): + def __unicode__(self): return self.question class Choice(models.Model): # ... - def __str__(self): + def __unicode__(self): return self.choice -It's important to add ``__str__()`` methods to your models, not only for your -own sanity when dealing with the interactive prompt, but also because objects' -representations are used throughout Django's automatically-generated admin. +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 +objects' representations are used throughout Django's automatically-generated +admin. + +.. admonition:: Why ``__unicode__()`` and not ``__str__()``? + + If you're familiar with Python, you might be in the habit of adding + ``__str__()`` methods to your classes, not ``__unicode__()`` methods. + We use ``__unicode__()`` here because Django models deal with Unicode by + default. All data stored in your database is converted to Unicode when it's + returned. + + Django models have a default ``__str__()`` method that calls + ``__unicode__()`` and converts the result to a UTF-8 bytestring. This means + that ``unicode(p)`` will return a Unicode string, and ``str(p)`` will return + a normal string, with characters encoded as UTF-8. + + If all of this is jibberish to you, just remember to add ``__unicode__()`` + methods to your models. With any luck, things should Just Work for you. Note these are normal Python methods. Let's add a custom method, just for demonstration:: @@ -509,7 +526,7 @@ Let's jump back into the Python interactive shell by running >>> from mysite.polls.models import Poll, Choice - # Make sure our __str__() addition worked. + # Make sure our __unicode__() addition worked. >>> Poll.objects.all() [] @@ -520,9 +537,9 @@ Let's jump back into the Python interactive shell by running >>> Poll.objects.filter(question__startswith='What') [] - # Get the poll whose year is 2005. Of course, if you're going through this + # Get the poll whose year is 2007. Of course, if you're going through this # tutorial in another year, change as appropriate. - >>> Poll.objects.get(pub_date__year=2005) + >>> Poll.objects.get(pub_date__year=2007) >>> Poll.objects.get(id=2) @@ -563,9 +580,9 @@ Let's jump back into the Python interactive shell by running # The API automatically follows relationships as far as you need. # Use double underscores to separate relationships. - # This works as many levels deep as you want. There's no limit. - # Find all Choices for any poll whose pub_date is in 2005. - >>> Choice.objects.filter(poll__pub_date__year=2005) + # This works as many levels deep as you want; there's no limit. + # Find all Choices for any poll whose pub_date is in 2007. + >>> Choice.objects.filter(poll__pub_date__year=2007) [, , ] # Let's delete one of the choices. Use delete() for that. -- cgit v1.3