2005-07-17 06:11:33 +00:00
|
|
|
=====================================
|
|
|
|
Writing your first Django app, part 1
|
|
|
|
=====================================
|
|
|
|
|
2005-07-16 04:55:40 +00:00
|
|
|
Let's learn by example.
|
|
|
|
|
2006-05-02 01:31:56 +00:00
|
|
|
Throughout this tutorial, we'll walk you through the creation of a basic
|
2006-05-06 03:31:26 +00:00
|
|
|
poll application.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
|
|
|
It'll consist of two parts:
|
|
|
|
|
2011-10-14 00:12:01 +00:00
|
|
|
* A public site that lets people view polls and vote in them.
|
2015-05-11 23:43:40 +00:00
|
|
|
* An admin site that lets you add, change, and delete polls.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2010-08-19 19:27:44 +00:00
|
|
|
We'll assume you have :doc:`Django installed </intro/install>` already. You can
|
2017-02-09 14:13:00 +00:00
|
|
|
tell Django is installed and which version by running the following command
|
|
|
|
in a shell prompt (indicated by the $ prefix):
|
2012-05-22 11:43:58 +00:00
|
|
|
|
2018-01-20 17:38:48 +00:00
|
|
|
.. console::
|
2012-05-22 11:43:58 +00:00
|
|
|
|
2016-07-02 10:52:36 +00:00
|
|
|
$ python -m django --version
|
2012-05-22 11:43:58 +00:00
|
|
|
|
2013-01-31 12:37:42 +00:00
|
|
|
If Django is installed, you should see the version of your installation. If it
|
|
|
|
isn't, you'll get an error telling "No module named django".
|
|
|
|
|
2019-01-18 15:04:29 +00:00
|
|
|
This tutorial is written for Django |version|, which supports Python 3.6 and
|
2017-12-18 14:06:02 +00:00
|
|
|
later. If the Django version doesn't match, you can refer to the tutorial for
|
|
|
|
your version of Django by using the version switcher at the bottom right corner
|
|
|
|
of this page, or update Django to the newest version. If you're using an older
|
|
|
|
version of Python, check :ref:`faq-python-version-support` to find a compatible
|
|
|
|
version of Django.
|
2012-05-22 11:43:58 +00:00
|
|
|
|
|
|
|
See :doc:`How to install Django </topics/install>` for advice on how to remove
|
|
|
|
older versions of Django and install a newer one.
|
2005-07-16 05:34:17 +00:00
|
|
|
|
2007-02-26 05:15:52 +00:00
|
|
|
.. admonition:: Where to get help:
|
|
|
|
|
|
|
|
If you're having trouble going through this tutorial, please post a message
|
2014-07-01 19:54:28 +00:00
|
|
|
to |django-users| or drop by `#django on irc.freenode.net
|
|
|
|
<irc://irc.freenode.net/django>`_ to chat with other Django users who might
|
|
|
|
be able to help.
|
2007-02-26 05:16:52 +00:00
|
|
|
|
2006-05-02 01:31:56 +00:00
|
|
|
Creating a project
|
|
|
|
==================
|
2005-07-16 04:55:40 +00:00
|
|
|
|
|
|
|
If this is your first time using Django, you'll have to take care of some
|
2008-08-23 22:25:40 +00:00
|
|
|
initial setup. Namely, you'll need to auto-generate some code that establishes a
|
|
|
|
Django :term:`project` -- a collection of settings for an instance of Django,
|
2006-05-02 01:31:56 +00:00
|
|
|
including database configuration, Django-specific options and
|
|
|
|
application-specific settings.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2006-05-02 01:31:56 +00:00
|
|
|
From the command line, ``cd`` into a directory where you'd like to store your
|
2011-08-23 05:24:31 +00:00
|
|
|
code, then run the following command:
|
|
|
|
|
2018-01-20 17:38:48 +00:00
|
|
|
.. console::
|
2011-08-23 05:24:31 +00:00
|
|
|
|
2014-07-26 11:21:52 +00:00
|
|
|
$ django-admin startproject mysite
|
2011-09-09 23:25:48 +00:00
|
|
|
|
2012-11-13 10:45:08 +00:00
|
|
|
This will create a ``mysite`` directory in your current directory. If it didn't
|
2014-07-26 11:21:52 +00:00
|
|
|
work, see :ref:`troubleshooting-django-admin`.
|
2007-09-14 21:48:50 +00:00
|
|
|
|
2007-02-26 20:51:21 +00:00
|
|
|
.. note::
|
2007-07-10 02:45:11 +00:00
|
|
|
|
2007-02-26 20:51:21 +00:00
|
|
|
You'll need to avoid naming projects after built-in Python or Django
|
|
|
|
components. In particular, this means you should avoid using names like
|
2008-08-23 22:25:40 +00:00
|
|
|
``django`` (which will conflict with Django itself) or ``test`` (which
|
2007-02-26 20:51:21 +00:00
|
|
|
conflicts with a built-in Python package).
|
|
|
|
|
2005-12-15 23:44:33 +00:00
|
|
|
.. admonition:: Where should this code live?
|
|
|
|
|
2012-12-13 13:20:47 +00:00
|
|
|
If your background is in plain old PHP (with no use of modern frameworks),
|
|
|
|
you're probably used to putting code under the Web server's document root
|
|
|
|
(in a place such as ``/var/www``). With Django, you don't do that. It's
|
|
|
|
not a good idea to put any of this Python code within your Web server's
|
|
|
|
document root, because it risks the possibility that people may be able
|
|
|
|
to view your code over the Web. That's not good for security.
|
2005-12-15 23:44:33 +00:00
|
|
|
|
2006-01-11 02:06:27 +00:00
|
|
|
Put your code in some directory **outside** of the document root, such as
|
2008-08-23 22:25:40 +00:00
|
|
|
:file:`/home/mycode`.
|
2005-12-15 23:44:33 +00:00
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
Let's look at what :djadmin:`startproject` created::
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2006-05-02 01:31:56 +00:00
|
|
|
mysite/
|
2006-01-11 02:06:27 +00:00
|
|
|
manage.py
|
2011-10-13 05:56:15 +00:00
|
|
|
mysite/
|
|
|
|
__init__.py
|
|
|
|
settings.py
|
|
|
|
urls.py
|
2011-10-22 04:30:10 +00:00
|
|
|
wsgi.py
|
2011-10-13 05:56:15 +00:00
|
|
|
|
2006-01-11 02:06:27 +00:00
|
|
|
These files are:
|
|
|
|
|
2013-07-07 01:24:38 +00:00
|
|
|
* The outer :file:`mysite/` root directory is just a container for your
|
2011-10-13 05:56:15 +00:00
|
|
|
project. Its name doesn't matter to Django; you can rename it to anything
|
|
|
|
you like.
|
|
|
|
|
|
|
|
* :file:`manage.py`: A command-line utility that lets you interact with this
|
|
|
|
Django project in various ways. You can read all the details about
|
|
|
|
:file:`manage.py` in :doc:`/ref/django-admin`.
|
2009-06-18 13:32:12 +00:00
|
|
|
|
2011-10-13 05:56:15 +00:00
|
|
|
* The inner :file:`mysite/` directory is the actual Python package for your
|
|
|
|
project. Its name is the Python package name you'll need to use to import
|
2013-07-07 01:24:38 +00:00
|
|
|
anything inside it (e.g. ``mysite.urls``).
|
2009-06-18 13:32:12 +00:00
|
|
|
|
2011-10-13 05:56:15 +00:00
|
|
|
* :file:`mysite/__init__.py`: An empty file that tells Python that this
|
2016-05-08 22:07:43 +00:00
|
|
|
directory should be considered a Python package. If you're a Python beginner,
|
|
|
|
read :ref:`more about packages <tut-packages>` in the official Python docs.
|
2009-06-18 13:32:12 +00:00
|
|
|
|
2011-10-13 05:56:15 +00:00
|
|
|
* :file:`mysite/settings.py`: Settings/configuration for this Django
|
|
|
|
project. :doc:`/topics/settings` will tell you all about how settings
|
|
|
|
work.
|
|
|
|
|
|
|
|
* :file:`mysite/urls.py`: The URL declarations for this Django project; a
|
|
|
|
"table of contents" of your Django-powered site. You can read more about
|
|
|
|
URLs in :doc:`/topics/http/urls`.
|
2006-01-11 02:06:27 +00:00
|
|
|
|
2013-04-29 17:40:03 +00:00
|
|
|
* :file:`mysite/wsgi.py`: An entry-point for WSGI-compatible web servers to
|
2011-10-22 04:30:10 +00:00
|
|
|
serve your project. See :doc:`/howto/deployment/wsgi/index` for more details.
|
|
|
|
|
2014-05-05 14:54:54 +00:00
|
|
|
The development server
|
2015-05-11 23:43:40 +00:00
|
|
|
======================
|
2014-05-05 14:54:54 +00:00
|
|
|
|
|
|
|
Let's verify your Django project works. Change into the outer :file:`mysite` directory, if
|
|
|
|
you haven't already, and run the following commands:
|
|
|
|
|
2018-01-20 17:38:48 +00:00
|
|
|
.. console::
|
2014-05-05 14:54:54 +00:00
|
|
|
|
|
|
|
$ python manage.py runserver
|
|
|
|
|
|
|
|
You'll see the following output on the command line:
|
|
|
|
|
|
|
|
.. parsed-literal::
|
|
|
|
|
2018-08-22 13:13:58 +00:00
|
|
|
Performing system checks…
|
2014-05-05 14:54:54 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
System check identified no issues (0 silenced).
|
|
|
|
|
|
|
|
You have unapplied migrations; your app may not work properly until they are applied.
|
|
|
|
Run 'python manage.py migrate' to apply them.
|
|
|
|
|
2014-05-05 14:54:54 +00:00
|
|
|
|today| - 15:50:53
|
|
|
|
Django version |version|, using settings 'mysite.settings'
|
|
|
|
Starting development server at http://127.0.0.1:8000/
|
|
|
|
Quit the server with CONTROL-C.
|
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
.. note::
|
|
|
|
Ignore the warning about unapplied database migrations for now; we'll deal
|
|
|
|
with the database shortly.
|
|
|
|
|
2014-05-05 14:54:54 +00:00
|
|
|
You've started the Django development server, a lightweight Web server written
|
|
|
|
purely in Python. We've included this with Django so you can develop things
|
|
|
|
rapidly, without having to deal with configuring a production server -- such as
|
|
|
|
Apache -- until you're ready for production.
|
|
|
|
|
|
|
|
Now's a good time to note: **don't** use this server in anything resembling a
|
|
|
|
production environment. It's intended only for use while developing. (We're in
|
|
|
|
the business of making Web frameworks, not Web servers.)
|
|
|
|
|
|
|
|
Now that the server's running, visit http://127.0.0.1:8000/ with your Web
|
2017-08-07 14:33:55 +00:00
|
|
|
browser. You'll see a "Congratulations!" page, with a rocket taking off.
|
2014-05-05 14:54:54 +00:00
|
|
|
It worked!
|
|
|
|
|
|
|
|
.. admonition:: Changing the port
|
|
|
|
|
|
|
|
By default, the :djadmin:`runserver` command starts the development server
|
|
|
|
on the internal IP at port 8000.
|
|
|
|
|
|
|
|
If you want to change the server's port, pass
|
|
|
|
it as a command-line argument. For instance, this command starts the server
|
|
|
|
on port 8080:
|
|
|
|
|
2018-01-20 17:38:48 +00:00
|
|
|
.. console::
|
2014-05-05 14:54:54 +00:00
|
|
|
|
|
|
|
$ python manage.py runserver 8080
|
|
|
|
|
2017-02-22 00:13:00 +00:00
|
|
|
If you want to change the server's IP, pass it along with the port. For
|
|
|
|
example, to listen on all available public IPs (which is useful if you are
|
|
|
|
running Vagrant or want to show off your work on other computers on the
|
|
|
|
network), use:
|
2014-05-05 14:54:54 +00:00
|
|
|
|
2018-01-20 17:38:48 +00:00
|
|
|
.. console::
|
2014-05-05 14:54:54 +00:00
|
|
|
|
2017-02-22 00:13:00 +00:00
|
|
|
$ python manage.py runserver 0:8000
|
2014-05-05 14:54:54 +00:00
|
|
|
|
2017-02-22 00:13:00 +00:00
|
|
|
**0** is a shortcut for **0.0.0.0**. Full docs for the development server
|
|
|
|
can be found in the :djadmin:`runserver` reference.
|
2014-05-05 14:54:54 +00:00
|
|
|
|
|
|
|
.. admonition:: Automatic reloading of :djadmin:`runserver`
|
|
|
|
|
|
|
|
The development server automatically reloads Python code for each request
|
|
|
|
as needed. You don't need to restart the server for code changes to take
|
|
|
|
effect. However, some actions like adding files don't trigger a restart,
|
|
|
|
so you'll have to restart the server in these cases.
|
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
Creating the Polls app
|
|
|
|
======================
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2005-08-11 16:01:09 +00:00
|
|
|
Now that your environment -- a "project" -- is set up, you're set to start
|
2006-05-02 01:31:56 +00:00
|
|
|
doing work.
|
2005-08-11 16:01:09 +00:00
|
|
|
|
Simplified default project template.
Squashed commit of:
commit 508ec9144b35c50794708225b496bde1eb5e60aa
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 22:50:55 2013 +0100
Tweaked default settings file.
* Explained why BASE_DIR exists.
* Added a link to the database configuration options, and put it in its
own section.
* Moved sensitive settings that must be changed for production at the
top.
commit 6515fd2f1aa73a86dc8dbd2ccf512ddb6b140d57
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 14:35:21 2013 +0100
Documented the simplified app & project templates in the changelog.
commit 2c5b576c2ea91d84273a019b3d0b3b8b4da72f23
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 13:59:27 2013 +0100
Minor fixes in tutorials 5 and 6.
commit 55a51531be8104f21b3cca3f6bf70b0a7139a041
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 13:51:11 2013 +0100
Updated tutorial 2 for the new project template.
commit 29ddae87bdaecff12dd31b16b000c01efbde9e20
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 11:58:54 2013 +0100
Updated tutorial 1 for the new project template.
commit 0ecb9f6e2514cfd26a678a280d471433375101a3
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 11:29:13 2013 +0100
Adjusted the default URLconf detection to account for the admin.
It's now enabled by default.
commit 5fb4da0d3d09dac28dd94e3fde92b9d4335c0565
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 10:36:55 2013 +0100
Added security warnings for the most sensitive settings.
commit 718d84bd8ac4a42fb4b28ec93965de32680f091e
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 23:24:06 2013 +0100
Used an absolute path for the SQLite database.
This ensures the settings file works regardless of which directory
django-admin.py / manage.py is invoked from.
BASE_DIR got a +1 from a BDFL and another core dev. It doesn't involve
the concept of a "Django project"; it's just a convenient way to express
relative paths within the source code repository for non-Python files.
Thanks Jacob Kaplan-Moss for the suggestion.
commit 1b559b4bcda622e10909b68fe5cab90db6727dd9
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 23:22:40 2013 +0100
Removed STATIC_ROOT from the default settings template.
It isn't necessary in development, and it confuses beginners to no end.
Thanks Carl Meyer for the suggestion.
commit a55f141a500bb7c9a1bc259bbe1954c13b199671
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 23:21:43 2013 +0100
Removed MEDIA_ROOT/URL from default settings template.
Many sites will never deal with user-uploaded files, and MEDIA_ROOT is
complicated to explain.
Thanks Carl Meyer for the suggestion.
commit 44bf2f2441420fd9429ee9fe1f7207f92dd87e70
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 22:22:09 2013 +0100
Removed logging config.
This configuration is applied regardless of the value of LOGGING;
duplicating it in LOGGING is confusing.
commit eac747e848eaed65fd5f6f254f0a7559d856f88f
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 22:05:31 2013 +0100
Enabled the locale middleware by default.
USE_I18N is True by default, and doesn't work well without
LocaleMiddleware.
commit d806c62b2d00826dc2688c84b092627b8d571cab
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 22:03:16 2013 +0100
Enabled clickjacking protection by default.
commit 99152c30e6a15003f0b6737dc78e87adf462aacb
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 22:01:48 2013 +0100
Reorganized settings in logical sections, and trimmed comments.
commit d37ffdfcb24b7e0ec7cc113d07190f65fb12fb8a
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:54:11 2013 +0100
Avoided misleading TEMPLATE_DEBUG = DEBUG.
According to the docs TEMPLATE_DEBUG works only when DEBUG = True.
commit 15d9478d3a9850e85841e7cf09cf83050371c6bf
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:46:25 2013 +0100
Removed STATICFILES_FINDERS/TEMPLATE_LOADERS from default settings file.
Only developers with special needs ever need to change these settings.
commit 574da0eb5bfb4570883756914b4dbd7e20e1f61e
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:45:01 2013 +0100
Removed STATICFILES/TEMPLATES_DIRS from default settings file.
The current best practice is to put static files and templates in
applications, for easier testing and deployment.
commit 8cb18dbe56629aa1be74718a07e7cc66b4f9c9f0
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:24:16 2013 +0100
Removed settings related to email reporting from default settings file.
While handy for small scale projects, it isn't exactly a best practice.
commit 8ecbfcb3638058f0c49922540f874a7d802d864f
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 18:54:43 2013 +0100
Documented how to enable the sites framework.
commit 23fc91a6fa67d91ddd9d71b1c3e0dc26bdad9841
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:28:59 2013 +0100
Disabled the sites framework by default.
RequestSite does the job for single-domain websites.
commit c4d82eb8afc0eb8568bf9c4d12644272415e3960
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 00:08:33 2013 +0100
Added a default admin.py to the application template.
Thanks Ryan D Hiebert for the suggestion.
commit 4071dc771e5c44b1c5ebb9beecefb164ae465e22
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 10:59:49 2013 +0100
Enabled the admin by default.
Everyone uses the admin.
commit c807a31f8d89e7e7fd97380e3023f7983a8b6fcb
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 10:57:05 2013 +0100
Removed admindocs from default project template.
commit 09e4ce0e652a97da1a9e285046a91c8ad7a9189c
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:32:52 2013 +0100
Added links to the settings documentation.
commit 5b8f5eaef364eb790fcde6f9e86f7d266074cca8
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 11:06:54 2013 +0100
Used a significant example for URLconf includes.
commit 908e91d6fcee2a3cb51ca26ecdf12a6a24e69ef8
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:22:31 2013 +0100
Moved code comments about WSGI to docs, and rewrote said docs.
commit 50417e51996146f891d08ca8b74dcc736a581932
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 15:51:50 2013 +0100
Normalized the default application template.
Removed the default test that 1 + 1 = 2, because it's been committed
way too many times, in too many projects.
Added an import of `render` for views, because the first view will
often be:
def home(request):
return render(request, "mysite/home.html")
2013-01-28 14:51:50 +00:00
|
|
|
Each application you write in Django consists of a Python package that follows
|
|
|
|
a certain convention. Django comes with a utility that automatically generates
|
|
|
|
the basic directory structure of an app, so you can focus on writing code
|
|
|
|
rather than creating directories.
|
2005-08-11 16:01:09 +00:00
|
|
|
|
2006-01-11 02:06:27 +00:00
|
|
|
.. admonition:: Projects vs. apps
|
|
|
|
|
|
|
|
What's the difference between a project and an app? An app is a Web
|
2010-10-09 08:12:50 +00:00
|
|
|
application that does something -- e.g., a Weblog system, a database of
|
2006-01-11 02:06:27 +00:00
|
|
|
public records or a simple poll app. A project is a collection of
|
2015-11-15 12:05:15 +00:00
|
|
|
configuration and apps for a particular website. A project can contain
|
2006-01-11 02:06:27 +00:00
|
|
|
multiple apps. An app can be in multiple projects.
|
2005-08-11 16:01:09 +00:00
|
|
|
|
2016-05-08 22:07:43 +00:00
|
|
|
Your apps can live anywhere on your :ref:`Python path <tut-searchpath>`. In
|
|
|
|
this tutorial, we'll create our poll app right next to your :file:`manage.py`
|
|
|
|
file so that it can be imported as its own top-level module, rather than a
|
|
|
|
submodule of ``mysite``.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2011-10-13 05:56:15 +00:00
|
|
|
To create your app, make sure you're in the same directory as :file:`manage.py`
|
|
|
|
and type this command:
|
2008-08-23 22:25:40 +00:00
|
|
|
|
2018-01-20 17:38:48 +00:00
|
|
|
.. console::
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2013-09-18 14:35:41 +00:00
|
|
|
$ python manage.py startapp polls
|
2005-07-20 17:42:36 +00:00
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
That'll create a directory :file:`polls`, which is laid out like this::
|
2005-07-16 04:55:40 +00:00
|
|
|
|
|
|
|
polls/
|
|
|
|
__init__.py
|
Simplified default project template.
Squashed commit of:
commit 508ec9144b35c50794708225b496bde1eb5e60aa
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 22:50:55 2013 +0100
Tweaked default settings file.
* Explained why BASE_DIR exists.
* Added a link to the database configuration options, and put it in its
own section.
* Moved sensitive settings that must be changed for production at the
top.
commit 6515fd2f1aa73a86dc8dbd2ccf512ddb6b140d57
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 14:35:21 2013 +0100
Documented the simplified app & project templates in the changelog.
commit 2c5b576c2ea91d84273a019b3d0b3b8b4da72f23
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 13:59:27 2013 +0100
Minor fixes in tutorials 5 and 6.
commit 55a51531be8104f21b3cca3f6bf70b0a7139a041
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 13:51:11 2013 +0100
Updated tutorial 2 for the new project template.
commit 29ddae87bdaecff12dd31b16b000c01efbde9e20
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 11:58:54 2013 +0100
Updated tutorial 1 for the new project template.
commit 0ecb9f6e2514cfd26a678a280d471433375101a3
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 11:29:13 2013 +0100
Adjusted the default URLconf detection to account for the admin.
It's now enabled by default.
commit 5fb4da0d3d09dac28dd94e3fde92b9d4335c0565
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 10:36:55 2013 +0100
Added security warnings for the most sensitive settings.
commit 718d84bd8ac4a42fb4b28ec93965de32680f091e
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 23:24:06 2013 +0100
Used an absolute path for the SQLite database.
This ensures the settings file works regardless of which directory
django-admin.py / manage.py is invoked from.
BASE_DIR got a +1 from a BDFL and another core dev. It doesn't involve
the concept of a "Django project"; it's just a convenient way to express
relative paths within the source code repository for non-Python files.
Thanks Jacob Kaplan-Moss for the suggestion.
commit 1b559b4bcda622e10909b68fe5cab90db6727dd9
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 23:22:40 2013 +0100
Removed STATIC_ROOT from the default settings template.
It isn't necessary in development, and it confuses beginners to no end.
Thanks Carl Meyer for the suggestion.
commit a55f141a500bb7c9a1bc259bbe1954c13b199671
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 23:21:43 2013 +0100
Removed MEDIA_ROOT/URL from default settings template.
Many sites will never deal with user-uploaded files, and MEDIA_ROOT is
complicated to explain.
Thanks Carl Meyer for the suggestion.
commit 44bf2f2441420fd9429ee9fe1f7207f92dd87e70
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 22:22:09 2013 +0100
Removed logging config.
This configuration is applied regardless of the value of LOGGING;
duplicating it in LOGGING is confusing.
commit eac747e848eaed65fd5f6f254f0a7559d856f88f
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 22:05:31 2013 +0100
Enabled the locale middleware by default.
USE_I18N is True by default, and doesn't work well without
LocaleMiddleware.
commit d806c62b2d00826dc2688c84b092627b8d571cab
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 22:03:16 2013 +0100
Enabled clickjacking protection by default.
commit 99152c30e6a15003f0b6737dc78e87adf462aacb
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 22:01:48 2013 +0100
Reorganized settings in logical sections, and trimmed comments.
commit d37ffdfcb24b7e0ec7cc113d07190f65fb12fb8a
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:54:11 2013 +0100
Avoided misleading TEMPLATE_DEBUG = DEBUG.
According to the docs TEMPLATE_DEBUG works only when DEBUG = True.
commit 15d9478d3a9850e85841e7cf09cf83050371c6bf
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:46:25 2013 +0100
Removed STATICFILES_FINDERS/TEMPLATE_LOADERS from default settings file.
Only developers with special needs ever need to change these settings.
commit 574da0eb5bfb4570883756914b4dbd7e20e1f61e
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:45:01 2013 +0100
Removed STATICFILES/TEMPLATES_DIRS from default settings file.
The current best practice is to put static files and templates in
applications, for easier testing and deployment.
commit 8cb18dbe56629aa1be74718a07e7cc66b4f9c9f0
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:24:16 2013 +0100
Removed settings related to email reporting from default settings file.
While handy for small scale projects, it isn't exactly a best practice.
commit 8ecbfcb3638058f0c49922540f874a7d802d864f
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 18:54:43 2013 +0100
Documented how to enable the sites framework.
commit 23fc91a6fa67d91ddd9d71b1c3e0dc26bdad9841
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:28:59 2013 +0100
Disabled the sites framework by default.
RequestSite does the job for single-domain websites.
commit c4d82eb8afc0eb8568bf9c4d12644272415e3960
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Tue Jan 29 00:08:33 2013 +0100
Added a default admin.py to the application template.
Thanks Ryan D Hiebert for the suggestion.
commit 4071dc771e5c44b1c5ebb9beecefb164ae465e22
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 10:59:49 2013 +0100
Enabled the admin by default.
Everyone uses the admin.
commit c807a31f8d89e7e7fd97380e3023f7983a8b6fcb
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 10:57:05 2013 +0100
Removed admindocs from default project template.
commit 09e4ce0e652a97da1a9e285046a91c8ad7a9189c
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:32:52 2013 +0100
Added links to the settings documentation.
commit 5b8f5eaef364eb790fcde6f9e86f7d266074cca8
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 11:06:54 2013 +0100
Used a significant example for URLconf includes.
commit 908e91d6fcee2a3cb51ca26ecdf12a6a24e69ef8
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 16:22:31 2013 +0100
Moved code comments about WSGI to docs, and rewrote said docs.
commit 50417e51996146f891d08ca8b74dcc736a581932
Author: Aymeric Augustin <aymeric.augustin@m4x.org>
Date: Mon Jan 28 15:51:50 2013 +0100
Normalized the default application template.
Removed the default test that 1 + 1 = 2, because it's been committed
way too many times, in too many projects.
Added an import of `render` for views, because the first view will
often be:
def home(request):
return render(request, "mysite/home.html")
2013-01-28 14:51:50 +00:00
|
|
|
admin.py
|
2015-10-01 19:17:39 +00:00
|
|
|
apps.py
|
2013-11-27 16:29:49 +00:00
|
|
|
migrations/
|
|
|
|
__init__.py
|
2006-05-02 01:31:56 +00:00
|
|
|
models.py
|
2009-10-14 13:38:31 +00:00
|
|
|
tests.py
|
2005-11-16 02:00:23 +00:00
|
|
|
views.py
|
2005-07-16 04:55:40 +00:00
|
|
|
|
|
|
|
This directory structure will house the poll application.
|
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
Write your first view
|
|
|
|
=====================
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
Let's write the first view. Open the file ``polls/views.py``
|
|
|
|
and put the following Python code in it:
|
2013-09-23 22:23:47 +00:00
|
|
|
|
2018-09-10 17:00:34 +00:00
|
|
|
.. code-block:: python
|
|
|
|
:caption: polls/views.py
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
from django.http import HttpResponse
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
def index(request):
|
|
|
|
return HttpResponse("Hello, world. You're at the polls index.")
|
2008-08-23 22:25:40 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
This is the simplest view possible in Django. To call the view, we need to map
|
|
|
|
it to a URL - and for this we need a URLconf.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
To create a URLconf in the polls directory, create a file called ``urls.py``.
|
|
|
|
Your app directory should now look like::
|
2013-02-07 10:51:25 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
polls/
|
|
|
|
__init__.py
|
|
|
|
admin.py
|
2015-10-01 19:17:39 +00:00
|
|
|
apps.py
|
2015-06-04 08:31:57 +00:00
|
|
|
migrations/
|
|
|
|
__init__.py
|
2015-05-11 23:43:40 +00:00
|
|
|
models.py
|
|
|
|
tests.py
|
|
|
|
urls.py
|
|
|
|
views.py
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
In the ``polls/urls.py`` file include the following code:
|
2013-09-23 22:23:47 +00:00
|
|
|
|
2018-09-10 17:00:34 +00:00
|
|
|
.. code-block:: python
|
|
|
|
:caption: polls/urls.py
|
2008-08-23 22:25:40 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
from django.urls import path
|
2013-11-27 16:29:49 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
from . import views
|
2013-11-27 16:29:49 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
urlpatterns = [
|
2016-10-20 17:29:04 +00:00
|
|
|
path('', views.index, name='index'),
|
2015-05-11 23:43:40 +00:00
|
|
|
]
|
2013-11-27 16:29:49 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
The next step is to point the root URLconf at the ``polls.urls`` module. In
|
2016-10-20 17:29:04 +00:00
|
|
|
``mysite/urls.py``, add an import for ``django.urls.include`` and insert an
|
|
|
|
:func:`~django.urls.include` in the ``urlpatterns`` list, so you have:
|
2013-11-27 16:29:49 +00:00
|
|
|
|
2018-09-10 17:00:34 +00:00
|
|
|
.. code-block:: python
|
|
|
|
:caption: mysite/urls.py
|
2013-11-27 16:29:49 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
from django.contrib import admin
|
2018-03-22 07:53:56 +00:00
|
|
|
from django.urls import include, path
|
2013-11-27 16:29:49 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
urlpatterns = [
|
2016-10-20 17:29:04 +00:00
|
|
|
path('polls/', include('polls.urls')),
|
|
|
|
path('admin/', admin.site.urls),
|
2015-05-11 23:43:40 +00:00
|
|
|
]
|
2013-11-27 16:29:49 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
The :func:`~django.urls.include` function allows referencing other URLconfs.
|
|
|
|
Whenever Django encounters :func:`~django.urls.include`, it chops off whatever
|
|
|
|
part of the URL matched up to that point and sends the remaining string to the
|
|
|
|
included URLconf for further processing.
|
2016-03-09 17:18:21 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
The idea behind :func:`~django.urls.include` is to make it easy to
|
2016-03-09 17:18:21 +00:00
|
|
|
plug-and-play URLs. Since polls are in their own URLconf
|
|
|
|
(``polls/urls.py``), they can be placed under "/polls/", or under
|
|
|
|
"/fun_polls/", or under "/content/polls/", or any other path root, and the
|
|
|
|
app will still work.
|
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
.. admonition:: When to use :func:`~django.urls.include()`
|
2015-12-30 16:13:58 +00:00
|
|
|
|
|
|
|
You should always use ``include()`` when you include other URL patterns.
|
|
|
|
``admin.site.urls`` is the only exception to this.
|
|
|
|
|
2019-01-14 23:54:15 +00:00
|
|
|
You have now wired an ``index`` view into the URLconf. Verify it's working with
|
|
|
|
the following command:
|
2008-08-23 22:25:40 +00:00
|
|
|
|
2018-01-20 17:38:48 +00:00
|
|
|
.. console::
|
2006-01-11 02:06:27 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
$ python manage.py runserver
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
Go to http://localhost:8000/polls/ in your browser, and you should see the
|
|
|
|
text "*Hello, world. You're at the polls index.*", which you defined in the
|
|
|
|
``index`` view.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2018-05-19 13:17:15 +00:00
|
|
|
.. admonition:: Page not found?
|
|
|
|
|
|
|
|
If you get an error page here, check that you're going to
|
|
|
|
http://localhost:8000/polls/ and not http://localhost:8000/.
|
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
The :func:`~django.urls.path` function is passed four arguments, two required:
|
|
|
|
``route`` and ``view``, and two optional: ``kwargs``, and ``name``.
|
2015-05-11 23:43:40 +00:00
|
|
|
At this point, it's worth reviewing what these arguments are for.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
:func:`~django.urls.path` argument: ``route``
|
2015-05-11 23:43:40 +00:00
|
|
|
---------------------------------------------
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
``route`` is a string that contains a URL pattern. When processing a request,
|
|
|
|
Django starts at the first pattern in ``urlpatterns`` and makes its way down
|
|
|
|
the list, comparing the requested URL against each pattern until it finds one
|
|
|
|
that matches.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
Patterns don't search GET and POST parameters, or the domain name. For example,
|
|
|
|
in a request to ``https://www.example.com/myapp/``, the URLconf will look for
|
|
|
|
``myapp/``. In a request to ``https://www.example.com/myapp/?page=3``, the
|
|
|
|
URLconf will also look for ``myapp/``.
|
2013-05-18 11:34:29 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
:func:`~django.urls.path` argument: ``view``
|
2015-05-11 23:43:40 +00:00
|
|
|
--------------------------------------------
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
When Django finds a matching pattern, it calls the specified view function with
|
|
|
|
an :class:`~django.http.HttpRequest` object as the first argument and any
|
|
|
|
"captured" values from the route as keyword arguments. We'll give an example
|
|
|
|
of this in a bit.
|
2013-12-30 17:15:49 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
:func:`~django.urls.path` argument: ``kwargs``
|
2015-05-11 23:43:40 +00:00
|
|
|
----------------------------------------------
|
2013-12-30 17:15:49 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
Arbitrary keyword arguments can be passed in a dictionary to the target view. We
|
|
|
|
aren't going to use this feature of Django in the tutorial.
|
2013-12-30 17:15:49 +00:00
|
|
|
|
2016-10-20 17:29:04 +00:00
|
|
|
:func:`~django.urls.path` argument: ``name``
|
|
|
|
--------------------------------------------
|
2013-12-30 17:15:49 +00:00
|
|
|
|
2016-07-04 13:43:29 +00:00
|
|
|
Naming your URL lets you refer to it unambiguously from elsewhere in Django,
|
|
|
|
especially from within templates. This powerful feature allows you to make
|
2016-07-06 19:31:12 +00:00
|
|
|
global changes to the URL patterns of your project while only touching a single
|
2016-07-04 13:43:29 +00:00
|
|
|
file.
|
2005-07-16 04:55:40 +00:00
|
|
|
|
2015-05-11 23:43:40 +00:00
|
|
|
When you're comfortable with the basic request and response flow, read
|
|
|
|
:doc:`part 2 of this tutorial </intro/tutorial02>` to start working with the
|
|
|
|
database.
|