Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 512 lines (383 sloc) 22.919 kb
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
1 ==========================
2 Chapter 2: Getting Started
3 ==========================
4
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
5 Installing Django is a multi-step process, due to the multiple moving parts in
6 modern Web development environments. In this chapter, we'll walk you through
7 how to install the framework and its few dependencies.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
8
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
9 Because Django is "just" Python code, it runs anywhere Python does -- including
10 on some cell phones! But this chapter just covers the common scenarios for
11 Django installations. We'll assume you're installing it either on a
12 desktop/laptop machine or a server.
13
14 Later, in Chapter 12, we'll cover how to deploy Django to a production site.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
15
16 Installing Python
17 =================
18
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
19 Django itself is written purely in Python, so the first step in installing the
20 framework is to make sure you have Python installed.
21
22 Python Versions
23 ---------------
24
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
25 The core Django framework (version 1.4+) works with any Python version from 2.5
26 to 2.7, inclusive. Django's optional GIS (Geographic Information Systems)
27 support requires Python 2.5 to 2.7.
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
28
29 If you're not sure which version of Python to install and you have complete
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
30 freedom over the decision, pick the latest one in the 2.x series: version 2.7.
31 Although Django works equally well with any version from 2.5 to 2.7, the later
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
32 versions of Python have performance improvements and additional language
33 features you might like to use in your applications. Plus, certain third-party
34 Django add-ons that you might want to use might require a version newer than
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
35 Python 2.5, so using a later version of Python keeps your options open.
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
36
37 .. admonition:: Django and Python 3.0
38
0eb88e3 Michael Daugherty Update note about python 3.0 to say that Django 1.5 will support it. No...
mpdaugherty authored
39 At the time of writing, Python 3.0 had been released, but Django only
40 supported it experimentally. Python 3.0 introduced a substantial number of
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
41 backwards-incompatible changes to the language itself, and, as a result,
0eb88e3 Michael Daugherty Update note about python 3.0 to say that Django 1.5 will support it. No...
mpdaugherty authored
42 many major Python libraries and frameworks, including Django, had not yet
3955a30 Michael Daugherty Django is now at 1.4.2
mpdaugherty authored
43 caught up. Python 3.0 support is expected in Django version 1.5 at the
44 earliest.
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
45
46 Installation
47 ------------
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
48
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
49 If you're on Linux or Mac OS X, you probably have Python already installed.
50 Type ``python`` at a command prompt (or in Applications/Utilities/Terminal, in
51 OS X). If you see something like this, then Python is installed::
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
52
53 Python 2.7.3rc2 (default, Apr 22 2012, 22:30:17)
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
54 [GCC 4.6.3] on linux2
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
55 Type "help", "copyright", "credits" or "license" for more information.
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
56 >>>
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
57
58 Otherwise, you'll need to download and install Python. It's fast and easy, and
59 detailed instructions are available at http://www.python.org/download/
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
60
61 Installing Django
62 =================
63
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
64 At any given time, two distinct versions of Django are available to you: the
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
65 latest official release and the bleeding-edge development version. The version you
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
66 decide to install depends on your priorities. Do you want a stable and tested
67 version of Django, or do you want a version containing the latest features,
68 perhaps so you can contribute to Django itself, at the expense of stability?
69
70 We'd recommend sticking with an official release, but it's important to know
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
71 that the development version exists, because you'll find it mentioned
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
72 in the documentation and by members of the community.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
73
74 Installing an Official Release
75 ------------------------------
76
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
77 Official releases have a version number, such as 1.4.1 or 1.4, and the latest
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
78 one is always available at http://www.djangoproject.com/download/.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
79
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
80 If you're on a Linux distribution that includes a package of Django, it's a
81 good idea to use the distributor's version. That way, you'll get security
82 updates along with the rest of your system packages.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
83
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
84 If you don't have access to a prepackaged version, you can download and install
85 the framework manually. To do so, first download the tarball, which will be
3955a30 Michael Daugherty Django is now at 1.4.2
mpdaugherty authored
86 named something like ``Django-1.4.2.tar.gz``. (It doesn't matter which
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
87 local directory you download this file into; the installation process will put
88 Django's files in the right place.) Then, unzip it and run ``setup.py install``,
89 as you do with most Python libraries.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
90
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
91 Here's how that process looks on Unix systems:
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
92
3955a30 Michael Daugherty Django is now at 1.4.2
mpdaugherty authored
93 #. ``tar xzvf Django-1.4.2.tar.gz``
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
94 #. ``cd Django-*``
95 #. ``sudo python setup.py install``
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
96
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
97 On Windows, we recommend using 7-Zip (http://www.djangoproject.com/r/7zip/)
98 to unzip ``.tar.gz`` files. Once you've unzipped the file, start up a DOS
99 shell (the "Command Prompt") with administrator privileges and run the
100 following command from within the directory whose name starts with ``Django-``::
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
101
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
102 python setup.py install
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
103
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
104 In case you're curious: Django's files will be installed into your Python
105 installation's ``site-packages`` directory -- a directory where Python looks
106 for third-party libraries. Usually it's in a place like
af89ea2 Michael Daugherty Update example to reference python 2.7, not 2.4
mpdaugherty authored
107 ``/usr/lib/python2.7/site-packages``.
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
108
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
109 Installing the "Development" Version
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
110 ------------------------------
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
111
961fcf7 Michael Daugherty Remove references to "trunk" and replace them with "development version"...
mpdaugherty authored
112 Django uses Git (http://git-scm.com) for its source control. The latest and
113 greatest Django development version available from Django's official Git
114 repository (https://github.com/django/django). You should consider installing
115 this version if you want to work on the bleeding edge, or if you want to
116 contribute code to Django itself.
117
118 Git is a free, open source distributed revision-control system, and the Django
119 team uses it to manage changes to the Django codebase. You can download and
120 install Git from http://git-scm.com/download but it is easier to install with
121 your operating system's package manager. You can use Git to grab the very latest
122 Django source code and, at any given time, you can update your local version of
123 the Django code to get the latest changes and improvements made by Django
124 developers.
125
126 When using the development version, keep in mind there's no guarantee things
127 won't be broken at any given moment. With that said, though, some members of the
128 Django team run production sites on the development version, so they have an
129 incentive to keep it stable.
130
131 To grab the latest Django development version, follow these steps:
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
132
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
133 #. Make sure you have Git installed. You can get the
134 software free from http://git-scm.com/, and you can find
135 excellent documentation at http://git-scm.com/documentation.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
136
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
137 #. Clone the repository using the command ``git clone https://github.com/django/django djmaster``
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
138
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
139 #. Locate your Python installation's ``site-packages`` directory. Usually
b3b4bd3 Michael Daugherty Update another 2.4=>2.7. Remove sentence that does not make sense with ...
mpdaugherty authored
140 it's in a place like ``/usr/lib/python2.7/site-packages``. If you have
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
141 no idea, type this command from a command prompt::
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
142
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
143 python -c 'import sys, pprint; pprint.pprint(sys.path)'
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
144
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
145 The resulting output should include your ``site-packages`` directory.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
146
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
147 # Within the ``site-packages`` directory, create a file called
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
148 ``djmaster.pth`` and edit it to contain the full path to your ``djmaster``
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
149 directory to it. For example, the file could just contain this line::
150
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
151 /path/to/djmaster
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
152
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
153 #. Place ``djmaster/django/bin`` on your system PATH. This directory
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
154 includes management utilities such as ``django-admin.py``.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
155
156 .. admonition:: Tip:
157
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
158 If ``.pth`` files are new to you, you can learn more about them at
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
159 http://www.djangoproject.com/r/python/site-module/.
160
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
161 After downloading from Git and following the preceding steps, there's no
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
162 need to run ``python setup.py install``-- you've just done the work by hand!
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
163
961fcf7 Michael Daugherty Remove references to "trunk" and replace them with "development version"...
mpdaugherty authored
164 Because the Django development version changes often with bug fixes and feature
165 additions, you'll probably want to update it every once in a while. To update
166 the code, just run the command ``git pull origin master`` from within the
167 ``djmaster`` directory. When you run that command, Git will contact
168 https://github.com/django/django, determine whether any of Django's code has
169 changed, and update your local version of the code with any changes that have
170 been made since you last updated. It's quite slick.
171
172 Finally, if you use Django development version, you should know how to figure
173 out which version of Django you're running. Knowing your version number is
174 important if you ever need to reach out to the community for help, or if you
175 submit improvements to the framework. In these cases, you should tell people the
9d1ad69 Michael Daugherty This paragraph sounded like it was still talking about SVN, so I used th...
mpdaugherty authored
176 revision, also known as a "commit," that you're using. To find out your current
177 commit (the most recent commit is often called HEAD), type "git log -1" from
178 within the ``django`` directory, and look for the identifier after
179 "commit". This number changes each time Django is changed, whether through a bug
180 fix, feature addition, documentation improvement or anything else.
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
181
182 Testing the Django installation
183 ===============================
184
185 For some post-installation positive feedback, take a moment to test whether the
186 installation worked. In a command shell, change into another directory (e.g.,
187 *not* the directory that contains the ``django`` directory) and start the
188 Python interactive interpreter by typing ``python``. If the installation was
189 successful, you should be able to import the module ``django``:
190
191 >>> import django
192 >>> django.VERSION
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
193 (1, 4, 1, 'final', 0)
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
194
195 .. admonition:: Interactive Interpreter Examples
196
197 The Python interactive interpreter is a command-line program that lets you
198 write a Python program interactively. To start it, run the command
199 ``python`` at the command line.
200
201 Throughout this book, we feature example Python interactive interpreter
202 sessions. You can recognize these examples by the triple
203 greater-than signs (``>>>``), which designate the interpreter's prompt. If
204 you're copying examples from this book, don't copy those greater-than signs.
205
206 Multiline statements in the interactive interpreter are padded with three
207 dots (``...``). For example::
208
209 >>> print """This is a
210 ... string that spans
211 ... three lines."""
212 This is a
213 string that spans
214 three lines.
215 >>> def my_function(value):
216 ... print value
217 >>> my_function('hello')
218 hello
219
220 Those three dots at the start of the additional lines are inserted by the
221 Python shell -- they're not part of our input. We include them here to be
222 faithful to the actual output of the interpreter. If you copy our examples
223 to follow along, don't copy those dots.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
224
225 Setting Up a Database
226 =====================
227
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
228 At this point, you could very well begin writing a Web application with Django,
229 because Django's only hard-and-fast prerequisite is a working Python
230 installation. However, odds are you'll be developing a *database-driven* Web
231 site, in which case you'll need to configure a database server.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
232
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
233 If you just want to start playing with Django, skip ahead to the
234 "Starting a Project" section -- but keep in mind that all the examples in this
235 book assume you have a working database set up.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
236
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
237 Django supports four database engines:
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
238
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
239 * PostgreSQL (http://www.postgresql.org/)
240 * SQLite 3 (http://www.sqlite.org/)
241 * MySQL (http://www.mysql.com/)
242 * Oracle (http://www.oracle.com/)
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
243
244 For the most part, all the engines here work equally well with the core Django
245 framework. (A notable exception is Django's optional GIS support, which is much
246 more powerful with PostgreSQL than with other databases.) If you're not tied to
247 any legacy system and have the freedom to choose a database backend, we
248 recommend PostgreSQL, which achieves a fine balance between cost, features,
249 speed and stability.
250
251 Setting up the database is a two-step process:
252
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
253 * First, you'll need to install and configure the database server itself.
254 This process is beyond the scope of this book, but each of the four
255 database backends has rich documentation on its Web site. (If you're on
256 a shared hosting provider, odds are that they've set this up for you
257 already.)
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
258
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
259 * Second, you'll need to install the Python library for your particular
260 database backend. This is a third-party bit of code that allows Python to
261 interface with the database. We outline the specific, per-database
262 requirements in the following sections.
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
263
264 If you're just playing around with Django and don't want to install a database
265 server, consider using SQLite. SQLite is unique in the list of supported
266 databases in that it doesn't require either of the above steps, if you're using
267 Python 2.5 or higher. It merely reads and writes its data to a single file on
268 your filesystem, and Python versions 2.5 and higher include built-in support
269 for it.
270
271 On Windows, obtaining database driver binaries can be frustrating. If you're
42dcb3a Michael Daugherty Recommend python 2.7
mpdaugherty authored
272 eager to jump in, we recommend using Python 2.7 and its built-in support for
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
273 SQLite.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
274
275 Using Django with PostgreSQL
276 ----------------------------
277
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
278 If you're using PostgreSQL, you'll need to install either the ``psycopg`` or
279 ``psycopg2`` package from http://www.djangoproject.com/r/python-pgsql/. We
280 recommend ``psycopg2``, as it's newer, more actively developed and can be
281 easier to install. Either way, take note of whether you're using version 1 or
282 2; you'll need this information later.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
283
284 If you're using PostgreSQL on Windows, you can find precompiled binaries of
285 ``psycopg`` at http://www.djangoproject.com/r/python-pgsql/windows/.
286
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
287 If you're on Linux, check whether your distribution's package-management
288 system offers a package called "python-psycopg2", "psycopg2-python",
289 "python-postgresql" or something similar.
290
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
291 Using Django with SQLite 3
292 --------------------------
293
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
294 If you're using Python version 2.5 or higher, you're in luck: no
295 database-specific installation is required, because Python ships with SQLite
296 support. Skip ahead to the next section.
297
298 If you're working with Python 2.4 or older, you'll need SQLite 3 -- *not*
299 version 2 -- from http://www.djangoproject.com/r/sqlite/ and the ``pysqlite``
300 package from http://www.djangoproject.com/r/python-sqlite/. Make sure you have
301 ``pysqlite`` version 2.0.3 or higher.
302
303 On Windows, you can skip installing the former (the separate SQLite binaries),
304 because they're statically linked into the ``pysqlite`` binaries.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
305
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
306 If you're on Linux, check whether your distribution's package-management system
307 offers a package called "python-sqlite3", "sqlite-python", "pysqlite" or
308 something similar.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
309
310 Using Django with MySQL
311 -----------------------
312
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
313 Django requires MySQL 4.0 or above. The 3.x versions don't support nested
314 subqueries and some other fairly standard SQL statements.
315
316 You'll also need to install the ``MySQLdb`` package from
317 http://www.djangoproject.com/r/python-mysql/.
318
319 If you're on Linux, check whether your distribution's package-management system
320 offers a package called "python-mysql", "python-mysqldb", "mysql-python" or
321 something similar.
322
323 Using Django with Oracle
324 ------------------------
325
326 Django works with Oracle Database Server versions 9i and higher.
327
328 If you're using Oracle, you'll need to install the ``cx_Oracle`` library,
329 available at http://cx-oracle.sourceforge.net/. Use version 4.3.1 or higher,
330 but avoid version 5.0 due to a bug in that version of the driver.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
331
332 Using Django Without a Database
333 -------------------------------
334
335 As mentioned earlier, Django doesn't actually require a database. If you just
336 want to use it to serve dynamic pages that don't hit a database, that's
337 perfectly fine.
338
339 With that said, bear in mind that some of the extra tools bundled with Django
340 *do* require a database, so if you choose not to use a database, you'll miss
341 out on those features. (We highlight these features throughout this book.)
342
343 Starting a Project
344 ==================
345
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
346 Once you've installed Python, Django and (optionally) your database
347 server/library, you can take the first step in developing a Django application
348 by creating a *project*.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
349
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
350 A project is a collection of settings for an instance of Django, including
351 database configuration, Django-specific options and application-specific
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
352 settings.
353
354 If this is your first time using Django, you'll have to take care of some
355 initial setup. Create a new directory to start working in, perhaps something
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
356 like ``/home/username/djcode/``.
357
358 .. admonition:: Where Should This Directory Live?
359
360 If your background is in PHP, you're probably used to putting code under the
361 Web server's document root (in a place such as ``/var/www``). With Django,
362 you don't do that. It's not a good idea to put any of this Python code
363 within your Web server's document root, because in doing so you risk the
364 possibility that people will be able to view your raw source code over the
365 Web. That's not good.
366
367 Put your code in some directory **outside** of the document root.
368
369 Change into the directory you created, and run the command
370 ``django-admin.py startproject mysite``. This will create a ``mysite``
371 directory in your current directory.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
372
373 .. note::
374
375 ``django-admin.py`` should be on your system path if you installed Django
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
376 via its ``setup.py`` utility.
377
961fcf7 Michael Daugherty Remove references to "trunk" and replace them with "development version"...
mpdaugherty authored
378 If you're using the development version, you'll find ``django-admin.py`` in
379 ``djmaster/django/bin``. Because you'll be using ``django-admin.py``
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
380 often, consider adding it to your system path. On Unix, you can do so by
381 symlinking from ``/usr/local/bin``, using a command such as ``sudo ln -s
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
382 /path/to/django/bin/django-admin.py /usr/local/bin/django-admin.py``. On
383 Windows, you'll need to update your ``PATH`` environment variable.
384
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
385 If you installed Django from a packaged version for your Linux
386 distribution, ``django-admin.py`` might be called ``django-admin`` instead.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
387
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
388 If you see a "permission denied" message when running
389 ``django-admin.py startproject``, you'll need to change the file's permissions.
390 To do this, navigate to the directory where ``django-admin.py`` is installed
391 (e.g., ``cd /usr/local/bin``) and run the command ``chmod +x django-admin.py``.
392
393 The ``startproject`` command creates a directory containing four files::
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
394
395 mysite/
396 manage.py
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
397 mysite/
398 __init__.py
399 settings.py
400 urls.py
401 wsgi.py
402
403 .. note:: Doesn't match what you see?
404
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
405 The default project layout recently changed. If you're seeing a
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
406 "flat" layout (with no inner ``mysite/`` directory), you're probably using
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
407 a version of Django that doesn't match this tutorial version. This book covers
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
408 Django 1.4 and above, so if you're using an older version you probably want to
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
409 consult Django's official documentation.
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
410
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
411 The documentation for Django 1.X version is available at https://docs.djangoproject.com/en/1.X/.
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
412
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
413 These files are as follows:
414
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
415 * ``mysite/``: The outer ``mysite/`` directory is just a container for your project.
416 Its name doesn't matter to Django; you can rename it to anything you like.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
417
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
418 * ``manage.py``: A command-line utility that lets you interact with this
419 Django project in various ways. Type ``python manage.py help`` to get a
420 feel for what it can do. You should never have to edit this file; it's
421 created in this directory purely for convenience.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
422
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
423 * ``mysite/mysite/``: The inner ``mysite/`` directory is the actual Python package
424 for your project. Its name is the Python package name you'll need to use to
425 import anything inside it (e.g. ``import mysite.settings``).
426
427 * ``__init__.py``: A file required for Python to treat the ``mysite``
428 directory as a package (i.e., a group of Python modules). It's an empty
429 file, and generally you won't add anything to it.
430
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
431 * ``settings.py``: Settings/configuration for this Django project. Take a
432 look at it to get an idea of the types of settings available, along with
433 their default values.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
434
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
435 * ``urls.py``: The URLs for this Django project. Think of this as the
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
436 "table of contents" of your Django-powered site.
437
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
438 * ``wsgi.py``: An entry-point for WSGI-compatible webservers to serve your project.
8a2a33d Guruprasad Incorporated Jacob's comments and more 1.4 changes
lgp171188 authored
439 See How to deploy with WSGI (https://docs.djangoproject.com/en/1.4/howto/deployment/wsgi/) for more details.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
440
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
441 Despite their small size, these files already constitute a working Django
442 application.
443
444 Running the Development Server
445 ------------------------------
446
447 For some more post-installation positive feedback, let's run the Django
448 development server to see our barebones application in action.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
449
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
450 The Django development server (also called the "runserver" after the command
451 that launches it) is a built-in, lightweight Web server you can use while
452 developing your site. It's included with Django so you can develop your site
453 rapidly, without having to deal with configuring your production server (e.g.,
454 Apache) until you're ready for production. The development server watches your
455 code and automatically reloads it, making it easy for you to change your code
456 without needing to restart anything.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
457
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
458 To start the server, change into your project container directory (``cd mysite``),
459 if you haven't already, and run this command::
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
460
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
461 python manage.py runserver
462
463 You'll see something like this::
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
464
465 Validating models...
466 0 errors found.
467
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
468 Django version 1.4.1, using settings 'mysite.settings'
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
469 Development server is running at http://127.0.0.1:8000/
470 Quit the server with CONTROL-C.
471
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
472 This launches the server locally, on port 8000, accessible only to connections
473 from your own computer. Now that it's running, visit http://127.0.0.1:8000/
039ceb7 Michael Daugherty Remove whitespace at end of lines, wrap lines at 80 characters.
mpdaugherty authored
474 with your Web browser. You might see a different Django version depending on
4b613bf Guruprasad Updated chapter02.rst for Django 1.4.1
lgp171188 authored
475 which version of Django you have installed. You'll see a "Welcome to Django" page shaded in a
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
476 pleasant pastel blue. It worked!
477
478 One final, important note about the development server is worth mentioning
479 before proceeding. Although this server is convenient for development, resist
480 the temptation to use it in anything resembling a production environment. The
481 development server can handle only a single request at a time reliably, and it
482 has not gone through a security audit of any sort. When the time comes to
483 launch your site, see Chapter 12 for information on how to deploy Django.
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
484
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
485 .. admonition:: Changing the Development Server's Host or Port
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
486
487 By default, the ``runserver`` command starts the development server on port
488 8000, listening only for local connections. If you want to change the
489 server's port, pass it as a command-line argument::
490
491 python manage.py runserver 8080
492
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
493 By specifying an IP address, you can tell the server to allow non-local
494 connections. This is especially helpful if you'd like to share a
495 development site with other members of your team. The IP address
496 ``0.0.0.0`` tells the server to listen on any network interface::
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
497
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
498 python manage.py runserver 0.0.0.0:8000
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
499
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
500 When you've done this, other computers on your local network will be able
501 to view your Django site by visiting your IP address in their Web browsers,
502 e.g., http://192.168.1.103:8000/ . (Note that you'll have to consult your
503 network settings to determine your IP address on the local network. Unix
504 users, try running "ifconfig" in a command prompt to get this information.
505 Windows users, try "ipconfig".)
acc918f Jacob Kaplan-Moss Initial import of djangobook from private SVN repo.
jacobian authored
506
507 What's Next?
508 ============
509
d40cfe7 Jacob Kaplan-Moss Restored *2.0* version of the book, not 1.0!
jacobian authored
510 Now that you have everything installed and the development server running,
fdc4800 Jacob Kaplan-Moss Fixed a bunch of reST markup errors.
jacobian authored
511 you're ready to :doc:`learn the basics <chapter03>` of serving Web pages with Django.
Something went wrong with that request. Please try again.