REKCARC-TSC-UHT Documentation

.
├── CodeReview.md
├── DS_tutorial.pdf
├── Python
│   ├── Numpy.ipynb
│   └── Python\ Advanced\ Topics.ipynb
├── backend
│   ├── Django.md
│   ├── Django_preparation.pdf
│   └── SQL.pdf
├── crawler
│   └── crawler.ipynb
├── readme.md
├── soup
│   ├── BeatifulSoup4.ipynb
│   ├── Pandas.ipynb
│   ├── Pandas_refined.ipynb
│   └── README.md
└── visualize
    ├── Matplotlib.ipynb
    └── README.md

5 directories, 15 files

conda install -c conda-forge basemap-data-hires

python -m django --version

django-admin startproject mysite

mysite/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

python manage.py runserver

python manage.py startapp <app_name>

python manage.py startapp polls

from django.http import HttpResponse
def index(request):
    return HttpResponse("Hello, world. You're at the polls index.")

from django.urls import path
from . import views
urlpatterns = [
    path('hello', views.index, name='index'),
]

from django.urls import include, path
urlpatterns = [
    path('polls/', include('polls.urls'))
]

python manage.py runserver

http://localhost:8000/polls/hello

pip install mysqlclient

[client]
host = 服务器地址
database = 所选数据库
user = 用户名
password = 密码
port = 端口
default-character-set = 字符集，这里推荐 utf8mb4

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'OPTIONS': {
            'read_default_file': '<my.cnf 的地址>', 
        },
    }
}

from django.db import models
class Question(models.Model):
    question_text = models.CharField(max_length=200)
    pub_date = models.FloatField('date published')

class Choice(models.Model):
    question = models.ForeignKey(Question, on_delete=models.CASCADE)
    choice_text = models.CharField(max_length=200)
    votes = models.IntegerField(default=0)

INSTALLED_APPS = [
    'polls.apps.PollsConfig',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

python manage.py makemigrations polls
Migrations for 'polls':
  polls\migrations\0001_initial.py
    - Create model Question
    - Create model Choice

python manage.py migrate

python manage.py sqlmigrate polls 0001

# 创建枚举选项：
class Role(models.TextChoices):
    MEMBER = "member"
    DEV = "dev"
    QA = "qa"
    SYS = "sys"
    SUPERMASTER = "supermaster"

class PendingModifyPasswordEmail(models.Model): 
    # 指定主键
    id = models.BigAutoField(primary_key=True) 
    # 唯一
    hash1 = models.CharField(max_length=100, unique=True) 
    # 枚举类型
    role = models.CharField(max_length=12, choices=Role.choices) 
    # 默认函数
    createdAt = models.FloatField(default=getTime.get_timestamp)
    class Meta: 
    # 索引
    indexes = [
        models.Index(fields=["hash1", "role"]),
        models.Index(fields=["createdAt"]),
    ]
    # 联合唯一
    unique_together = ["hash1", "createdAt"]

python manage.py shell

/* Detailed source-code truncated for AI context efficiency. */

def __str__(self):
        return f"{self.question_text} @ {self.pub_date}"

def __str__(self):
        return f"{self.choice_text} [{self.votes}]"

>>> from polls.models import *

# 自定义显示:
>>> Choice.objects.all()
<QuerySet [<Choice: A [0]>, <Choice: B [0]>, <Choice: C [0]>]>
>>> Question.objects.all()
<QuerySet [<Question: Is it a question? @ 1658422997.1246326>,
           <Question: Is it a question? @ 1658423046.8407936>,
           <Question: Is it another question? @ 1658423054.8635635>]>

# save object: 修改特定对象
>>> ch = Choice.objects.get(pk=2) >>> ch.votes = 114514
>>> ch.save()
# update: 修改整个 Query Set
>>> Choice.objects.filter(id=3).update(votes=255) 1
# 查看修改效果
>>> Choice.objects.all()
<QuerySet [<Choice: A [0]>, <Choice: B [114514]>, <Choice: C [255]>]>

/* Detailed source-code truncated for AI context efficiency. */

>>> print(
...     Choice.objects.filter(
...         Q(question__id=2) & (~Q(choice_text__in=["A", "B"]) | Q(id=1))
...     ).query
... )
SELECT `polls_choice`.`id`, `polls_choice`.`question_id`, `polls_choice`.`choice_text`, `polls_choice`.`votes` FROM `polls_choice` WHERE(`polls_choice`.`question_id` = 2 AND (NOT (`polls_choice`.`choice_text` IN (A, B)) OR `polls_choice`.`id` = 1))

>>> Choice.objects.raw("SELECT * FROM ...")

from django.http import HttpRequest, JsonResponse
from .models import *
from django.forms.models import model_to_dict

def question_detail(req: HttpRequest, qid: int):
    res = Question.objects.filter(id=qid).first()
    if res:
        return JsonResponse({
            "code": 0,
            "data": {
                **model_to_dict(res),
                "choices": [
                    model_to_dict(ch, exclude=["question"])
                    for ch in res.choice_set.all()
                ]
            }
        })
    else:
        return JsonResponse({
            "code": -1
        }, status=404)

from django.urls import path
from . import views

urlpatterns = [
    path('question/<int:qid>', views.question_detail),
]

views.question_detail(request=<HttpRequest object>, qid=<int:qid>)

// 请求 
{
    "qid": 2,
    "cid": 0 
}
// 响应 
{
    "code": 0,
    "choices": [...]
}

def vote(req: HttpRequest):
    info = json.loads(req.body)
    try:
        qid = info["qid"]
        cid = info["cid"]
        ch = Choice.objects.get(pk=cid)
        if ch.question.id != qid:
            raise ValueError("Mismatched question and choice pair")
        ch.votes += 1
        ch.save()
        return JsonResponse({
            "code": 0,
            "choices": [
                model_to_dict(ch, exclude=["question"])
                for ch in Choice.objects.filter(question__id=qid)
            ]
        }) 
    except:
        if settings.DEBUG:
            raise
        return JsonResponse({
            "code": -1
        }, status=400)

path('vote', views.vote)

from django.views.decorators.csrf import csrf_exempt
@csrf_exempt
def vote(req: HttpRequest):
    ...

from django.views.decorators.http import require_http_methods as method
@method(["GET"])
def leaderboard(req: HttpRequest):
...

uwsgi --http :10001 --module mysite.wsgi

import pymysql

pymysql.install_as_MySQLdb()

[uwsgi]
socket = :9999
chdir = /home/train/site module = mysite.wsgi master = true
processes = 9
threads = 9
vacuum = true

uwsgi --ini u.ini

server{
listen 10002;
server_name 59.66.131.240;
location / {
        include uwsgi_params;
        uwsgi_pass 127.0.0.1:9999;
        uwsgi_read_timeout 15;
  }
}

sudo service nginx start

server {
listen 10001;
server_name 59.66.131.240;
location / {
        root /home/nana/build;
        index index.html;
}

sudo nginx -t
sudo cat /var/log/nginx/error.log

index

intro/index
topics/index
howto/index
faq/index
ref/index
misc/index
glossary
releases/index
internals/index

concrete model
    A non-abstract (:attr:`abstract=False
    <django.db.models.Options.abstract>`) model.

field
    An attribute on a :term:`model`; a given field usually maps directly to
    a single database column.

    See :doc:`/topics/db/models`.

generic view
    A higher-order :term:`view` function that provides an abstract/generic
    implementation of a common idiom or pattern found in view development.

    See :doc:`/topics/class-based-views/index`.

model
    Models store your application's data.

    See :doc:`/topics/db/models`.

MTV
    "Model-template-view"; a software pattern, similar in style to MVC, but
    a better description of the way Django does things.

    See :ref:`the FAQ entry <faq-mtv>`.

MVC
    `Model-view-controller`__; a software pattern. Django :ref:`follows MVC
    to some extent <faq-mtv>`.

    __ https://en.wikipedia.org/wiki/Model-view-controller

project
    A Python package -- i.e. a directory of code -- that contains all the
    settings for an instance of Django. This would include database
    configuration, Django-specific options and application-specific
    settings.

property
    Also known as "managed attributes", and a feature of Python since
    version 2.2. This is a neat way to implement attributes whose usage
    resembles attribute access, but whose implementation uses method calls.

    See :class:`property`.

queryset
    An object representing some set of rows to be fetched from the database.

    See :doc:`/topics/db/queries`.

slug
    A short label for something, containing only letters, numbers,
    underscores or hyphens. They're generally used in URLs. For
    example, in a typical blog entry URL:

    .. parsed-literal::

        https://www.djangoproject.com/weblog/2008/apr/12/**spring**/

    the last bit (``spring``) is the slug.

template
    A chunk of text that acts as formatting for representing data. A
    template helps to abstract the presentation of data from the data
    itself.

    See :doc:`/topics/templates`.

view
    A function responsible for rendering a page.

Django (Version 1.5) [Computer Software]. (2013). Retrieved from https://djangoproject.com.

>>> from django.db import connection
>>> connection.queries
[{'sql': 'SELECT polls_polls.id, polls_polls.question, polls_polls.pub_date FROM polls_polls',
'time': '0.002'}]

``sql`` -- The raw SQL statement
``time`` -- How long the statement took to execute, in seconds.

>>> from django.db import connections
>>> connections['my_db_alias'].queries

from django.db import reset_queries
reset_queries()

ALTER TABLE myapp_mytable ENGINE=MyISAM;

UnicodeDecodeError: 'ascii' codec can't decode byte 0x?? in position ?:
ordinal not in range(128)

MIDDLEWARE = [
    '...',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.auth.middleware.RemoteUserMiddleware',
    '...',
]

AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.RemoteUserBackend',
]

Since the ``RemoteUserBackend`` inherits from ``ModelBackend``, you will
still have all of the same permissions checking that is implemented in
``ModelBackend``.

Users with :attr:`is_active=False
<django.contrib.auth.models.User.is_active>` won't be allowed to
authenticate. Use
:class:`~django.contrib.auth.backends.AllowAllUsersRemoteUserBackend` if
you want to allow them to.

.. versionchanged:: 1.10

    In older versions, inactive users weren't rejected as described above.

from django.contrib.auth.middleware import RemoteUserMiddleware

class CustomHeaderMiddleware(RemoteUserMiddleware):
    header = 'HTTP_AUTHUSER'

Be very careful if using a ``RemoteUserMiddleware`` subclass with a custom
HTTP header. You must be sure that your front-end web server always sets or
strips that header based on the appropriate authentication checks, never
permitting an end-user to submit a fake (or "spoofed") header value. Since
the HTTP headers ``X-Auth-User`` and ``X-Auth_User`` (for example) both
normalize to the ``HTTP_X_AUTH_USER`` key in ``request.META``, you must
also check that your web server doesn't allow a spoofed header using
underscores in place of dashes.

This warning doesn't apply to ``RemoteUserMiddleware`` in its default
configuration with ``header = 'REMOTE_USER'``, since a key that doesn't
start with ``HTTP_`` in ``request.META`` can only be set by your WSGI
server, not directly from an HTTP request header.

from django.core.files.storage import Storage

    class MyStorage(Storage):
        ...

from django.conf import settings
    from django.core.files.storage import Storage

    class MyStorage(Storage):
        def __init__(self, option=None):
            if not option:
                option = settings.CUSTOM_STORAGE_OPTIONS
            ...

In older versions, this method was not called when ``upload_to`` was a
callable.

def as_sql(self, compiler, connection):
      lhs, lhs_params = self.process_lhs(compiler, connection)
      rhs, rhs_params = self.process_rhs(compiler, connection)
      params = lhs_params + rhs_params
      return '%s <> %s' % (lhs, rhs), params

from django.db.models.fields import Field

@Field.register_lookup
class NotEqualLookup(Lookup):
    # ...

SELECT ... WHERE ABS("experiments"."change") = 27

SELECT ... WHERE ABS("experiments"."change") < 27

from django.db.models import FloatField, Transform

class AbsoluteValue(Transform):
    lookup_name = 'abs'
    function = 'ABS'

    @property
    def output_field(self):
        return FloatField()

SELECT .. WHERE "experiments"."change" < 27 AND "experiments"."change" > -27

def as_sql(self, compiler, connection):
      lhs, lhs_params = compiler.compile(self.lhs.lhs)
      rhs, rhs_params = self.process_rhs(compiler, connection)
      params = lhs_params + rhs_params + lhs_params + rhs_params
      return '%s < %s AND %s > -%s' % (lhs, rhs, lhs, rhs), params

SELECT ... WHERE UPPER("author"."name") = UPPER('doe')

class CoordinatesField(Field):
    def get_lookup(self, lookup_name):
        if lookup_name.startswith('x'):
            try:
                dimension = int(lookup_name[1:])
            except ValueError:
                pass
            else:
                return get_coordinate_lookup(dimension)
        return super(CoordinatesField, self).get_lookup(lookup_name)

polls/
    __init__.py
    models.py
    management/
        __init__.py
        commands/
            __init__.py
            _private.py
            closepoll.py
    tests.py
    views.py

Custom management commands are especially useful for running standalone
scripts or for scripts that are periodically executed from the UNIX crontab
or from Windows scheduled tasks control panel.

from django.core.management.base import BaseCommand, CommandError
from polls.models import Question as Poll

class Command(BaseCommand):
    help = 'Closes the specified poll for voting'

    def add_arguments(self, parser):
        parser.add_argument('poll_id', nargs='+', type=int)

    def handle(self, *args, **options):
        for poll_id in options['poll_id']:
            try:
                poll = Poll.objects.get(pk=poll_id)
            except Poll.DoesNotExist:
                raise CommandError('Poll "%s" does not exist' % poll_id)

            poll.opened = False
            poll.save()

            self.stdout.write(self.style.SUCCESS('Successfully closed poll "%s"' % poll_id))

self.stdout.write("Unterminated line", ending='')

class Command(BaseCommand):
    def add_arguments(self, parser):
        # Positional arguments
        parser.add_argument('poll_id', nargs='+', type=int)

        # Named (optional) arguments
        parser.add_argument(
            '--delete',
            action='store_true',
            dest='delete',
            default=False,
            help='Delete poll instead of closing it',
        )

    def handle(self, *args, **options):
        # ...
        if options['delete']:
            poll.delete()
        # ...

from django.core.management.base import BaseCommand, CommandError
from django.utils import translation

class Command(BaseCommand):
    ...
    can_import_settings = True

    def handle(self, *args, **options):

        # Activate a fixed locale, e.g. Russian
        translation.activate('ru')

        # Or you can activate the LANGUAGE_CODE # chosen in the settings:
        from django.conf import settings
        translation.activate(settings.LANGUAGE_CODE)

        # Your command logic here
        ...

        translation.deactivate()

A boolean indicating whether the command needs to be able to
import Django settings; if ``True``, ``execute()`` will verify
that this is possible before proceeding. Default value is
``True``.

A short description of the command, which will be printed in the
help message when the user runs the command
``python manage.py help <command>``.

If your command defines mandatory positional arguments, you can customize
the message error returned in the case of missing arguments. The default is
output by :py:mod:`argparse` ("too few arguments").

A boolean indicating whether the command outputs SQL statements; if
``True``, the output will automatically be wrapped with ``BEGIN;`` and
``COMMIT;``. Default value is ``False``.

.. versionadded:: 1.10

A boolean; if ``True``, the command prints a warning if the set of
migrations on disk don't match the migrations in the database. A warning
doesn't prevent the command from executing. Default value is ``False``.

A boolean; if ``True``, the entire Django project will be checked for
potential problems prior to executing the command. Default value is ``True``.

A boolean indicating whether the locale set in settings should be preserved
during the execution of the command instead of being forcibly set to 'en-us'.

Default value is ``False``.

Make sure you know what you are doing if you decide to change the value of
this option in your custom command if it creates database content that
is locale-sensitive and such content shouldn't contain any translations
(like it happens e.g. with django.contrib.auth permissions) as making the
locale differ from the de facto default 'en-us' might cause unintended
effects. Seethe `Management commands and locales`_ section above for
further details.

This option can't be ``False`` when the
:data:`~BaseCommand.can_import_settings` option is set to ``False`` too
because attempting to set the locale needs access to settings. This
condition will generate a :exc:`CommandError`.

An instance attribute that helps create colored output when writing to
``stdout`` or ``stderr``. For example::

    self.stdout.write(self.style.SUCCESS('...'))

See :ref:`syntax-coloring` to learn how to modify the color palette and to
see the available styles (use uppercased versions of the "roles" described
in that section).

If you pass the :option:`--no-color` option when running your command, all
``self.style()`` calls will return the original string uncolored.

If you implement ``__init__`` in your subclass of :class:`BaseCommand`,
you must call :class:`BaseCommand`’s ``__init__``::

    class Command(BaseCommand):
        def __init__(self, *args, **kwargs):
            super(Command, self).__init__(*args, **kwargs)
            # ...

Entry point to add parser arguments to handle command line arguments passed
to the command. Custom commands should override this method to add both
positional and optional arguments accepted by the command. Calling
``super()`` is not needed when directly subclassing ``BaseCommand``.

Returns the Django version, which should be correct for all built-in Django
commands. User-supplied commands can override this method to return their
own version.

Tries to execute this command, performing system checks if needed (as
controlled by the :attr:`requires_system_checks` attribute). If the command
raises a :exc:`CommandError`, it's intercepted and printed to stderr.

``execute()`` should not be called directly from your code to execute a
command. Use :func:`~django.core.management.call_command` instead.

The actual logic of the command. Subclasses must implement this method.

It may return a Unicode string which will be printed to ``stdout`` (wrapped
by ``BEGIN;`` and ``COMMIT;`` if :attr:`output_transaction` is ``True``).

Uses the system check framework to inspect the entire Django project for
potential problems. Serious problems are raised as a :exc:`CommandError`;
warnings are output to stderr; minor notifications are output to stdout.

If ``app_configs`` and ``tags`` are both ``None``, all system checks are
performed. ``tags`` can be a list of check tags, like ``compatibility`` or
``models``.

Perform the command's actions for ``app_config``, which will be an
:class:`~django.apps.AppConfig` instance corresponding to an application
label given on the command line.

Perform the command's actions for ``label``, which will be the string as
given on the command line.

class Hand(object):
    """A hand of cards (bridge style)"""

    def __init__(self, north, east, south, west):
        # Input parameters are lists of cards ('Ah', '9s', etc.)
        self.north = north
        self.east = east
        self.south = south
        self.west = west

    # ... (other possibly useful methods omitted) ...

example = MyModel.objects.get(pk=1)
print(example.hand.north)

new_hand = Hand(north, east, south, west)
example.hand = new_hand
example.save()

from django.db import models

class HandField(models.Field):

    description = "A hand of cards (bridge style)"

    def __init__(self, *args, **kwargs):
        kwargs['max_length'] = 104
        super(HandField, self).__init__(*args, **kwargs)

Many of Django's model fields accept options that they don't do anything
with. For example, you can pass both
:attr:`~django.db.models.Field.editable` and
:attr:`~django.db.models.DateField.auto_now` to a
:class:`django.db.models.DateField` and it will simply ignore the
:attr:`~django.db.models.Field.editable` parameter
(:attr:`~django.db.models.DateField.auto_now` being set implies
``editable=False``). No error is raised in this case.

This behavior simplifies the field classes, because they don't need to
check for options that aren't necessary. They just pass all the options to
the parent class and then don't use them later on. It's up to you whether
you want your fields to be more strict about the options they select, or to
use the simpler, more permissive behavior of the current fields.

from django.db import models

class HandField(models.Field):

    def __init__(self, *args, **kwargs):
        kwargs['max_length'] = 104
        super(HandField, self).__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super(HandField, self).deconstruct()
        del kwargs["max_length"]
        return name, path, args, kwargs

from django.db import models

class CommaSepField(models.Field):
    "Implements comma-separated storage of lists"

    def __init__(self, separator=",", *args, **kwargs):
        self.separator = separator
        super(CommaSepField, self).__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super(CommaSepField, self).deconstruct()
        # Only include kwarg if it's not the default
        if self.separator != ",":
            kwargs['separator'] = self.separator
        return name, path, args, kwargs

name, path, args, kwargs = my_field_instance.deconstruct()
new_instance = MyField(*args, **kwargs)
self.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)

class CustomCharField(models.CharField):
    ...

class CustomCharField(models.TextField):
    ...

class CustomCharField(models.CharField):
    ...

class CustomTextField(models.TextField):
    ...

description = _("String (up to %(max_length)s)")

Say you've created a PostgreSQL custom type called ``mytype``. You can
subclass ``Field`` and implement the :meth:`~Field.db_type` method, like so::

    from django.db import models

    class MytypeField(models.Field):
        def db_type(self, connection):
            return 'mytype'

Once you have ``MytypeField``, you can use it in any model, just like any other
``Field`` type::

    class Person(models.Model):
        name = models.CharField(max_length=80)
        something_else = MytypeField()

If you aim to build a database-agnostic application, you should account for
differences in database column types. For example, the date/time column type
in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
``datetime``. The simplest way to handle this in a :meth:`~Field.db_type`
method is to check the ``connection.settings_dict['ENGINE']`` attribute.

For example::

    class MyDateField(models.Field):
        def db_type(self, connection):
            if connection.settings_dict['ENGINE'] == 'django.db.backends.mysql':
                return 'datetime'
            else:
                return 'timestamp'

The :meth:`~Field.db_type` and :meth:`~Field.rel_db_type` methods are called by
Django when the framework constructs the ``CREATE TABLE`` statements for your
application -- that is, when you first create your tables. The methods are also
called when constructing a ``WHERE`` clause that includes the model field --
that is, when you retrieve data using QuerySet methods like ``get()``,
``filter()``, and ``exclude()`` and have the model field as an argument. They
are not called at any other time, so it can afford to execute slightly complex
code, such as the ``connection.settings_dict`` check in the above example.

Some database column types accept parameters, such as ``CHAR(25)``, where the
parameter ``25`` represents the maximum column length. In cases like these,
it's more flexible if the parameter is specified in the model rather than being
hard-coded in the ``db_type()`` method. For example, it wouldn't make much
sense to have a ``CharMaxlength25Field``, shown here::

    # This is a silly example of hard-coded parameters.
    class CharMaxlength25Field(models.Field):
        def db_type(self, connection):
            return 'char(25)'

    # In the model:
    class MyModel(models.Model):
        # ...
        my_field = CharMaxlength25Field()

The better way of doing this would be to make the parameter specifiable at run
time -- i.e., when the class is instantiated. To do that, just implement
``Field.__init__()``, like so::

    # This is a much more flexible example.
    class BetterCharField(models.Field):
        def __init__(self, max_length, *args, **kwargs):
            self.max_length = max_length
            super(BetterCharField, self).__init__(*args, **kwargs)

        def db_type(self, connection):
            return 'char(%s)' % self.max_length

    # In the model:
    class MyModel(models.Model):
        # ...
        my_field = BetterCharField(25)

Finally, if your column requires truly complex SQL setup, return ``None`` from
:meth:`.db_type`. This will cause Django's SQL creation code to skip
over this field. You are then responsible for creating the column in the right
table in some other way, of course, but this gives you a way to tell Django to
get out of the way.

The :meth:`~Field.rel_db_type` method is called by fields such as ``ForeignKey``
and ``OneToOneField`` that point to another field to determine their database
column data types. For example, if you have an ``UnsignedAutoField``, you also
need the foreign keys that point to that field to use the same data type::

    # MySQL unsigned integer (range 0 to 4294967295).
    class UnsignedAutoField(models.AutoField):
        def db_type(self, connection):
            return 'integer UNSIGNED AUTO_INCREMENT'

        def rel_db_type(self, connection):
            return 'integer UNSIGNED'

.. versionadded:: 1.10

    The :meth:`~Field.rel_db_type` method was added.

.. _converting-values-to-python-objects:

Converting values to Python objects

import re

from django.core.exceptions import ValidationError
from django.db import models
from django.utils.translation import ugettext_lazy as _

def parse_hand(hand_string):
    """Takes a string of cards and splits into a full hand."""
    p1 = re.compile('.{26}')
    p2 = re.compile('..')
    args = [p2.findall(x) for x in p1.findall(hand_string)]
    if len(args) != 4:
        raise ValidationError(_("Invalid input for a Hand instance"))
    return Hand(*args)

class HandField(models.Field):
    # ...

    def from_db_value(self, value, expression, connection, context):
        if value is None:
            return value
        return parse_hand(value)

    def to_python(self, value):
        if isinstance(value, Hand):
            return value

        if value is None:
            return value

        return parse_hand(value)

Since using a database requires conversion in both ways, if you override
:meth:`~Field.to_python` you also have to override :meth:`~Field.get_prep_value`
to convert Python objects back to query values.

For example::

    class HandField(models.Field):
        # ...

        def get_prep_value(self, value):
            return ''.join([''.join(l) for l in (value.north,
                    value.east, value.south, value.west)])

.. warning::

    If your custom field uses the ``CHAR``, ``VARCHAR`` or ``TEXT``
    types for MySQL, you must make sure that :meth:`.get_prep_value`
    always returns a string type. MySQL performs flexible and unexpected
    matching when a query is performed on these types and the provided
    value is an integer, which can cause queries to include unexpected
    objects in their results. This problem cannot occur if you always
    return a string type from :meth:`.get_prep_value`.

.. _converting-query-values-to-database-values:

Converting query values to database values

def get_db_prep_value(self, value, connection, prepared=False):
    value = super(BinaryField, self).get_db_prep_value(value, connection, prepared)
    if value is not None:
        return connection.Database.Binary(value)
    return value

If you want to preprocess the value just before saving, you can use
:meth:`~Field.pre_save`. For example, Django's
:class:`~django.db.models.DateTimeField` uses this method to set the attribute
correctly in the case of :attr:`~django.db.models.DateField.auto_now` or
:attr:`~django.db.models.DateField.auto_now_add`.

If you do override this method, you must return the value of the attribute at
the end. You should also update the model's attribute if you make any changes
to the value so that code holding references to the model will always see the
correct value.

.. _specifying-form-field-for-model-field:

Specifying the form field for a model field

class HandField(models.Field):
    # ...

    def formfield(self, **kwargs):
        # This is a fairly standard way to set up some defaults
        # while letting the caller override them.
        defaults = {'form_class': MyFormField}
        defaults.update(kwargs)
        return super(HandField, self).formfield(**defaults)

If you have created a :meth:`.db_type` method, you don't need to worry about
:meth:`.get_internal_type` -- it won't be used much. Sometimes, though, your
database storage is similar in type to some other field, so you can use that
other field's logic to create the right column.

For example::

    class HandField(models.Field):
        # ...

        def get_internal_type(self):
            return 'CharField'

No matter which database backend we are using, this will mean that
:djadmin:`migrate` and other SQL commands create the right column type for
storing a string.

If :meth:`.get_internal_type` returns a string that is not known to Django for
the database backend you are using -- that is, it doesn't appear in
``django.db.backends.<db_name>.base.DatabaseWrapper.data_types`` -- the string
will still be used by the serializer, but the default :meth:`~Field.db_type`
method will return ``None``. See the documentation of :meth:`~Field.db_type`
for reasons why this might be useful. Putting a descriptive string in as the
type of the field for the serializer is a useful idea if you're ever going to
be using the serializer output in some other place, outside of Django.

.. _converting-model-field-to-serialization:

Converting field data for serialization

class HandField(models.Field):
    # ...

    def value_to_string(self, obj):
        value = self.value_from_object(obj)
        return self.get_prep_value(value)

After adding the ``templatetags``  module, you will need to restart your
server before you can use the tags or filters in templates.

polls/
    __init__.py
    models.py
    templatetags/
        __init__.py
        poll_extras.py
    views.py

{% load poll_extras %}

from django import template

register = template.Library()

For a ton of examples, read the source code for Django's default filters
and tags. They're in ``django/template/defaultfilters.py`` and
``django/template/defaulttags.py``, respectively.

For more information on the :ttag:`load` tag, read its documentation.

def cut(value, arg):
    """Removes all values of arg from the given string"""
    return value.replace(arg, '')

{{ somevariable|cut:"0" }}

def lower(value): # Only one argument.
    """Converts a string into all lowercase"""
    return value.lower()

register.filter('cut', cut)
register.filter('lower', lower)

@register.filter(name='cut')
def cut(value, arg):
    return value.replace(arg, '')

@register.filter
def lower(value):
    return value.lower()

from django import template
from django.template.defaultfilters import stringfilter

register = template.Library()

@register.filter
@stringfilter
def lower(value):
    return value.lower()

Django's built-in filters have ``autoescape=True`` by default in order to
get the proper autoescaping behavior and avoid a cross-site script
vulnerability.

In older versions of Django, be careful when reusing Django's built-in
filters as ``autoescape`` defaults to ``None``. You'll need to pass
``autoescape=True`` to get autoescaping.

For example, if you wanted to write a custom filter called
``urlize_and_linebreaks`` that combined the :tfilter:`urlize` and
:tfilter:`linebreaksbr` filters, the filter would look like::

    from django.template.defaultfilters import linebreaksbr, urlize

    @register.filter(needs_autoescape=True)
    def urlize_and_linebreaks(text, autoescape=True):
        return linebreaksbr(
            urlize(text, autoescape=autoescape),
            autoescape=autoescape
        )

Then:

.. code-block:: html+django

    {{ comment|urlize_and_linebreaks }}

would be equivalent to:

.. code-block:: html+django

    {{ comment|urlize|linebreaksbr }}

@register.filter(expects_localtime=True)
def businesshours(value):
    try:
        return 9 <= value.hour < 17
    except AttributeError:
        return ''

import datetime
from django import template

register = template.Library()

@register.simple_tag
def current_time(format_string):
    return datetime.datetime.now().strftime(format_string)

@register.simple_tag(takes_context=True)
def current_time(context, format_string):
    timezone = context['timezone']
    return your_get_current_time_method(timezone, format_string)

register.simple_tag(lambda x: x - 1, name='minusone')

@register.simple_tag(name='minustwo')
def some_function(value):
    return value - 2

@register.simple_tag
def my_tag(a, b, *args, **kwargs):
    warning = kwargs['warning']
    profile = kwargs['profile']
    ...
    return ...

{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}

{% get_current_time "%Y-%m-%d %I:%M %p" as the_time %}
<p>The time is {{ the_time }}.</p>

{% show_results poll %}

<ul>
  <li>First choice</li>
  <li>Second choice</li>
  <li>Third choice</li>
</ul>

def show_results(poll):
    choices = poll.choice_set.all()
    return {'choices': choices}

<ul>
{% for choice in choices %}
    <li> {{ choice }} </li>
{% endfor %}
</ul>

# Here, register is a django.template.Library instance, as before
@register.inclusion_tag('results.html')
def show_results(poll):
    ...

from django.template.loader import get_template
t = get_template('results.html')
register.inclusion_tag(t)(show_results)

@register.inclusion_tag('link.html', takes_context=True)
def jump_link(context):
    return {
        'link': context['home_link'],
        'title': context['home_title'],
    }

Jump directly to <a href="{{ link }}">{{ title }}</a>.

{% jump_link %}

@register.inclusion_tag('my_template.html')
def my_tag(a, b, *args, **kwargs):
    warning = kwargs['warning']
    profile = kwargs['profile']
    ...
    return ...

{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}

``simple_tag`` can now store results in a template variable and should
be used instead.

@register.assignment_tag
def get_current_time(format_string):
    return datetime.datetime.now().strftime(format_string)

{% get_current_time "%Y-%m-%d %I:%M %p" as the_time %}
<p>The time is {{ the_time }}.</p>

<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>

from django import template

def do_current_time(parser, token):
    try:
        # split_contents() knows not to split quoted strings.
        tag_name, format_string = token.split_contents()
    except ValueError:
        raise template.TemplateSyntaxError(
            "%r tag requires a single argument" % token.contents.split()[0]
        )
    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
        raise template.TemplateSyntaxError(
            "%r tag's argument should be in quotes" % tag_name
        )
    return CurrentTimeNode(format_string[1:-1])

import datetime
from django import template

class CurrentTimeNode(template.Node):
    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        return datetime.datetime.now().strftime(self.format_string)

from django.template import Context

def render(self, context):
    # ...
    new_context = Context({'var': obj}, autoescape=context.autoescape)
    # ... Do something with new_context ...

def render(self, context):
    t = context.template.engine.get_template('small_fragment.html')
    return t.render(Context({'var': obj}, autoescape=context.autoescape))

{% for o in some_list %}
    <tr class="{% cycle 'row1' 'row2' %}">
        ...
    </tr>
{% endfor %}

import itertools
from django import template

class CycleNode(template.Node):
    def __init__(self, cyclevars):
        self.cycle_iter = itertools.cycle(cyclevars)

    def render(self, context):
        return next(self.cycle_iter)

class CycleNode(template.Node):
    def __init__(self, cyclevars):
        self.cyclevars = cyclevars

    def render(self, context):
        if self not in context.render_context:
            context.render_context[self] = itertools.cycle(self.cyclevars)
        cycle_iter = context.render_context[self]
        return next(cycle_iter)

register.tag('current_time', do_current_time)

@register.tag(name="current_time")
def do_current_time(parser, token):
    ...

@register.tag
def shout(parser, token):
    ...

<p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>

from django import template

def do_format_time(parser, token):
    try:
        # split_contents() knows not to split quoted strings.
        tag_name, date_to_be_formatted, format_string = token.split_contents()
    except ValueError:
        raise template.TemplateSyntaxError(
            "%r tag requires exactly two arguments" % token.contents.split()[0]
        )
    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
        raise template.TemplateSyntaxError(
            "%r tag's argument should be in quotes" % tag_name
        )
    return FormatTimeNode(date_to_be_formatted, format_string[1:-1])

class FormatTimeNode(template.Node):
    def __init__(self, date_to_be_formatted, format_string):
        self.date_to_be_formatted = template.Variable(date_to_be_formatted)
        self.format_string = format_string

    def render(self, context):
        try:
            actual_date = self.date_to_be_formatted.resolve(context)
            return actual_date.strftime(self.format_string)
        except template.VariableDoesNotExist:
            return ''

import datetime
from django import template

class CurrentTimeNode2(template.Node):
    def __init__(self, format_string):
        self.format_string = format_string
    def render(self, context):
        context['current_time'] = datetime.datetime.now().strftime(self.format_string)
        return ''

{% current_time "%Y-%M-%d %I:%M %p" %}<p>The time is {{ current_time }}.</p>

Any variable set in the context will only be available in the same
``block`` of the template in which it was assigned. This behavior is
intentional; it provides a scope for variables so that they don't conflict
with context in other blocks.

{% current_time "%Y-%M-%d %I:%M %p" as my_current_time %}
<p>The current time is {{ my_current_time }}.</p>

import re

class CurrentTimeNode3(template.Node):
    def __init__(self, format_string, var_name):
        self.format_string = format_string
        self.var_name = var_name
    def render(self, context):
        context[self.var_name] = datetime.datetime.now().strftime(self.format_string)
        return ''

def do_current_time(parser, token):
    # This version uses a regular expression to parse tag contents.
    try:
        # Splitting by None == splitting by spaces.
        tag_name, arg = token.contents.split(None, 1)
    except ValueError:
        raise template.TemplateSyntaxError(
            "%r tag requires arguments" % token.contents.split()[0]
        )
    m = re.search(r'(.*?) as (\w+)', arg)
    if not m:
        raise template.TemplateSyntaxError("%r tag had invalid arguments" % tag_name)
    format_string, var_name = m.groups()
    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):
        raise template.TemplateSyntaxError(
            "%r tag's argument should be in quotes" % tag_name
        )
    return CurrentTimeNode3(format_string[1:-1], var_name)

def do_comment(parser, token):
    nodelist = parser.parse(('endcomment',))
    parser.delete_first_token()
    return CommentNode()

class CommentNode(template.Node):
    def render(self, context):
        return ''

{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %}

def do_upper(parser, token):
    nodelist = parser.parse(('endupper',))
    parser.delete_first_token()
    return UpperNode(nodelist)

class UpperNode(template.Node):
    def __init__(self, nodelist):
        self.nodelist = nodelist
    def render(self, context):
        output = self.nodelist.render(context)
        return output.upper()

Server error emails are sent using the logging framework, so you can
customize this behavior by :doc:`customizing your logging configuration
</topics/logging>`.

In older versions, 404s were not ignored when the referer was equal to the
requested URL.

:class:`~django.middleware.common.BrokenLinkEmailsMiddleware` must appear
before other middleware that intercepts 404 errors, such as
:class:`~django.middleware.locale.LocaleMiddleware` or
:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`.
Put it towards the top of your :setting:`MIDDLEWARE` setting.

import re
IGNORABLE_404_URLS = [
    re.compile(r'\.(php|cgi)$'),
    re.compile(r'^/phpmyadmin/'),
]

import re
IGNORABLE_404_URLS = [
    re.compile(r'^/apple-touch-icon.*\.png$'),
    re.compile(r'^/favicon\.ico$'),
    re.compile(r'^/robots\.txt$'),
]

404 errors are logged using the logging framework. By default, these log
records are ignored, but you can use them for error reporting by writing a
handler and :doc:`configuring logging </topics/logging>` appropriately.

Filtering sensitive data is a hard problem, and it's nearly impossible to
guarantee that sensitive won't leak into an error report. Therefore, error
reports should only be available to trusted team members and you should
avoid transmitting error reports unencrypted over the Internet (such as
through email).

If a function (either a view or any regular callback) in your code uses
local variables susceptible to contain sensitive information, you may
prevent the values of those variables from being included in error reports
using the ``sensitive_variables`` decorator::

    from django.views.decorators.debug import sensitive_variables

    @sensitive_variables('user', 'pw', 'cc')
    def process_info(user):
        pw = user.pass_word
        cc = user.credit_card_number
        name = user.name
        ...

In the above example, the values for the ``user``, ``pw`` and ``cc``
variables will be hidden and replaced with stars (`**********`) in the
error reports, whereas the value of the ``name`` variable will be
disclosed.

To systematically hide all local variables of a function from error logs,
do not provide any argument to the ``sensitive_variables`` decorator::

    @sensitive_variables()
    def my_function():
        ...

.. admonition:: When using multiple decorators

    If the variable you want to hide is also a function argument (e.g.
    '``user``’ in the following example), and if the decorated function has
    multiple decorators, then make sure to place ``@sensitive_variables``
    at the top of the decorator chain. This way it will also hide the
    function argument as it gets passed through the other decorators::

        @sensitive_variables('user', 'pw', 'cc')
        @some_decorator
        @another_decorator
        def process_info(user):
            ...

If one of your views receives an :class:`~django.http.HttpRequest` object
with :attr:`POST parameters<django.http.HttpRequest.POST>` susceptible to
contain sensitive information, you may prevent the values of those
parameters from being included in the error reports using the
``sensitive_post_parameters`` decorator::

    from django.views.decorators.debug import sensitive_post_parameters

    @sensitive_post_parameters('pass_word', 'credit_card_number')
    def record_user_profile(request):
        UserProfile.create(
            user=request.user,
            password=request.POST['pass_word'],
            credit_card=request.POST['credit_card_number'],
            name=request.POST['name'],
        )
        ...

In the above example, the values for the ``pass_word`` and
``credit_card_number`` POST parameters will be hidden and replaced with
stars (`**********`) in the request's representation inside the error
reports, whereas the value of the ``name`` parameter will be disclosed.

To systematically hide all POST parameters of a request in error reports,
do not provide any argument to the ``sensitive_post_parameters`` decorator::

    @sensitive_post_parameters()
    def my_view(request):
        ...

All POST parameters are systematically filtered out of error reports for
certain :mod:`django.contrib.auth.views` views (``login``,
``password_reset_confirm``, ``password_change``, and ``add_view`` and
``user_change_password`` in the ``auth`` admin) to prevent the leaking of
sensitive information such as user passwords.

DEFAULT_EXCEPTION_REPORTER_FILTER = 'path.to.your.CustomExceptionReporterFilter'

def my_view(request):
    if request.user.is_authenticated:
        request.exception_reporter_filter = CustomExceptionReporterFilter()
    ...

Returns ``True`` to activate the filtering operated in the other methods.
By default the filter is active if :setting:`DEBUG` is ``False``.

Returns the filtered dictionary of POST parameters. By default it replaces
the values of sensitive parameters with stars (`**********`).

Returns the filtered dictionary of local variables for the given traceback
frame. By default it replaces the values of sensitive variables with stars
(`**********`).

You can also set up custom error reporting by writing a custom piece of
:ref:`exception middleware <exception-middleware>`. If you do write custom
error handling, it's a good idea to emulate Django's built-in error handling
and only report/log errors if :setting:`DEBUG` is ``False``.

The `Django community aggregator`_, where we aggregate content from the
global Django community. Many writers in the aggregator write this sort of
how-to material.

.. _django community aggregator: https://www.djangoproject.com/community/

[
  {
    "model": "myapp.person",
    "pk": 1,
    "fields": {
      "first_name": "John",
      "last_name": "Lennon"
    }
  },
  {
    "model": "myapp.person",
    "pk": 2,
    "fields": {
      "first_name": "Paul",
      "last_name": "McCartney"
    }
  }
]

- model: myapp.person
  pk: 1
  fields:
    first_name: John
    last_name: Lennon
- model: myapp.person
  pk: 2
  fields:
    first_name: Paul
    last_name: McCartney

Fixtures are also used by the :ref:`testing framework
<topics-testing-fixtures>` to help set up a consistent test environment.

$ python manage.py inspectdb

$ python manage.py inspectdb > models.py

class Person(models.Model):
    id = models.IntegerField(primary_key=True)
    first_name = models.CharField(max_length=70)
    class Meta:
       managed = False
       db_table = 'CENSUS_PERSONS'

$ python manage.py migrate

import csv
from django.http import HttpResponse

def some_view(request):
    # Create the HttpResponse object with the appropriate CSV header.
    response = HttpResponse(content_type='text/csv')
    response['Content-Disposition'] = 'attachment; filename="somefilename.csv"'

    writer = csv.writer(response)
    writer.writerow(['First row', 'Foo', 'Bar', 'Baz'])
    writer.writerow(['Second row', 'A', 'B', 'C', '"Testing"', "Here's a quote"])

    return response

Python 2's :mod:`csv` module does not support Unicode input. Since Django
uses Unicode internally this means strings read from sources such as
:class:`~django.http.HttpRequest` are potentially problematic. There are a
few options for handling this:

* Manually encode all Unicode objects to a compatible encoding.

* Use the ``UnicodeWriter`` class provided in the `csv module's examples
  section`_.

* Use the `python-unicodecsv module`_, which aims to be a drop-in
  replacement for :mod:`csv` that gracefully handles Unicode.

For more information, see the Python documentation of the :mod:`csv` module.

.. _`csv module's examples section`: https://docs.python.org/2/library/csv.html#examples
.. _`python-unicodecsv module`: https://github.com/jdunck/python-unicodecsv

import csv

from django.utils.six.moves import range
from django.http import StreamingHttpResponse

class Echo(object):
    """An object that implements just the write method of the file-like
    interface.
    """
    def write(self, value):
        """Write the value by returning it, instead of storing in a buffer."""
        return value

def some_streaming_csv_view(request):
    """A view that streams a large CSV file."""
    # Generate a sequence of rows. The range is based on the maximum number of
    # rows that can be handled by a single sheet in most spreadsheet
    # applications.
    rows = (["Row {}".format(idx), str(idx)] for idx in range(65536))
    pseudo_buffer = Echo()
    writer = csv.writer(pseudo_buffer)
    response = StreamingHttpResponse((writer.writerow(row) for row in rows),
                                     content_type="text/csv")
    response['Content-Disposition'] = 'attachment; filename="somefilename.csv"'
    return response

from django.http import HttpResponse
from django.template import loader, Context

def some_view(request):
    # Create the HttpResponse object with the appropriate CSV header.
    response = HttpResponse(content_type='text/csv')
    response['Content-Disposition'] = 'attachment; filename="somefilename.csv"'

    # The data is hard-coded here, but you could load it from a database or
    # some other source.
    csv_data = (
        ('First row', 'Foo', 'Bar', 'Baz'),
        ('Second row', 'A', 'B', 'C', '"Testing"', "Here's a quote"),
    )

    t = loader.get_template('my_template_name.txt')
    c = Context({
        'data': csv_data,
    })
    response.write(t.render(c))
    return response

{% for row in data %}"{{ row.0|addslashes }}", "{{ row.1|addslashes }}", "{{ row.2|addslashes }}", "{{ row.3|addslashes }}", "{{ row.4|addslashes }}"
{% endfor %}

$ pip install reportlab

>>> import reportlab

from reportlab.pdfgen import canvas
from django.http import HttpResponse

def some_view(request):
    # Create the HttpResponse object with the appropriate PDF headers.
    response = HttpResponse(content_type='application/pdf')
    response['Content-Disposition'] = 'attachment; filename="somefilename.pdf"'

    # Create the PDF object, using the response object as its "file."
    p = canvas.Canvas(response)

    # Draw things on the PDF. Here's where the PDF generation happens.
    # See the ReportLab documentation for the full list of functionality.
    p.drawString(100, 100, "Hello world.")

    # Close the PDF object cleanly, and we're done.
    p.showPage()
    p.save()
    return response

ReportLab is not thread-safe. Some of our users have reported odd issues
with building PDF-generating Django views that are accessed by many people
at the same time.

from io import BytesIO
from reportlab.pdfgen import canvas
from django.http import HttpResponse

def some_view(request):
    # Create the HttpResponse object with the appropriate PDF headers.
    response = HttpResponse(content_type='application/pdf')
    response['Content-Disposition'] = 'attachment; filename="somefilename.pdf"'

    buffer = BytesIO()

    # Create the PDF object, using the BytesIO object as its "file."
    p = canvas.Canvas(buffer)

    # Draw things on the PDF. Here's where the PDF generation happens.
    # See the ReportLab documentation for the full list of functionality.
    p.drawString(100, 100, "Hello world.")

    # Close the PDF object cleanly.
    p.showPage()
    p.save()

    # Get the value of the BytesIO buffer and write it to the response.
    pdf = buffer.getvalue()
    buffer.close()
    response.write(pdf)
    return response

$ python -Wall manage.py test

$ PYTHONWARNINGS=all py.test tests --capture=no

$ python -Wall manage.py test

python --version

pip install virtualenvwrapper-win

mkvirtualenv myproject

workon myproject

pip install django

from django.db import migrations

def forwards(apps, schema_editor):
    if not schema_editor.connection.alias == 'default':
        return
    # Your migration code goes here

class Migration(migrations.Migration):

    dependencies = [
        # Dependencies to other migrations
    ]

    operations = [
        migrations.RunPython(forwards),
    ]

class MyRouter(object):

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        if 'target_db' in hints:
            return db == hints['target_db']
        return True

from django.db import migrations

def forwards(apps, schema_editor):
    # Your migration code goes here
    ...

class Migration(migrations.Migration):

    dependencies = [
        # Dependencies to other migrations
    ]

    operations = [
        migrations.RunPython(forwards, hints={'target_db': 'default'}),
    ]

.. versionadded:: 1.10

On databases that support DDL transactions (SQLite and PostgreSQL), migrations
will run inside a transaction by default. For use cases such as performing data
migrations on large tables, you may want to prevent a migration from running in
a transaction by setting the ``atomic`` attribute to ``False``::

    from django.db import migrations

    class Migration(migrations.Migration):
        atomic = False

Within such a migration, all operations are run without a transaction. It's
possible to execute parts of the migration inside a transaction using
:func:`~django.db.transaction.atomic()` or by passing ``atomic=True`` to
``RunPython``.

Here's an example of a non-atomic data migration that updates a large table in
smaller batches::

    import uuid

    from django.db import migrations, transaction

    def gen_uuid(apps, schema_editor):
        MyModel = apps.get_model('myapp', 'MyModel')
        while MyModel.objects.filter(uuid__isnull=True).exists():
            with transaction.atomic():
                for row in MyModel.objects.filter(uuid__isnull=True)[:1000]:
                    row.uuid = uuid.uuid4()
                    row.save()

    class Migration(migrations.Migration):
        atomic = False

        operations = [
            migrations.RunPython(gen_uuid),
        ]

The ``atomic`` attribute doesn't have an effect on databases that don't support
DDL transactions (e.g. MySQL, Oracle).

Controlling the order of migrations
===================================

Django determines the order in which migrations should be applied not by the
filename of each migration, but by building a graph using two properties on the
``Migration`` class: ``dependencies`` and ``run_before``.

If you've used the :djadmin:`makemigrations` command you've probably
already seen ``dependencies`` in action because auto-created
migrations have this defined as part of their creation process.

The ``dependencies`` property is declared like this::

    from django.db import migrations

    class Migration(migrations.Migration):

        dependencies = [
            ('myapp', '0123_the_previous_migration'),
        ]

Usually this will be enough, but from time to time you may need to
ensure that your migration runs *before* other migrations. This is
useful, for example, to make third-party apps' migrations run *after*
your :setting:`AUTH_USER_MODEL` replacement.

To achieve this, place all migrations that should depend on yours in
the ``run_before`` attribute on your ``Migration`` class::

    class Migration(migrations.Migration):
        ...

        run_before = [
            ('third_party_app', '0001_do_awesome'),
        ]

Prefer using ``dependencies`` over ``run_before`` when possible. You should
only use ``run_before`` if it is undesirable or impractical to specify
``dependencies`` in the migration which you want to run after the one you are
writing.

Migrating data between third-party apps
=======================================

You can use a data migration to move data from one third-party application to
another.

If you plan to remove the old app later, you'll need to set the ``dependencies``
property based on whether or not the old app is installed. Otherwise, you'll
have missing dependencies once you uninstall the old app. Similarly, you'll
need to catch :exc:`LookupError` in the ``apps.get_model()`` call that
retrieves models from the old app. This approach allows you to deploy your
project anywhere without first installing and then uninstalling the old app.

Here's a sample migration:

.. snippet::
    :filename: myapp/migrations/0124_move_old_app_to_new_app.py

    from django.apps import apps as global_apps
    from django.db import migrations

    def forwards(apps, schema_editor):
        try:
            OldModel = apps.get_model('old_app', 'OldModel')
        except LookupError:
            # The old app isn't installed.
            return

        NewModel = apps.get_model('new_app', 'NewModel')
        NewModel.objects.bulk_create(
            NewModel(new_attribute=old_object.old_attribute)
            for old_object in OldModel.objects.all()
        )

    class Migration(migrations.Migration):
        operations = [
            migrations.RunPython(forwards, migrations.RunPython.noop),
        ]
        dependencies = [
            ('myapp', '0123_the_previous_migration'),
            ('new_app', '0001_initial'),
        ]

        if global_apps.is_installed('old_app'):
            dependencies.append(('old_app', '0001_initial'))

Also consider what you want to happen when the migration is unapplied. You
could either do nothing (as in the example above) or remove some or all of the
data from the new application. Adjust the second argument of the
:mod:`~django.db.migrations.operations.RunPython` operation accordingly.

Changing an unmanaged model to managed
======================================

If you want to change an unmanaged model (:attr:`managed=False
<django.db.models.Options.managed>`) to managed, you must remove
``managed=False`` and generate a migration before making other schema-related
changes to the model, since schema changes that appear in the migration that
contains the operation to change ``Meta.managed`` may not be applied.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Deprecation (`大一小学期/Week_3-Python/exam/2016/docs/internals/deprecation.txt`)

===========================
Django Deprecation Timeline
===========================

This document outlines when various pieces of Django will be removed or altered
in a backward incompatible way, following their deprecation, as per the
:ref:`deprecation policy `. More details
about each item can often be found in the release notes of two versions prior.

.. _deprecation-removed-in-2.0:

2.0
---

See the :ref:`Django 1.9 release notes<deprecated-features-1.9>` for more
details on these changes.

* The ``weak`` argument to ``django.dispatch.signals.Signal.disconnect()`` will
  be removed.

* The ``django.forms.extras`` package will be removed.

* The ``assignment_tag`` helper will be removed.

* The ``host`` argument to ``assertsRedirects`` will be removed. The
  compatibility layer which allows absolute URLs to be considered equal to
  relative ones when the path is identical will also be removed.

* ``Field.rel`` will be removed.

* ``Field.remote_field.to`` attribute will be removed.

* The ``on_delete`` argument for ``ForeignKey`` and ``OneToOneField``  will be
  required.

* ``django.db.models.fields.add_lazy_relation()`` will be removed.

* When time zone support is enabled, database backends that don't support time
  zones won't convert aware datetimes to naive values in UTC anymore when such
  values are passed as parameters to SQL queries executed outside of the ORM,
  e.g. with ``cursor.execute()``.

* The ``django.contrib.auth.tests.utils.skipIfCustomUser()`` decorator will be
  removed.

* The ``GeoManager`` and ``GeoQuerySet`` classes will be removed.

* The ``django.contrib.gis.geoip`` module will be removed.

* The ``supports_recursion`` check for template loaders will be removed from:

  * ``django.template.engine.Engine.find_template()``
  * ``django.template.loader_tags.ExtendsNode.find_template()``
  * ``django.template.loaders.base.Loader.supports_recursion()``
  * ``django.template.loaders.cached.Loader.supports_recursion()``

* The ``load_template()`` and ``load_template_sources()`` template loader
  methods will be removed.

* The ``template_dirs`` argument for template loaders will be removed:

  * ``django.template.loaders.base.Loader.get_template()``
  * ``django.template.loaders.cached.Loader.cache_key()``
  * ``django.template.loaders.cached.Loader.get_template()``
  * ``django.template.loaders.cached.Loader.get_template_sources()``
  * ``django.template.loaders.filesystem.Loader.get_template_sources()``

* The ``django.template.loaders.base.Loader.__call__()`` method will be
  removed.

* Support for custom error views with a single positional parameter will be
  dropped.

* The ``mime_type`` attribute of ``django.utils.feedgenerator.Atom1Feed`` and
  ``django.utils.feedgenerator.RssFeed`` will be removed in favor of
  ``content_type``.

* The ``app_name`` argument to :func:`~django.conf.urls.include()` will be
  removed.

* Support for passing a 3-tuple as the first argument to ``include()`` will
  be removed.

* Support for setting a URL instance namespace without an application
  namespace will be removed.

* ``Field._get_val_from_obj()`` will be removed in favor of
  ``Field.value_from_object()``.

* ``django.template.loaders.eggs.Loader`` will be removed.

* The ``current_app`` parameter to the ``contrib.auth`` views will be removed.

* The ``callable_obj`` keyword argument to
  ``SimpleTestCase.assertRaisesMessage()`` will be removed.

* Support for the ``allow_tags`` attribute on ``ModelAdmin`` methods will be
  removed.

* The ``enclosure`` keyword argument to ``SyndicationFeed.add_item()`` will be
  removed.

* The ``django.template.loader.LoaderOrigin`` and
  ``django.template.base.StringOrigin`` aliases for
  ``django.template.base.Origin`` will be removed.

See the :ref:`Django 1.10 release notes <deprecated-features-1.10>` for more
details on these changes.

* The ``makemigrations --exit`` option will be removed.

* Support for direct assignment to a reverse foreign key or many-to-many
  relation will be removed.

* The ``get_srid()`` and ``set_srid()`` methods of
  ``django.contrib.gis.geos.GEOSGeometry`` will be removed.

* The ``get_x()``, ``set_x()``, ``get_y()``, ``set_y()``, ``get_z()``, and
  ``set_z()`` methods of ``django.contrib.gis.geos.Point`` will be removed.

* The ``get_coords()`` and ``set_coords()`` methods of
  ``django.contrib.gis.geos.Point`` will be removed.

* The ``cascaded_union`` property of ``django.contrib.gis.geos.MultiPolygon``
  will be removed.

* ``django.utils.functional.allow_lazy()`` will be removed.

* The ``shell --plain`` option will be removed.

* The ``django.core.urlresolvers`` module will be removed.

* The model ``CommaSeparatedIntegerField`` will be removed. A stub field will
  remain for compatibility with historical migrations.

* Support for the template ``Context.has_key()`` method will be removed.

* Support for the ``django.core.files.storage.Storage.accessed_time()``,
  ``created_time()``, and ``modified_time()`` methods will be removed.

* Support for query lookups using the model name when
  ``Meta.default_related_name`` is set will be removed.

* The ``__search`` query lookup and the
  ``DatabaseOperations.fulltext_search_sql()`` method will be removed.

* The shim for supporting custom related manager classes without a
  ``_apply_rel_filters()`` method will be removed.

* Using ``User.is_authenticated()`` and ``User.is_anonymous()`` as methods
  will no longer be supported.

* The private attribute ``virtual_fields`` of ``Model._meta`` will be removed.

* The private keyword arguments ``virtual_only`` in
  ``Field.contribute_to_class()`` and ``virtual`` in
  ``Model._meta.add_field()`` will be removed.

* The ``javascript_catalog()`` and ``json_catalog()`` views will be removed.

* The ``django.contrib.gis.utils.precision_wkt()`` function will be removed.

* In multi-table inheritance, implicit promotion of a ``OneToOneField`` to a
  ``parent_link`` will be removed.

* Support for ``Widget._format_value()`` will be removed.

* ``FileField`` methods ``get_directory_name()`` and ``get_filename()`` will be
  removed.

* The ``mark_for_escaping()`` function and the classes it uses: ``EscapeData``,
  ``EscapeBytes``, ``EscapeText``, ``EscapeString``, and ``EscapeUnicode`` will
  be removed.

* The ``escape`` filter will change to use
  ``django.utils.html.conditional_escape()``.

* ``Manager.use_for_related_fields`` will be removed.

* Model ``Manager`` inheritance will follow MRO inheritance rules and the
  ``Meta.manager_inheritance_from_future`` to opt-in to this behavior will be
  removed.

* Support for old-style middleware using ``settings.MIDDLEWARE_CLASSES`` will
  be removed.

.. _deprecation-removed-in-1.10:

1.10
----

See the :ref:`Django 1.8 release notes<deprecated-features-1.8>` for more
details on these changes.

* Support for calling a ``SQLCompiler`` directly as an alias for calling its
  ``quote_name_unless_alias`` method will be removed.

* ``cycle`` and ``firstof`` template tags will be removed from the ``future``
  template tag library (used during the 1.6/1.7 deprecation period).

* ``django.conf.urls.patterns()`` will be removed.

* Support for the ``prefix`` argument to
  ``django.conf.urls.i18n.i18n_patterns()`` will be removed.

* ``SimpleTestCase.urls`` will be removed.

* Using an incorrect count of unpacked values in the ``for`` template tag
  will raise an exception rather than fail silently.

* The ability to reverse URLs using a dotted Python path will be removed.

* The ability to use a dotted Python path for the ``LOGIN_URL`` and
  ``LOGIN_REDIRECT_URL`` settings will be removed.

* Support for :py:mod:`optparse` will be dropped for custom management commands
  (replaced by :py:mod:`argparse`).

* The class ``django.core.management.NoArgsCommand`` will be removed. Use
  :class:`~django.core.management.BaseCommand` instead, which takes no arguments
  by default.

* ``django.core.context_processors`` module will be removed.

* ``django.db.models.sql.aggregates`` module will be removed.

* ``django.contrib.gis.db.models.sql.aggregates`` module will be removed.

* The following methods and properties of ``django.db.sql.query.Query`` will
  be removed:

  * Properties: ``aggregates`` and ``aggregate_select``
  * Methods: ``add_aggregate``, ``set_aggregate_mask``, and
    ``append_aggregate_mask``.

* ``django.template.resolve_variable`` will be removed.

* The following private APIs will be removed from
  :class:`django.db.models.options.Options` (``Model._meta``):

  * ``get_field_by_name()``
  * ``get_all_field_names()``
  * ``get_fields_with_model()``
  * ``get_concrete_fields_with_model()``
  * ``get_m2m_with_model()``
  * ``get_all_related_objects()``
  * ``get_all_related_objects_with_model()``
  * ``get_all_related_many_to_many_objects()``
  * ``get_all_related_m2m_objects_with_model()``

* The ``error_message`` argument of ``django.forms.RegexField`` will be removed.

* The ``unordered_list`` filter will no longer support old style lists.

* Support for string ``view`` arguments to ``url()`` will be removed.

* The backward compatible shim  to rename ``django.forms.Form._has_changed()``
  to ``has_changed()`` will be removed.

* The ``removetags`` template filter will be removed.

* The ``remove_tags()`` and ``strip_entities()`` functions in
  ``django.utils.html`` will be removed.

* The ``is_admin_site`` argument to
  ``django.contrib.auth.views.password_reset()`` will be removed.

* ``django.db.models.field.subclassing.SubfieldBase`` will be removed.

* ``django.utils.checksums`` will be removed; its functionality is included
  in django-localflavor 1.1+.

* The ``original_content_type_id`` attribute on
  ``django.contrib.admin.helpers.InlineAdminForm`` will be removed.

* The backwards compatibility shim to allow ``FormMixin.get_form()`` to be
  defined with no default value for its ``form_class`` argument will be removed.

* The following settings will be removed:

  * ``ALLOWED_INCLUDE_ROOTS``
  * ``TEMPLATE_CONTEXT_PROCESSORS``
  * ``TEMPLATE_DEBUG``
  * ``TEMPLATE_DIRS``
  * ``TEMPLATE_LOADERS``
  * ``TEMPLATE_STRING_IF_INVALID``

* The backwards compatibility alias ``django.template.loader.BaseLoader`` will
  be removed.

* Django template objects returned by
  :func:`~django.template.loader.get_template` and
  :func:`~django.template.loader.select_template` won't accept a
  :class:`~django.template.Context` in their
  :meth:`~django.template.backends.base.Template.render()` method anymore.

* :doc:`Template response APIs </ref/template-response>` will enforce the use
  of :class:`dict` and backend-dependent template objects instead of
  :class:`~django.template.Context` and :class:`~django.template.Template`
  respectively.

* The ``current_app`` parameter for the following function and classes will be
  removed:

  * ``django.shortcuts.render()``
  * ``django.template.Context()``
  * ``django.template.RequestContext()``
  * ``django.template.response.TemplateResponse()``

* The ``dictionary`` and ``context_instance`` parameters for the following
  functions will be removed:

  * ``django.shortcuts.render()``
  * ``django.shortcuts.render_to_response()``
  * ``django.template.loader.render_to_string()``

* The ``dirs`` parameter for the following functions will be removed:

  * ``django.template.loader.get_template()``
  * ``django.template.loader.select_template()``
  * ``django.shortcuts.render()``
  * ``django.shortcuts.render_to_response()``

* Session verification will be enabled regardless of whether or not
  ``'django.contrib.auth.middleware.SessionAuthenticationMiddleware'`` is in
  ``MIDDLEWARE_CLASSES``.

* Private attribute ``django.db.models.Field.related`` will be removed.

* The ``--list`` option of the ``migrate`` management command will be removed.

* The ``ssi`` template tag will be removed.

* Support for the ``=`` comparison operator in the ``if`` template tag will be
  removed.

* The backwards compatibility shims to allow ``Storage.get_available_name()``
  and ``Storage.save()`` to be defined without a ``max_length`` argument will
  be removed.

* Support for the legacy ``%(<foo>)s`` syntax in ``ModelFormMixin.success_url``
  will be removed.

* ``GeoQuerySet`` aggregate methods ``collect()``, ``extent()``, ``extent3d()``,
  ``make_line()``, and ``unionagg()`` will be removed.

* Ability to specify ``ContentType.name`` when creating a content type instance
  will be removed.

* Support for the old signature of ``allow_migrate`` will be removed. It changed
  from ``allow_migrate(self, db, model)`` to
  ``allow_migrate(self, db, app_label, model_name=None, **hints)``.

* Support for the syntax of ``{% cycle %}`` that uses comma-separated arguments
  will be removed.

* The warning that :class:`~django.core.signing.Signer` issues when given an
  invalid separator will become an exception.

.. _deprecation-removed-in-1.9:

1.9
---

See the :ref:`Django 1.7 release notes<deprecated-features-1.7>` for more
details on these changes.

* ``django.utils.dictconfig`` will be removed.

* ``django.utils.importlib`` will be removed.

* ``django.utils.tzinfo`` will be removed.

* ``django.utils.unittest`` will be removed.

* The ``syncdb`` command will be removed.

* ``django.db.models.signals.pre_syncdb`` and
  ``django.db.models.signals.post_syncdb`` will be removed.

* ``allow_syncdb`` on database routers will no longer automatically become
  ``allow_migrate``.

* Automatic syncing of apps without migrations will be removed. Migrations will
  become compulsory for all apps unless you pass the ``--run-syncdb`` option to
  ``migrate``.

* The SQL management commands for apps without migrations, ``sql``, ``sqlall``,
  ``sqlclear``, ``sqldropindexes``, and ``sqlindexes``, will be removed.

* Support for automatic loading of ``initial_data`` fixtures and initial SQL
  data will be removed.

* All models will need to be defined inside an installed application or
  declare an explicit :attr:`~django.db.models.Options.app_label`.
  Furthermore, it won't be possible to import them before their application
  is loaded. In particular, it won't be possible to import models inside
  the root package of their application.

* The model and form ``IPAddressField`` will be removed. A stub field will
  remain for compatibility with historical migrations.

* ``AppCommand.handle_app()`` will no longer be supported.

* ``RequestSite`` and ``get_current_site()`` will no longer be importable from
  ``django.contrib.sites.models``.

* FastCGI support via the ``runfcgi`` management command will be
  removed. Please deploy your project using WSGI.

* ``django.utils.datastructures.SortedDict`` will be removed. Use
  :class:`collections.OrderedDict` from the Python standard library instead.

* ``ModelAdmin.declared_fieldsets`` will be removed.

* Instances of ``util.py`` in the Django codebase have been renamed to
  ``utils.py`` in an effort to unify all util and utils references.
  The modules that provided backwards compatibility will be removed:

  * ``django.contrib.admin.util``
  * ``django.contrib.gis.db.backends.util``
  * ``django.db.backends.util``
  * ``django.forms.util``

* ``ModelAdmin.get_formsets`` will be removed.

* The backward compatibility shim introduced to rename the
  ``BaseMemcachedCache._get_memcache_timeout()`` method to
  ``get_backend_timeout()`` will be removed.

* The ``--natural`` and ``-n`` options for :djadmin:`dumpdata` will be removed.

* The ``use_natural_keys`` argument for ``serializers.serialize()`` will be
  removed.

* Private API ``django.forms.forms.get_declared_fields()`` will be removed.

* The ability to use a ``SplitDateTimeWidget`` with ``DateTimeField`` will be
  removed.

* The ``WSGIRequest.REQUEST`` property will be removed.

* The class ``django.utils.datastructures.MergeDict`` will be removed.

* The ``zh-cn`` and ``zh-tw`` language codes will be removed and have been
  replaced by the ``zh-hans`` and ``zh-hant`` language code respectively.

* The internal ``django.utils.functional.memoize`` will be removed.

* ``django.core.cache.get_cache`` will be removed. Add suitable entries
  to :setting:`CACHES` and use :data:`django.core.cache.caches` instead.

* ``django.db.models.loading`` will be removed.

* Passing callable arguments to querysets will no longer be possible.

* ``BaseCommand.requires_model_validation`` will be removed in favor of
  ``requires_system_checks``. Admin validators will be replaced by admin
  checks.

* The ``ModelAdmin.validator_class`` and ``default_validator_class`` attributes
  will be removed.

* ``ModelAdmin.validate()`` will be removed.

* ``django.db.backends.DatabaseValidation.validate_field`` will be removed in
  favor of the ``check_field`` method.

* The ``validate`` management command will be removed.

* ``django.utils.module_loading.import_by_path`` will be removed in favor of
  ``django.utils.module_loading.import_string``.

* ``ssi`` and ``url`` template tags will be removed from the ``future`` template
  tag library (used during the 1.3/1.4 deprecation period).

* ``django.utils.text.javascript_quote`` will be removed.

* Database test settings as independent entries in the database settings,
  prefixed by ``TEST_``, will no longer be supported.

* The `cache_choices` option to :class:`~django.forms.ModelChoiceField` and
  :class:`~django.forms.ModelMultipleChoiceField` will be removed.

* The default value of the
  :attr:`RedirectView.permanent <django.views.generic.base.RedirectView.permanent>`
  attribute will change from ``True`` to ``False``.

* ``django.contrib.sitemaps.FlatPageSitemap`` will be removed in favor of
  ``django.contrib.flatpages.sitemaps.FlatPageSitemap``.

* Private API ``django.test.utils.TestTemplateLoader`` will be removed.

* The ``django.contrib.contenttypes.generic`` module will be removed.

* Private APIs ``django.db.models.sql.where.WhereNode.make_atom()`` and
  ``django.db.models.sql.where.Constraint`` will be removed.

.. _deprecation-removed-in-1.8:

1.8
---

See the :ref:`Django 1.6 release notes<deprecated-features-1.6>` for more
details on these changes.

* ``django.contrib.comments`` will be removed.

* The following transaction management APIs will be removed:

  - ``TransactionMiddleware``,
  - the decorators and context managers ``autocommit``, ``commit_on_success``,
    and ``commit_manually``, defined in ``django.db.transaction``,
  - the functions ``commit_unless_managed`` and ``rollback_unless_managed``,
    also defined in ``django.db.transaction``,
  - the ``TRANSACTIONS_MANAGED`` setting.

* The :ttag:`cycle` and :ttag:`firstof` template tags will auto-escape their
  arguments. In 1.6 and 1.7, this behavior is provided by the version of these
  tags in the ``future`` template tag library.

* The ``SEND_BROKEN_LINK_EMAILS`` setting will be removed. Add the
  :class:`django.middleware.common.BrokenLinkEmailsMiddleware` middleware to
  your :setting:`MIDDLEWARE_CLASSES` setting instead.

* ``django.middleware.doc.XViewMiddleware`` will be removed. Use
  ``django.contrib.admindocs.middleware.XViewMiddleware`` instead.

* ``Model._meta.module_name`` was renamed to ``model_name``.

* Remove the backward compatible shims introduced to rename ``get_query_set``
  and similar queryset methods. This affects the following classes:
  ``BaseModelAdmin``, ``ChangeList``, ``BaseCommentNode``,
  ``GenericForeignKey``, ``Manager``, ``SingleRelatedObjectDescriptor`` and
  ``ReverseSingleRelatedObjectDescriptor``.

* Remove the backward compatible shims introduced to rename the attributes
  ``ChangeList.root_query_set`` and ``ChangeList.query_set``.

* ``django.views.defaults.shortcut`` will be removed, as part of the
  goal of removing all ``django.contrib`` references from the core
  Django codebase. Instead use
  ``django.contrib.contenttypes.views.shortcut``. ``django.conf.urls.shortcut``
  will also be removed.

* Support for the Python Imaging Library (PIL) module will be removed, as it
  no longer appears to be actively maintained & does not work on Python 3.
  You are advised to install `Pillow`_, which should be used instead.

  .. _`Pillow`: https://pypi.python.org/pypi/Pillow

* The following private APIs will be removed:

  - ``django.db.backend``
  - ``django.db.close_connection()``
  - ``django.db.backends.creation.BaseDatabaseCreation.set_autocommit()``
  - ``django.db.transaction.is_managed()``
  - ``django.db.transaction.managed()``

* ``django.forms.widgets.RadioInput`` will be removed in favor of
  ``django.forms.widgets.RadioChoiceInput``.

* The module ``django.test.simple`` and the class
  ``django.test.simple.DjangoTestSuiteRunner`` will be removed. Instead use
  ``django.test.runner.DiscoverRunner``.

* The module ``django.test._doctest`` will be removed. Instead use the doctest
  module from the Python standard library.

* The ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting will be removed.

* Usage of the hard-coded *Hold down "Control", or "Command" on a Mac, to select
  more than one.* string to override or append to user-provided ``help_text`` in
  forms for ManyToMany model fields will not be performed by Django anymore
  either at the model or forms layer.

* The ``Model._meta.get_(add|change|delete)_permission`` methods will
  be removed.

* The session key ``django_language`` will no longer be read for backwards
  compatibility.

* Geographic Sitemaps will be removed
  (``django.contrib.gis.sitemaps.views.index`` and
  ``django.contrib.gis.sitemaps.views.sitemap``).

* ``django.utils.html.fix_ampersands``, the ``fix_ampersands`` template filter and
  ``django.utils.html.clean_html`` will be removed following an accelerated deprecation.

.. _deprecation-removed-in-1.7:

1.7
---

See the :ref:`Django 1.5 release notes<deprecated-features-1.5>` for more
details on these changes.

* The module ``django.utils.simplejson`` will be removed. The standard library
  provides :mod:`json` which should be used instead.

* The function ``django.utils.itercompat.product`` will be removed. The Python
  builtin version should be used instead.

* Auto-correction of INSTALLED_APPS and TEMPLATE_DIRS settings when they are
  specified as a plain string instead of a tuple will be removed and raise an
  exception.

* The ``mimetype`` argument to the ``__init__`` methods of
  :class:`~django.http.HttpResponse`,
  :class:`~django.template.response.SimpleTemplateResponse`, and
  :class:`~django.template.response.TemplateResponse`, will be removed.
  ``content_type`` should be used instead. This also applies to the
  ``render_to_response()`` shortcut and the sitemap views,
  :func:`~django.contrib.sitemaps.views.index` and
  :func:`~django.contrib.sitemaps.views.sitemap`.

* When :class:`~django.http.HttpResponse` is instantiated with an iterator,
  or when :attr:`~django.http.HttpResponse.content` is set to an iterator,
  that iterator will be immediately consumed.

* The ``AUTH_PROFILE_MODULE`` setting, and the ``get_profile()`` method on
  the User model, will be removed.

* The ``cleanup`` management command will be removed. It's replaced by
  ``clearsessions``.

* The ``daily_cleanup.py`` script will be removed.

* The ``depth`` keyword argument will be removed from
  :meth:`~django.db.models.query.QuerySet.select_related`.

* The undocumented ``get_warnings_state()``/``restore_warnings_state()``
  functions from :mod:`django.test.utils` and the ``save_warnings_state()``/
  ``restore_warnings_state()``
  :ref:`django.test.*TestCase <django-testcase-subclasses>` methods are
  deprecated. Use the :class:`warnings.catch_warnings` context manager
  available starting with Python 2.6 instead.

* The undocumented ``check_for_test_cookie`` method in
  :class:`~django.contrib.auth.forms.AuthenticationForm` will be removed
  following an accelerated deprecation. Users subclassing this form should
  remove calls to this method, and instead ensure that their auth related views
  are CSRF protected, which ensures that cookies are enabled.

* The version of :func:`django.contrib.auth.views.password_reset_confirm` that
  supports base36 encoded user IDs
  (``django.contrib.auth.views.password_reset_confirm_uidb36``) will be
  removed. If your site has been running Django 1.6 for more than
  :setting:`PASSWORD_RESET_TIMEOUT_DAYS`, this change will have no effect. If
  not, then any password reset links generated before you upgrade to Django 1.7
  won't work after the upgrade.

* The ``django.utils.encoding.StrAndUnicode`` mix-in will be removed.
  Define a ``__str__`` method and apply the
  :func:`~django.utils.encoding.python_2_unicode_compatible` decorator instead.

.. _deprecation-removed-in-1.6:

1.6
---

See the :ref:`Django 1.4 release notes<deprecated-features-1.4>` for more
details on these changes.

* ``django.contrib.databrowse`` will be removed.

* ``django.contrib.localflavor`` will be removed following an accelerated
  deprecation.

* ``django.contrib.markup`` will be removed following an accelerated
  deprecation.

* The compatibility modules ``django.utils.copycompat`` and
  ``django.utils.hashcompat`` as well as the functions
  ``django.utils.itercompat.all`` and ``django.utils.itercompat.any`` will
  be removed. The Python builtin versions should be used instead.

* The ``csrf_response_exempt`` and ``csrf_view_exempt`` decorators will
  be removed. Since 1.4 ``csrf_response_exempt`` has been a no-op (it
  returns the same function), and ``csrf_view_exempt`` has been a
  synonym for ``django.views.decorators.csrf.csrf_exempt``, which should
  be used to replace it.

* The ``django.core.cache.backends.memcached.CacheClass`` backend
  was split into two in Django 1.3 in order to introduce support for
  PyLibMC. The historical ``CacheClass`` will be removed in favor of
  ``django.core.cache.backends.memcached.MemcachedCache``.

* The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only
  be accessible through their GB-prefixed names (GB is the correct
  ISO 3166 code for United Kingdom).

* The ``IGNORABLE_404_STARTS`` and ``IGNORABLE_404_ENDS`` settings have been
  superseded by :setting:`IGNORABLE_404_URLS` in the 1.4 release. They will be
  removed.

* The form wizard has been refactored to use class-based views with pluggable
  backends in 1.4. The previous implementation will be removed.

* Legacy ways of calling
  :func:`~django.views.decorators.cache.cache_page` will be removed.

* The backward-compatibility shim to automatically add a debug-false
  filter to the ``'mail_admins'`` logging handler will be removed. The
  :setting:`LOGGING` setting should include this filter explicitly if
  it is desired.

* The builtin truncation functions ``django.utils.text.truncate_words()``
  and ``django.utils.text.truncate_html_words()`` will be removed in
  favor of the ``django.utils.text.Truncator`` class.

* The :class:`~django.contrib.gis.geoip.GeoIP` class was moved to
  :mod:`django.contrib.gis.geoip` in 1.4 -- the shortcut in
  :mod:`django.contrib.gis.utils` will be removed.

* ``django.conf.urls.defaults`` will be removed. The functions
  :func:`~django.conf.urls.include`, ``patterns()`` and
  :func:`~django.conf.urls.url` plus :data:`~django.conf.urls.handler404`,
  :data:`~django.conf.urls.handler500`, are now available through
  :mod:`django.conf.urls` .

* The functions ``setup_environ()`` and ``execute_manager()`` will be removed
  from :mod:`django.core.management`. This also means that the old (pre-1.4)
  style of :file:`manage.py` file will no longer work.

* Setting the ``is_safe`` and ``needs_autoescape`` flags as attributes of
  template filter functions will no longer be supported.

* The attribute ``HttpRequest.raw_post_data`` was renamed to ``HttpRequest.body``
  in 1.4. The backward compatibility will be removed --
  ``HttpRequest.raw_post_data`` will no longer work.

* The value for the ``post_url_continue`` parameter in
  ``ModelAdmin.response_add()`` will have to be either ``None`` (to redirect
  to the newly created object's edit page) or a pre-formatted url. String
  formats, such as the previous default ``'../%s/'``, will not be accepted any
  more.

.. _deprecation-removed-in-1.5:

1.5
---

See the :ref:`Django 1.3 release notes<deprecated-features-1.3>` for more
details on these changes.

* Starting Django without a :setting:`SECRET_KEY` will result in an exception
  rather than a ``DeprecationWarning``. (This is accelerated from the usual
  deprecation path; see the :doc:`Django 1.4 release notes</releases/1.4>`.)

* The ``mod_python`` request handler will be removed. The ``mod_wsgi``
  handler should be used instead.

* The ``template`` attribute on ``django.test.client.Response``
  objects returned by the :ref:`test client <test-client>` will be removed.
  The :attr:`~django.test.Response.templates` attribute should be
  used instead.

* The ``django.test.simple.DjangoTestRunner`` will be removed.
  Instead use a unittest-native class.  The features of the
  ``django.test.simple.DjangoTestRunner`` (including fail-fast and
  Ctrl-C test termination) can currently be provided by the unittest-native
  :class:`~unittest.TextTestRunner`.

* The undocumented function
  ``django.contrib.formtools.utils.security_hash`` will be removed,
  instead use ``django.contrib.formtools.utils.form_hmac``

* The function-based generic view modules will be removed in favor of their
  class-based equivalents, outlined :doc:`here
  </topics/class-based-views/index>`.

* The ``django.core.servers.basehttp.AdminMediaHandler`` will be
  removed.  In its place use
  ``django.contrib.staticfiles.handlers.StaticFilesHandler``.

* The template tags library ``adminmedia`` and the template tag ``{%
  admin_media_prefix %}`` will be removed in favor of the generic static files
  handling. (This is faster than the usual deprecation path; see the
  :doc:`Django 1.4 release notes</releases/1.4>`.)

* The ``url`` and ``ssi`` template tags will be modified so that the first
  argument to each tag is a template variable, not an implied string. In 1.4,
  this behavior is provided by a version of the tag in the ``future`` template
  tag library.

* The ``reset`` and ``sqlreset`` management commands will be removed.

* Authentication backends will need to support an inactive user
  being passed to all methods dealing with permissions.
  The ``supports_inactive_user`` attribute will no longer be checked
  and can be removed from custom backends.

* :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise
  a :class:`~django.contrib.gis.geos.GEOSException` when called
  on a geometry with no SRID value.

* ``django.http.CompatCookie`` will be removed in favor of
  ``django.http.SimpleCookie``.

* ``django.core.context_processors.PermWrapper`` and
  ``django.core.context_processors.PermLookupDict`` will be removed in
  favor of the corresponding
  ``django.contrib.auth.context_processors.PermWrapper`` and
  ``django.contrib.auth.context_processors.PermLookupDict``, respectively.

* The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings will be
  required to end with a trailing slash to ensure there is a consistent
  way to combine paths in templates.

* ``django.db.models.fields.URLField.verify_exists`` will be removed. The
  feature was deprecated in 1.3.1 due to intractable security and
  performance issues and will follow a slightly accelerated deprecation
  timeframe.

* Translations located under the so-called *project path* will be ignored during
  the translation building process performed at runtime. The
  :setting:`LOCALE_PATHS` setting can be used for the same task by including the
  filesystem path to a ``locale`` directory containing non-app-specific
  translations in its value.

* The Markup contrib app will no longer support versions of Python-Markdown
  library earlier than 2.1. An accelerated timeline was used as this was
  a security related deprecation.

* The ``CACHE_BACKEND`` setting will be removed. The cache backend(s) should be
  specified in the :setting:`CACHES` setting.

.. _deprecation-removed-in-1.4:

1.4
---

See the :ref:`Django 1.2 release notes<deprecated-features-1.2>` for more
details on these changes.

* ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` will be removed.  Use
  the ``{% csrf_token %}`` template tag inside forms to enable CSRF
  protection. ``CsrfViewMiddleware`` remains and is enabled by default.

* The old imports for CSRF functionality (``django.contrib.csrf.*``),
  which moved to core in 1.2, will be removed.

* The ``django.contrib.gis.db.backend`` module will be removed in favor
  of the specific backends.

* ``SMTPConnection`` will be removed in favor of a generic Email backend API.

* The many to many SQL generation functions on the database backends
  will be removed.

* The ability to use the ``DATABASE_*`` family of top-level settings to
  define database connections will be removed.

* The ability to use shorthand notation to specify a database backend
  (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be
  removed.

* The ``get_db_prep_save``, ``get_db_prep_value`` and
  ``get_db_prep_lookup`` methods will have to support multiple databases.

* The ``Message`` model (in ``django.contrib.auth``), its related
  manager in the ``User`` model (``user.message_set``), and the
  associated methods (``user.message_set.create()`` and
  ``user.get_and_delete_messages()``), will be removed.  The
  :doc:`messages framework </ref/contrib/messages>` should be used
  instead. The related ``messages`` variable returned by the
  auth context processor will also be removed. Note that this
  means that the admin application will depend on the messages
  context processor.

* Authentication backends will need to support the ``obj`` parameter for
  permission checking. The ``supports_object_permissions`` attribute
  will no longer be checked and can be removed from custom backends.

* Authentication backends will need to support the ``AnonymousUser`` class
  being passed to all methods dealing with permissions.  The
  ``supports_anonymous_user`` variable will no longer be checked and can be
  removed from custom backends.

* The ability to specify a callable template loader rather than a
  ``Loader`` class will be removed, as will the ``load_template_source``
  functions that are included with the built in template loaders for
  backwards compatibility.

* ``django.utils.translation.get_date_formats()`` and
  ``django.utils.translation.get_partial_date_formats()``. These functions
  will be removed; use the locale-aware
  ``django.utils.formats.get_format()`` to get the appropriate formats.

* In ``django.forms.fields``, the constants: ``DEFAULT_DATE_INPUT_FORMATS``,
  ``DEFAULT_TIME_INPUT_FORMATS`` and
  ``DEFAULT_DATETIME_INPUT_FORMATS`` will be removed. Use
  ``django.utils.formats.get_format()`` to get the appropriate
  formats.

* The ability to use a function-based test runner will be removed,
  along with the ``django.test.simple.run_tests()`` test runner.

* The ``views.feed()`` view and ``feeds.Feed`` class in
  ``django.contrib.syndication`` will be removed. The class-based view
  ``views.Feed`` should be used instead.

* ``django.core.context_processors.auth``.  This release will
  remove the old method in favor of the new method in
  ``django.contrib.auth.context_processors.auth``.

* The ``postgresql`` database backend will be removed, use the
  ``postgresql_psycopg2`` backend instead.

* The ``no`` language code will be removed and has been replaced by the
  ``nb`` language code.

* Authentication backends will need to define the boolean attribute
  ``supports_inactive_user`` until version 1.5 when it will be assumed that
  all backends will handle inactive users.

* ``django.db.models.fields.XMLField`` will be removed. This was
  deprecated as part of the 1.3 release. An accelerated deprecation
  schedule has been used because the field hasn't performed any role
  beyond that of a simple ``TextField`` since the removal of ``oldforms``.
  All uses of ``XMLField`` can be replaced with ``TextField``.

* The undocumented ``mixin`` parameter to the ``open()`` method of
  ``django.core.files.storage.Storage`` (and subclasses) will be removed.

.. _deprecation-removed-in-1.3:

1.3
---

See the :ref:`Django 1.1 release notes<deprecated-features-1.1>` for more
details on these changes.

* ``AdminSite.root()``.  This method of hooking up the admin URLs will be
  removed in favor of including ``admin.site.urls``.

* Authentication backends need to define the boolean attributes
  ``supports_object_permissions`` and ``supports_anonymous_user`` until
  version 1.4, at which point it will be assumed that all backends will
  support these options.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Git (`大一小学期/Week_3-Python/exam/2016/docs/internals/git.txt`)

=================================
The Django source code repository
=================================

When deploying a Django application into a real production environment, you
will almost always want to use `an official packaged release of Django`_.

However, if you'd like to try out in-development code from an upcoming release
or contribute to the development of Django, you'll need to obtain a clone of
Django's source code repository.

This document covers the way the code repository is laid out and how to work
with and find things in it.

.. _an official packaged release of Django: https://www.djangoproject.com/download/

High-level overview
===================

The Django source code repository uses `Git`_ to track changes to the code
over time, so you'll need a copy of the Git client (a program called ``git``)
on your computer, and you'll want to familiarize yourself with the basics of
how Git works.

Git's website offers downloads for various operating systems. The site also
contains vast amounts of `documentation`_.

The Django Git repository is located online at `github.com/django/django
<https://github.com/django/django>`_. It contains the full source code for all
Django releases, which you can browse online.

The Git repository includes several `branches`_:

* ``master`` contains the main in-development code which will become
  the next packaged release of Django. This is where most development
  activity is focused.

* ``stable/A.B.x`` are the branches where release preparation work happens.
  They are also used for bugfix and security releases which occur as necessary
  after the initial release of a feature version.

* ``soc20XX/`` branches were used by students who worked on Django
  during the 2009 and 2010 Google Summer of Code programs.

* ``attic/`` branches were used to develop major or experimental new
  features without affecting the rest of Django's code.

The Git repository also contains `tags`_. These are the exact revisions from
which packaged Django releases were produced, since version 1.0.

The source code for the `Djangoproject.com <https://www.djangoproject.com/>`_
website can be found at `github.com/django/djangoproject.com
<https://github.com/django/djangoproject.com>`_.

.. _Git: http://git-scm.com/
.. _documentation: http://git-scm.com/documentation
.. _branches: https://github.com/django/django/branches
.. _tags: https://github.com/django/django/tags

The master branch
=================

If you'd like to try out the in-development code for the next release of
Django, or if you'd like to contribute to Django by fixing bugs or developing
new features, you'll want to get the code from the master branch.

Note that this will get *all* of Django: in addition to the top-level
``django`` module containing Python code, you'll also get a copy of Django's
documentation, test suite, packaging scripts and other miscellaneous bits.
Django's code will be present in your clone as a directory named
``django``.

To try out the in-development code with your own applications, simply place
the directory containing your clone on your Python import path. Then
``import`` statements which look for Django will find the ``django`` module
within your clone.

If you're going to be working on Django's code (say, to fix a bug or
develop a new feature), you can probably stop reading here and move
over to :doc:`the documentation for contributing to Django
`, which covers things like the preferred
coding style and how to generate and submit a patch.

Other branches
==============

Django uses branches to prepare for releases of Django.

In the past when Django was hosted on Subversion, branches were also used for
feature development. Now Django is hosted on Git and feature development is
done on contributor's forks, but the Subversion feature branches remain in Git
for historical reference.

Stable branches
---------------

These branches can be found in the repository as ``stable/A.B.x``
branches and will be created right after the first alpha is tagged.

For example, immediately after *Django 1.5 alpha 1* was tagged, the branch
``stable/1.5.x`` was created and all further work on preparing the code for the
final 1.5 release was done there.

These branches also provide limited bugfix support for the most recent released
version of Django and security support for the two most recently-released
versions of Django.

For example, after the release of Django 1.5, the branch ``stable/1.5.x``
receives only fixes for security and critical stability bugs, which are
eventually released as Django 1.5.1 and so on, ``stable/1.4.x`` receives only
security fixes, and ``stable/1.3.x`` no longer receives any updates.

.. admonition:: Historical information

    This policy for handling ``stable/A.B.x`` branches was adopted starting
    with the Django 1.5 release cycle.

    Previously, these branches weren't created until right after the releases
    and the stabilization work occurred on the main repository branch. Thus,
    no new features development work for the next release of Django could be
    committed until the final release happened.

    For example, shortly after the release of Django 1.3 the branch
    ``stable/1.3.x`` was created. Official support for that release has expired,
    and so it no longer receives direct maintenance from the Django project.
    However, that and all other similarly named branches continue to exist and
    interested community members have occasionally used them to provide
    unofficial support for old Django releases.

Feature-development branches
----------------------------

.. admonition:: Historical information

    Since Django moved to Git in 2012, anyone can clone the repository and
    create their own branches, alleviating the need for official branches in
    the source code repository.

    The following section is mostly useful if you're exploring the repository's
    history, for example if you're trying to understand how some features were
    designed.

Feature-development branches tend by their nature to be temporary. Some
produce successful features which are merged back into Django's master to
become part of an official release, but others do not; in either case there
comes a time when the branch is no longer being actively worked on by any
developer. At this point the branch is considered closed.

Unfortunately, Django used to be maintained with the Subversion revision
control system, that has no standard way of indicating this. As a workaround,
branches of Django which are closed and no longer maintained were moved into
``attic``.

For reference, the following are branches whose code eventually became
part of Django itself, and so are no longer separately maintained:

* ``boulder-oracle-sprint``: Added support for Oracle databases to
  Django's object-relational mapper. This has been part of Django
  since the 1.0 release.

* ``gis``: Added support for geographic/spatial queries to Django's
  object-relational mapper. This has been part of Django since the 1.0
  release, as the bundled application ``django.contrib.gis``.

* ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to
  Django. This has been part of Django since the 0.90 release.

* ``magic-removal``: A major refactoring of both the internals and
  public APIs of Django's object-relational mapper. This has been part
  of Django since the 0.95 release.

* ``multi-auth``: A refactoring of :doc:`Django's bundled
  authentication framework </topics/auth/index>` which added support for
  :ref:`authentication backends <authentication-backends>`. This has
  been part of Django since the 0.95 release.

* ``new-admin``: A refactoring of :doc:`Django's bundled
  administrative application </ref/contrib/admin/index>`. This became part of
  Django as of the 0.91 release, but was superseded by another
  refactoring (see next listing) prior to the Django 1.0 release.

* ``newforms-admin``: The second refactoring of Django's bundled
  administrative application. This became part of Django as of the 1.0
  release, and is the basis of the current incarnation of
  ``django.contrib.admin``.

* ``queryset-refactor``: A refactoring of the internals of Django's
  object-relational mapper. This became part of Django as of the 1.0
  release.

* ``unicode``: A refactoring of Django's internals to consistently use
  Unicode-based strings in most places within Django and Django
  applications. This became part of Django as of the 1.0 release.

When Django moved from SVN to Git, the information about branch merges wasn't
preserved in the source code repository. This means that the ``master`` branch
of Django doesn't contain merge commits for the above branches.

However, this information is `available as a grafts file`_. You can restore it
by putting the following lines in ``.git/info/grafts`` in your local clone::

  ac64e91a0cadc57f4bc5cd5d66955832320ca7a1 553a20075e6991e7a60baee51ea68c8adc520d9a 0cb8e31823b2e9f05c4ae868c19f5f38e78a5f2e
  79e68c225b926302ebb29c808dda8afa49856f5c d0f57e7c7385a112cb9e19d314352fc5ed5b0747 aa239e3e5405933af6a29dac3cf587b59a099927
  5cf8f684237ab5addaf3549b2347c3adf107c0a7 cb45fd0ae20597306cd1f877efc99d9bd7cbee98 e27211a0deae2f1d402537f0ebb64ad4ccf6a4da
  f69cf70ed813a8cd7e1f963a14ae39103e8d5265 d5dbeaa9be359a4c794885c2e9f1b5a7e5e51fb8 d2fcbcf9d76d5bb8a661ee73dae976c74183098b
  aab3a418ac9293bb4abd7670f65d930cb0426d58 4ea7a11659b8a0ab07b0d2e847975f7324664f10 adf4b9311d5d64a2bdd58da50271c121ea22e397
  ff60c5f9de3e8690d1e86f3e9e3f7248a15397c8 7ef212af149540aa2da577a960d0d87029fd1514 45b4288bb66a3cda401b45901e85b645674c3988
  9dda4abee1225db7a7b195b84c915fdd141a7260 4fe5c9b7ee09dc25921918a6dbb7605edb374bc9 3a7c14b583621272d4ef53061287b619ce3c290d
  a19ed8aea395e8e07164ff7d85bd7dff2f24edca dc375fb0f3b7fbae740e8cfcd791b8bccb8a4e66 42ea7a5ce8aece67d16c6610a49560c1493d4653
  9c52d56f6f8a9cdafb231adf9f4110473099c9b5 c91a30f00fd182faf8ca5c03cd7dbcf8b735b458 4a5c5c78f2ecd4ed8859cd5ac773ff3a01bccf96
  953badbea5a04159adbfa970f5805c0232b6a401 4c958b15b250866b70ded7d82aa532f1e57f96ae 5664a678b29ab04cad425c15b2792f4519f43928
  471596fc1afcb9c6258d317c619eaf5fd394e797 4e89105d64bb9e04c409139a41e9c7aac263df4c 3e9035a9625c8a8a5e88361133e87ce455c4fc13
  9233d0426537615e06b78d28010d17d5a66adf44 6632739e94c6c38b4c5a86cf5c80c48ae50ac49f 18e151bc3f8a85f2766d64262902a9fcad44d937

.. _available as a grafts file: https://github.com/ramiro/django-git-grafts

Additionally, the following branches are closed, but their code was
never merged into Django and the features they aimed to implement
were never finished:

* ``full-history``

* ``generic-auth``

* ``multiple-db-support``

* ``per-object-permissions``

* ``schema-evolution``

* ``schema-evolution-ng``

* ``search-api``

* ``sqlalchemy``

All of the above-mentioned branches now reside in ``attic``.

Finally, the repository contains ``soc2009/xxx`` and ``soc2010/xxx`` feature
branches, used for Google Summer of Code projects.

Tags
====

Each Django release is tagged and signed by a :ref:`releaser
<releasers-list>`.

The tags can be found on GitHub's `tags`_ page.

.. _tags: https://github.com/django/django/tags

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Howto Release Django (`大一小学期/Week_3-Python/exam/2016/docs/internals/howto-release-django.txt`)

=====================
How is Django Formed?
=====================

.. highlight:: console

This document explains how to release Django.

**Please, keep these instructions up-to-date if you make changes!** The point
here is to be descriptive, not prescriptive, so feel free to streamline or
otherwise make changes, but **update this document accordingly!**

Overview
========

There are three types of releases that you might need to make:

* Security releases: disclosing and fixing a vulnerability. This'll
  generally involve two or three simultaneous releases -- e.g.
  1.5.x, 1.6.x, and, depending on timing, perhaps a 1.7 alpha/beta/rc.

* Regular version releases: either a final release (e.g. 1.5) or a
  bugfix update (e.g. 1.5.1).

* Pre-releases: e.g. 1.6 alpha, beta, or rc.

The short version of the steps involved is:

#. If this is a security release, pre-notify the security distribution list
   one week before the actual release.

#. Proofread the release notes, looking for organization and writing errors.
   Draft a blog post and email announcement.

#. Update version numbers and create the release package(s).

#. Upload the package(s) to the ``djangoproject.com`` server.

#. Upload the new version(s) to PyPI.

#. Declare the new version in the admin on ``djangoproject.com``.

#. Post the blog entry and send out the email announcements.

#. Update version numbers post-release.

There are a lot of details, so please read on.

Prerequisites
=============

You'll need a few things before getting started:

* A GPG key. If the key you want to use is not your default signing key, you'll
  need to add ``-u [email protected]`` to every GPG signing command below, where
  ``[email protected]`` is the email address associated with the key you want to
  use.

* An install of some required Python packages::

      $ pip install wheel twine

* Access to Django's record on PyPI. Create a file with your credentials:

  .. snippet::
    :filename: ~/.pypirc

    [pypi]
    username:YourUsername
    password:YourPassword

* Access to the ``djangoproject.com`` server to upload files.

* Access to the admin on ``djangoproject.com`` as a "Site maintainer".

* Access to post to ``django-announce``.

* If this is a security release, access to the pre-notification distribution
  list.

If this is your first release, you'll need to coordinate with James and/or
Jacob to get all these things lined up.

Pre-release tasks
=================

A few items need to be taken care of before even beginning the release process.
This stuff starts about a week before the release; most of it can be done
any time leading up to the actual release:

#. If this is a security release, send out pre-notification **one week** before
   the release. We maintain a list of who gets these pre-notification emails in
   the private ``django-core`` repository. Send the mail to
   ``[email protected]`` and BCC the pre-notification recipients.
   This email should be signed by the key you'll use for the release, and
   should include patches for each issue being fixed.

#. As the release approaches, watch Trac to make sure no release blockers
   are left for the upcoming release.

#. Check with the other committers to make sure they don't have any
   uncommitted changes for the release.

#. Proofread the release notes, including looking at the online
   version to catch any broken links or reST errors, and make sure the
   release notes contain the correct date.

#. Double-check that the release notes mention deprecation timelines
   for any APIs noted as deprecated, and that they mention any changes
   in Python version support.

#. Double-check that the release notes index has a link to the notes
   for the new release; this will be in ``docs/releases/index.txt``.

#. If this is a feature release, ensure translations from Transifex have been
   integrated. This is typically done by a separate translation's manager
   rather than the releaser, but here are the steps. Provided you have an
   account on Transifex::

        $ python scripts/manage_translations.py fetch

   and then commit the changed/added files (both .po and .mo). Sometimes there
   are validation errors which need to be debugged, so avoid doing this task
   immediately before a release is needed.

#. :ref:`Update the django-admin manual page <django-admin-manpage>`::

        $ cd docs
        $ make man
        $ man _build/man/django-admin.1  # do a quick sanity check
        $ cp _build/man/django-admin.1 man/django-admin.1

   and then commit the changed man page.

Preparing for release
=====================

Write the announcement blog post for the release. You can enter it into the
admin at any time and mark it as inactive. Here are a few examples: `example
security release announcement`__, `example regular release announcement`__,
`example pre-release announcement`__.

__ https://www.djangoproject.com/weblog/2013/feb/19/security/
__ https://www.djangoproject.com/weblog/2012/mar/23/14/
__ https://www.djangoproject.com/weblog/2012/nov/27/15-beta-1/

Actually rolling the release
============================

OK, this is the fun part, where we actually push out a release!

#. Check `Jenkins`__ is green for the version(s) you're putting out. You
   probably shouldn't issue a release until it's green.

   __ http://djangoci.com

#. A release always begins from a release branch, so you should make sure
   you're on a stable branch and up-to-date. For example::

        $ git checkout stable/1.5.x
        $ git pull

#. If this is a security release, merge the appropriate patches from
   ``django-private``. Rebase these patches as necessary to make each one a
   simple commit on the release branch rather than a merge commit. To ensure
   this, merge them with the ``--ff-only`` flag; for example::

        $ git checkout stable/1.5.x
        $ git merge --ff-only security/1.5.x

   (This assumes ``security/1.5.x`` is a branch in the ``django-private`` repo
   containing the necessary security patches for the next release in the 1.5
   series.)

   If git refuses to merge with ``--ff-only``, switch to the security-patch
   branch and rebase it on the branch you are about to merge it into (``git
   checkout security/1.5.x; git rebase stable/1.5.x``) and then switch back and
   do the merge. Make sure the commit message for each security fix explains
   that the commit is a security fix and that an announcement will follow
   (`example security commit`__).

   __ https://github.com/django/django/commit/3ef4bbf495cc6c061789132e3d50a8231a89406b

#. For a feature release, remove the ``UNDER DEVELOPMENT`` header at the
   top of the release notes and add the release date on the next line. For a
   patch release, replace ``*Under Development*`` with the release date. Make
   this change on all branches where the release notes for a particular version
   are located.

#. Update the version number in ``django/__init__.py`` for the release.
   Please see `notes on setting the VERSION tuple`_ below for details
   on ``VERSION``.

#. If this is a pre-release package, update the "Development Status" trove
   classifier in ``setup.py`` to reflect this. Otherwise, make sure the
   classifier is set to ``Development Status :: 5 - Production/Stable``.

#. Tag the release using ``git tag``. For example::

        $ git tag --sign --message="Tag 1.5.1" 1.5.1

   You can check your work by running ``git tag --verify <tag>``.

#. Push your work, including the tag: ``git push --tags``.

#. Make sure you have an absolutely clean tree by running ``git clean -dfx``.

#. Run ``make -f extras/Makefile`` to generate the release packages. This will
   create the release packages in a ``dist/`` directory.

#. Generate the hashes of the release packages::

        $ cd dist
        $ md5sum *
        $ sha1sum *
        $ sha256sum *

#. Create a "checksums" file, ``Django-<<VERSION>>.checksum.txt`` containing
   the hashes and release information. Start with this template and insert the
   correct version, date, GPG key ID (from
   ``gpg --list-keys --keyid-format LONG``), release URL, and checksums:

   .. code-block:: text

    This file contains MD5, SHA1, and SHA256 checksums for the source-code
    tarball and wheel files of Django <<VERSION>>, released <<DATE>>.

    To use this file, you will need a working install of PGP or other
    compatible public-key encryption software. You will also need to have
    the Django release manager's public key in your keyring; this key has
    the ID ``XXXXXXXXXXXXXXXX`` and can be imported from the MIT
    keyserver. For example, if using the open-source GNU Privacy Guard
    implementation of PGP:

        gpg --keyserver pgp.mit.edu --recv-key XXXXXXXXXXXXXXXX

    Once the key is imported, verify this file::

        gpg --verify <>

    Once you have verified this file, you can use normal MD5, SHA1, or SHA256
    checksumming applications to generate the checksums of the Django
    package and compare them to the checksums listed below.

    Release packages:
    =================

    https://www.djangoproject.com/m/releases/<<RELEASE TAR.GZ FILENAME>>
    https://www.djangoproject.com/m/releases/<<RELEASE WHL FILENAME>>

    MD5 checksums:
    ==============

    <<MD5SUM>>  <<RELEASE TAR.GZ FILENAME>>
    <<MD5SUM>>  <<RELEASE WHL FILENAME>>

    SHA1 checksums:
    ===============

    <<SHA1SUM>>  <<RELEASE TAR.GZ FILENAME>>
    <<SHA1SUM>>  <<RELEASE WHL FILENAME>>

    SHA256 checksums:
    =================

    <<SHA256SUM>>  <<RELEASE TAR.GZ FILENAME>>
    <<SHA256SUM>>  <<RELEASE WHL FILENAME>>

#. Sign the checksum file (``gpg --clearsign --digest-algo SHA256
   Django-<version>.checksum.txt``). This generates a signed document,
   ``Django-<version>.checksum.txt.asc`` which you can then verify using ``gpg
   --verify Django-<version>.checksum.txt.asc``.

If you're issuing multiple releases, repeat these steps for each release.

Making the release(s) available to the public
=============================================

Now you're ready to actually put the release out there. To do this:

#. Upload the release package(s) to the djangoproject server, replacing
   A.B. with the appropriate version number, e.g. 1.5 for a 1.5.x release::

        $ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B

#. Upload the checksum file(s)::

        $ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt

#. Test that the release packages install correctly using ``easy_install``
   and ``pip``. Here's one method (which requires `virtualenvwrapper`__)::

        $ RELEASE_VERSION='1.7.2'
        $ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3`

        $ mktmpenv
        $ easy_install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz
        $ deactivate
        $ mktmpenv
        $ pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz
        $ deactivate
        $ mktmpenv
        $ pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION-py2.py3-none-any.whl
        $ deactivate

   This just tests that the tarballs are available (i.e. redirects are up) and
   that they install correctly, but it'll catch silly mistakes.

   __ https://pypi.python.org/pypi/virtualenvwrapper

#. Ask a few people on IRC to verify the checksums by visiting the checksums
   file (e.g. https://www.djangoproject.com/m/pgp/Django-1.5b1.checksum.txt)
   and following the instructions in it. For bonus points, they can also unpack
   the downloaded release tarball and verify that its contents appear to be
   correct (proper version numbers, no stray ``.pyc`` or other undesirable
   files).

#. Upload the release packages to PyPI (for pre-releases, only upload the wheel
   file)::

       $ twine upload -s dist/*

#. Go to the `Add release page in the admin`__, enter the new release number
   exactly as it appears in the name of the tarball (Django-<version>.tar.gz).
   So for example enter "1.5.1" or "1.4c2", etc. If the release is part of
   an LTS branch, mark it so.

   __ https://www.djangoproject.com/admin/releases/release/add/

#. Make the blog post announcing the release live.

#. For a new version release (e.g. 1.5, 1.6), update the default stable version
   of the docs by flipping the ``is_default`` flag to ``True`` on the
   appropriate ``DocumentRelease`` object in the ``docs.djangoproject.com``
   database (this will automatically flip it to ``False`` for all
   others); you can do this using the site's admin.

#. Post the release announcement to the |django-announce|, |django-developers|,
   and |django-users| mailing lists. This should include a link to the
   announcement blog post. If this is a security release, also include
   [email protected].

#. Add a link to the blog post in the topic of the #django IRC channel:
   ``/msg chanserv TOPIC #django new topic goes here``.

Post-release
============

You're almost done! All that's left to do now is:

#. Update the ``VERSION`` tuple in ``django/__init__.py`` again,
   incrementing to whatever the next expected release will be. For
   example, after releasing 1.5.1, update ``VERSION`` to
   ``VERSION = (1, 5, 2, 'alpha', 0)``.

#. Add the release in `Trac's versions list`_ if necessary (and make it the
   default if it's a final release). Not all versions are declared;
   take example on previous releases.

#. If this was a security release, update :doc:`/releases/security` with
   details of the issues addressed.

.. _Trac's versions list: https://code.djangoproject.com/admin/ticket/versions

New stable branch tasks
=======================

There are several items to do in the time following the creation of a new
stable branch (often following an alpha release). Some of these tasks don't
need to be done by the releaser.

#. Create a new ``DocumentRelease`` object in the ``docs.djangoproject.com``
   database for the new version's docs, and update the
   ``docs/fixtures/doc_releases.json`` JSON fixture, so people without access
   to the production DB can still run an up-to-date copy of the docs site.

#. Create a stub release note for the new feature version. Use the stub from
   the previous feature release version or copy the contents from the previous
   feature version and delete most of the contents leaving only the headings.

#. Increase the default PBKDF2 iterations in
   ``django.contrib.auth.hashers.PBKDF2PasswordHasher`` by about 20%
   (pick a round number). Run the tests, and update the 3 failing
   hasher tests with the new values. Make sure this gets noted in the
   release notes (see the 1.8 release notes for an example).

#. Remove features that have reached the end of their deprecation cycle. Each
   removal should be done in a separate commit for clarity. In the commit
   message, add a "refs #XXXX" to the original ticket where the deprecation
   began if possible.

#. Remove ``.. versionadded::``, ``.. versionadded::``, and ``.. deprecated::``
   annotations in the documentation from two releases ago. For example, in
   Django 1.9, notes for 1.7 will be removed.

#. Add the new branch to `Read the Docs
   <https://readthedocs.org/projects/django/>`_. Since the automatically
   generated version names ("stable-A.B.x") differ from the version numbers
   we've used historically in Read the Docs ("A.B.x"), we currently ask Eric
   Holscher to add the version for us. Someday the alias functionality may be
   built-in to the Read the Docs UI.

Notes on setting the VERSION tuple
==================================

Django's version reporting is controlled by the ``VERSION`` tuple in
``django/__init__.py``. This is a five-element tuple, whose elements
are:

#. Major version.
#. Minor version.
#. Micro version.
#. Status -- can be one of "alpha", "beta", "rc" or "final".
#. Series number, for alpha/beta/RC packages which run in sequence
   (allowing, for example, "beta 1", "beta 2", etc.).

For a final release, the status is always "final" and the series
number is always 0. A series number of 0 with an "alpha" status will
be reported as "pre-alpha".

Some examples:

* ``(1, 2, 1, 'final', 0)`` → "1.2.1"

* ``(1, 3, 0, 'alpha', 0)`` → "1.3 pre-alpha"

* ``(1, 3, 0, 'beta', 2)`` → "1.3 beta 2"

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Index (`大一小学期/Week_3-Python/exam/2016/docs/internals/index.txt`)

================
Django internals
================

Documentation for people hacking on Django itself. This is the place to go if
you'd like to help improve Django or learn about how Django is managed.

.. toctree::
   :maxdepth: 2

   contributing/index
   mailing-lists
   organization
   team
   roles
   security
   release-process
   deprecation
   git
   howto-release-django

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Mailing Lists (`大一小学期/Week_3-Python/exam/2016/docs/internals/mailing-lists.txt`)

=============
Mailing lists
=============

.. Important::

    Please report security issues **only** to
    [email protected].  This is a private list only open to
    long-time, highly trusted Django developers, and its archives are
    not public. For further details, please see :doc:`our security
    policies `.

Django has several official mailing lists on Google Groups that are open to
anyone.

.. _django-users-mailing-list:

``django-users``
================

This is the right place if you are looking to ask any question regarding the
installation, usage, or debugging of Django.

.. note::

    If it's the first time you send an email to this list, your email must be
    accepted first so don't worry if :ref:`your message does not appear
    <message-does-not-appear-on-django-users>` instantly.

* `django-users mailing archive`_
* `django-users subscription email address`_
* `django-users posting email`_

.. _django-users mailing archive: https://groups.google.com/d/forum/django-users
.. _django-users subscription email address: mailto:[email protected]
.. _django-users posting email: mailto:[email protected]

.. _django-core-mentorship-mailing-list:

``django-core-mentorship``
==========================

The Django Core Mentorship list is intended to provide a welcoming
introductory environment for community members interested in contributing to
the Django Project.

* `django-core-mentorship mailing archive`_
* `django-core-mentorship subscription email address`_
* `django-core-mentorship posting email`_

.. _django-core-mentorship mailing archive: https://groups.google.com/d/forum/django-core-mentorship
.. _django-core-mentorship subscription email address: mailto:[email protected]
.. _django-core-mentorship posting email: mailto:[email protected]

.. _django-developers-mailing-list:

``django-developers``
=====================

The discussion about the development of Django itself takes place here.

.. note::

    Please make use of
    :ref:`django-users mailing list <django-users-mailing-list>` if you want
    to ask for tech support, doing so in this list is inappropriate.

* `django-developers mailing archive`_
* `django-developers subscription email address`_
* `django-developers posting email`_

.. _django-developers mailing archive: https://groups.google.com/d/forum/django-developers
.. _django-developers subscription email address: mailto:[email protected]
.. _django-developers posting email: mailto:[email protected]

.. _django-i18n-mailing-list:

``django-i18n``
===============

This is the place to discuss the internationalization and localization of
Django's components.

* `django-i18n mailing archive`_
* `django-i18n subscription email address`_
* `django-i18n posting email`_

.. _django-i18n mailing archive: https://groups.google.com/d/forum/django-i18n
.. _django-i18n subscription email address: mailto:[email protected]
.. _django-i18n posting email: mailto:[email protected]

.. _django-announce-mailing-list:

``django-announce``
===================

A (very) low-traffic list for announcing new releases of Django and important
bugfixes.

* `django-announce mailing archive`_
* `django-announce subscription email address`_
* `django-announce posting email`_

.. _django-announce mailing archive: https://groups.google.com/d/forum/django-announce
.. _django-announce subscription email address: mailto:[email protected]
.. _django-announce posting email: mailto:[email protected]

.. _django-updates-mailing-list:

``django-updates``
==================

All the ticket updates are mailed automatically to this list, which is tracked
by developers and interested community members.

* `django-updates mailing archive`_
* `django-updates subscription email address`_
* `django-updates posting email`_

.. _django-updates mailing archive: https://groups.google.com/d/forum/django-updates
.. _django-updates subscription email address: mailto:[email protected]
.. _django-updates posting email: mailto:[email protected]

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Organization (`大一小学期/Week_3-Python/exam/2016/docs/internals/organization.txt`)

==================================
Organization of the Django Project
==================================

Principles
==========

The Django Project is managed by a team of volunteers pursuing three goals:

- Driving the development of the Django Web Framework,
- Fostering the ecosystem of Django-related software,
- Leading the Django community in accordance with the values described in the
  `Django Code of Conduct`_.

The Django Project isn't a legal entity. The `Django Software Foundation`_, a
non-profit organization, handles financial and legal matters related to the
Django Project. Other than that, the Django Software Foundation lets the
Django Project manage the development of the Django framework, its ecosystem
and its community.

.. _Django Code of Conduct: https://www.djangoproject.com/conduct/
.. _Django Software Foundation: https://www.djangoproject.com/foundation/

The Django core team makes the decisions, nominates its new members, and
elects its technical board. While it holds decision power in theory, it aims
at using it as rarely as possible in practice. Rough consensus should be the
norm and formal voting an exception.

.. _core-team:

Core team
=========

Role
----

The core team is the group of trusted volunteers who manage the Django
Project. They assume many roles required to achieve the project's goals,
especially those that require a high level of trust. They make the decisions
that shape the future of the project.

Core team members are expected to act as role models for the community and
custodians of the project, on behalf of the community and all those who rely
on Django.

They will intervene, where necessary, in online discussions or at official
Django events on the rare occasions that a situation arises that requires
intervention.

They have authority over the Django Project infrastructure, including the
Django Project website itself, the Django GitHub organization and
repositories, the Trac bug tracker, the mailing lists, IRC channels, etc.

Prerogatives
------------

Core team members may participate in formal votes, typically to nominate new
team members and to elect the technical board.

Some contributions don't require commit access. Depending on the reasons why a
contributor joins the team, they may or may not have commit permissions to the
Django code repository.

However, should the need arise, any team member may ask for commit access by
writing to the core team's mailing list. Access will be granted unless the
person withdraws their request or the technical board vetoes the proposal.

Core team members who have commit access are referred to as "committers" or
"core developers".

Other permissions, such as access to the servers, are granted to those who
need them through the same process.

Membership
----------

The core team finds its origins with the :ref:`four people
<original-team-list>` who created Django. It has grown to :ref:`a few dozen
people <core-team-list>` by co-opting volunteers who demonstrate:

- a good grasp of the philosophy of the Django Project
- a solid track record of being constructive and helpful
- significant contributions to the project's goals, in any form
- willingness to dedicate some time to improving Django

As the project matures, contributions go way beyond code. Here's an incomplete
list of areas where contributions may be considered for joining the core team,
in no particular order:

- Working on community management and outreach
- Providing support on the mailing-lists and on IRC
- Triaging tickets
- Writing patches (code, docs, or tests)
- Reviewing patches (code, docs, or tests)
- Participating in design decisions
- Providing expertise in a particular domain (security, i18n, etc.)
- Managing the continuous integration infrastructure
- Managing the servers (website, tracker, documentation, etc.)
- Maintaining related projects (djangoproject.com site, ex-contrib apps, etc.)
- Creating visual designs

Very few areas are reserved to core team members:

- Reviewing security reports
- Merging patches (code, docs, or tests)
- Packaging releases

Core team membership acknowledges sustained and valuable efforts that align
well with the philosophy and the goals of the Django Project.

It is granted by a four fifths majority of votes cast in a core team vote and
no veto by the technical board.

Core team members are always looking for promising contributors, teaching them
how the project is managed, and submitting their names to the core team's vote
when they're ready. If you would like to join the core team, you can contact a
core team member privately or ask for guidance on the :ref:`Django Core
Mentorship mailing-list <django-core-mentorship-mailing-list>`.

There's no time limit on core team membership. However, in order to provide
the general public with a reasonable idea of how many people maintain Django,
core team members who have stopped contributing are encouraged to declare
themselves as "past team members". Those who haven't made any non-trivial
contribution in two years may be asked to move themselves to this category,
and moved there if they don't respond. Past team members lose their privileges
such as voting rights and commit access.

.. _technical-board:

Technical board
===============

Role
----

The technical board is a group of experienced and active committers who steer
technical choices. Their main concern is to maintain the quality and stability
of the Django Web Framework.

Prerogatives
------------

The technical board holds two prerogatives:

- Making major technical decisions when no consensus is found otherwise. This
  happens on the |django-developers| mailing-list.
- Veto a grant of commit access or remove commit access. This happens on the
  django-core mailing-list.

In both cases, the technical board is a last resort. In these matters, it
fulfills a similar function to the former Benevolent Dictators For Life.

When the board wants to exercise one of these prerogatives, it must hold a
private, simple majority vote on the resolution. The quorum is the full
committee — each member must cast a vote or abstain explicitly. Then the board
communicates the result, and if possible the reasons, on the appropriate
mailing-list. There's no appeal for such decisions.

In addition, at its discretion, the technical board may act in an advisory
capacity on non-technical decisions.

Membership
----------

The technical board is an elected group of five committers. They're expected
to be experienced but there's no formal seniority requirement. Its current
composition is published :ref:`here <technical-board-list>`.

A new board is elected after each feature release of Django. The election
process is managed by a returns officer nominated by the outgoing technical
board. The election process works as follows:

1. Candidates advertise their application for the technical board to the team.

   They must be committers already. There's no term limit for technical board
   members.

2. Each team member can vote for zero to five people among the candidates.
   Candidates are ranked by the total number of votes they received.

   In case of a tie, the person who joined the core team earlier wins.

Both the application and the voting period last between one and two weeks, at
the outgoing board's discretion.

Changing the organization
=========================

Changes to this document require a four fifths majority of votes cast in a
core team vote and no veto by the technical board.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Release Process (`大一小学期/Week_3-Python/exam/2016/docs/internals/release-process.txt`)

========================
Django's release process
========================

.. _official-releases:

Official releases
=================

Since version 1.0, Django's release numbering works as follows:

* Versions are numbered in the form ``A.B`` or ``A.B.C``.

* ``A.B`` is the *feature release* version number. Each version will be mostly
  backwards compatible with the previous release. Exceptions to this rule will
  be listed in the release notes.

* ``C`` is the *patch release* version number, which is incremented for bugfix
  and security releases. These releases will be 100% backwards-compatible with
  the previous patch release. The only exception is when a security or data
  loss issue can't be fixed without breaking backwards-compatibility. If this
  happens, the release notes will provide detailed upgrade instructions.

* Before a new feature release, we'll make alpha, beta, and release candidate
  releases. These are of the form ``A.B alpha/beta/rc N``, which means the
  ``Nth`` alpha/beta/release candidate of version ``A.B``.

In git, each Django release will have a tag indicating its version number,
signed with the Django release key. Additionally, each release series has its
own branch, called ``stable/A.B.x``, and bugfix/security releases will be
issued from those branches.

For more information about how the Django project issues new releases for
security purposes, please see :doc:`our security policies <security>`.

.. glossary::

  Feature release
    Feature releases (A.B, A.B+1, etc.) will happen roughly every eight months
    -- see `release process`_ for details. These releases will contain new
    features, improvements to existing features, and such.

  Patch release
    Patch releases (A.B.C, A.B.C+1, etc.) will be issued as needed, to fix
    bugs and/or security issues.

    These releases will be 100% compatible with the associated feature release,
    unless this is impossible for security reasons or to prevent data loss.
    So the answer to "should I upgrade to the latest patch release?" will always
    be "yes."

  Long-term support release
    Certain feature releases will be designated as long-term support (LTS)
    releases. These releases will get security and data loss fixes applied for
    a guaranteed period of time, typically three years.

    See `the download page`_ for the releases that have been designated for
    long-term support.

    .. _the download page: https://www.djangoproject.com/download/

Release cadence
===============

Starting with Django 2.0, version numbers will use a loose form of `semantic
versioning <http://semver.org/>`_ such that each version following an LTS will
bump to the next "dot zero" version. For example: 2.0, 2.1, 2.2 (LTS), 3.0,
3.1, 3.2 (LTS), etc.

SemVer makes it easier to see at a glance how compatible releases are with each
other. It also helps to anticipate when compatibility shims will be removed.
It's not a pure form of SemVer as each feature release will continue to have a
few documented backwards incompatibilities where a deprecation path isn't
possible or not worth the cost. Also, deprecations started in an LTS release
(X.2) will be dropped in a non-dot-zero release (Y.1) to accommodate our policy
of keeping deprecation shims for at least two feature releases. Read on to the
next section for an example.

.. _internal-release-deprecation-policy:

Deprecation policy
==================

A feature release may deprecate certain features from previous releases. If a
feature is deprecated in feature release A.x, it will continue to work in all
A.x versions (for all versions of x) but raise warnings. Deprecated features
will be removed in the B.0 release, or B.1 for features deprecated in the last
A.x feature release to ensure deprecations are done over at least 2 feature
releases.

So, for example, if we decided to start the deprecation of a function in
Django 4.2:

* Django 4.2 will contain a backwards-compatible replica of the function which
  will raise a ``RemovedInDjango51Warning``.

* Django 5.0 (the version that follows 4.2) will still contain the
  backwards-compatible replica.

* Django 5.1 will remove the feature outright.

The warnings are silent by default. You can turn on display of these warnings
with the ``python -Wd`` option.

A more generic example:

* X.0
* X.1
* X.2 LTS
* Y.0: Drop deprecation shims added in X.0 and X.1.
* Y.1: Drop deprecation shims added in X.2.
* Y.2 LTS: No deprecation shims dropped (while Y.0 is no longer supported,
  third-party apps need to maintain compatibility back to X.2 LTS to ease
  LTS to LTS upgrades).
* Z.0: Drop deprecation shims added in Y.0 and Y.1.

.. _backwards-compatibility-policy:

Supported versions
==================

At any moment in time, Django's developer team will support a set of releases to
varying levels. See `the supported versions section
<https://www.djangoproject.com/download/#supported-versions>`_ of the download
page for the current state of support for each version.

* The current development master will get new features and bug fixes
  requiring non-trivial refactoring.

* Patches applied to the master branch must also be applied to the last feature
  release branch, to be released in the next patch release of that feature
  series, when they fix critical problems:

  * Security issues.

  * Data loss bugs.

  * Crashing bugs.

  * Major functionality bugs in newly-introduced features.

  * Regressions from older versions of Django.

  The rule of thumb is that fixes will be backported to the last feature
  release for bugs that would have prevented a release in the first place
  (release blockers).

* Security fixes and data loss bugs will be applied to the current master, the
  last two feature release branches, and any other supported long-term
  support release branches.

* Documentation fixes generally will be more freely backported to the last
  release branch. That's because it's highly advantageous to have the docs for
  the last release be up-to-date and correct, and the risk of introducing
  regressions is much less of a concern.

As a concrete example, consider a moment in time halfway between the release of
Django 5.1 and 5.2. At this point in time:

* Features will be added to development master, to be released as Django 5.2.

* Critical bug fixes will be applied to the ``stable/5.1.x`` branch, and
  released as 5.1.1, 5.1.2, etc.

* Security fixes and bug fixes for data loss issues will be applied to
  ``master`` and to the ``stable/5.1.x``, ``stable/5.0.x``, and
  ``stable/4.2.x`` (LTS) branches. They will trigger the release of ``5.1.1``,
  ``5.0.5``, ``4.2.8``, etc.

* Documentation fixes will be applied to master, and, if easily backported, to
  the latest stable branch, ``5.1.x``.

.. _release-process:

Release process
===============

Django uses a time-based release schedule, with feature releases every eight
months or so.

After each feature release, the release manager will announce a timeline for
the next feature release.

Release cycle
-------------

Each release cycle consists of three parts:

Phase one: feature proposal

The second part of the release schedule is the "heads-down" working period.
Using the roadmap produced at the end of phase one, we'll all work very hard to
get everything on it done.

At the end of phase two, any unfinished features will be postponed until the
next release.

Phase two will culminate with an alpha release. At this point, the
``stable/A.B.x`` branch will be forked from ``master``.

Phase three: bugfixes
~~~~~~~~~~~~~~~~~~~~~

The last part of a release cycle is spent fixing bugs -- no new features will
be accepted during this time. We'll try to release a beta release one month
after the alpha and a release candidate one month after the beta.

The release candidate marks the string freeze, and it happens at least two
weeks before the final release. After this point, new translatable strings
must not be added.

During this phase, committers will be more and more conservative with
backports, to avoid introducing regressions. After the release candidate, only
release blockers and documentation fixes should be backported.

In parallel to this phase, ``master`` can receive new features, to be released
in the ``A.B+1`` cycle.

Bug-fix releases
----------------

After a feature release (e.g. A.B), the previous release will go into bugfix
mode.

The branch for the previous feature release (e.g. ``stable/A.B-1.x``) will
include bugfixes. Critical bugs fixed on master must *also* be fixed on the
bugfix branch; this means that commits need to cleanly separate bug fixes from
feature additions. The developer who commits a fix to master will be
responsible for also applying the fix to the current bugfix branch.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Roles (`大一小学期/Week_3-Python/exam/2016/docs/internals/roles.txt`)

=====
Roles
=====

.. _technical-board-list:

Technical board
===============

The technical board for the 1.10 release cycle is:

* James Bennett
* Andrew Godwin
* Russell Keith-Magee
* Carl Meyer
* Marc Tamlyn

.. _committers:

Committers
==========

Most :ref:`core team <core-team>` members have commit access. They're called
"committers" or "core developers".

Being part of the core team is a pre-requisite for having commit access.

.. _security-team-list:

Security team
=============

The security team is responsible for :doc:`Django's security policies
`. It handles private reports of security issues.

The current security team members are:

- Florian Apolloner
- James Bennett
- Jeremy Dunck
- Adrian Holovaty
- Jacob Kaplan-Moss
- Russell Keith-Magee
- Paul McMillan
- Carl Meyer
- Donald Stufft

.. _releasers-list:

Releasers
=========

Releasers take care of :doc:`building Django releases
`.

The current releasers are:

- James Bennett
- Jacob Kaplan-Moss
- Tim Graham

Ops team
========

The ops team maintains Django's infrastructure like the Django Project server,
Trac instance, and continuous integration infrastructure.

- Florian Apolloner
- Aymeric Augustin
- Tim Graham
- Jannis Leidel

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Security (`大一小学期/Week_3-Python/exam/2016/docs/internals/security.txt`)

==========================
Django's security policies
==========================

Django's development team is strongly committed to responsible
reporting and disclosure of security-related issues. As such, we've
adopted and follow a set of policies which conform to that ideal and
are geared toward allowing us to deliver timely security updates to
the official distribution of Django, as well as to third-party
distributions.

.. _reporting-security-issues:

Reporting security issues
=========================

**Short version: please report security issues by emailing
[email protected]**.

Most normal bugs in Django are reported to `our public Trac instance`_, but
due to the sensitive nature of security issues, we ask that they **not** be
publicly reported in this fashion.

Instead, if you believe you've found something in Django which has security
implications, please send a description of the issue via email to
``[email protected]``. Mail sent to that address reaches a
:ref:`subset of the core team <security-team-list>`, who can forward security
issues into the private committers' mailing list for broader discussion if
needed.

Once you've submitted an issue via email, you should receive an acknowledgment
from a member of the security team within 48 hours, and depending on the
action to be taken, you may receive further followup emails.

.. note::

    If you want to send an encrypted email (*optional*), the public key ID for
    ``[email protected]`` is ``0xfcb84b8d1d17f80b``, and this public
    key is available from most commonly-used keyservers.

.. _our public Trac instance: https://code.djangoproject.com/query

.. _security-support:

Supported versions
==================

At any given time, the Django team provides official security support
for several versions of Django:

* The `master development branch`_, hosted on GitHub, which will
  become the next release of Django, receives security support.

* The two most recent Django release series receive security
  support. For example, during the development cycle leading to the
  release of Django 1.5, support will be provided for Django 1.4 and
  Django 1.3. Upon the release of Django 1.5, Django 1.3's security
  support will end.

* :term:`Long-term support release`\s will receive security updates for a
  specified period.

When new releases are issued for security reasons, the accompanying
notice will include a list of affected versions. This list is
comprised solely of *supported* versions of Django: older versions may
also be affected, but we do not investigate to determine that, and
will not issue patches or new releases for those versions.

.. _master development branch: https://github.com/django/django/

.. _security-disclosure:

How Django discloses security issues
====================================

Our process for taking a security issue from private discussion to
public disclosure involves multiple steps.

Approximately one week before full public disclosure, we will send
advance notification of the issue to a list of people and
organizations, primarily composed of operating-system vendors and
other distributors of Django. This notification will consist of an
email message, signed with the Django release key, containing:

* A full description of the issue and the affected versions of Django.

* The steps we will be taking to remedy the issue.

* The patch(es), if any, that will be applied to Django.

* The date on which the Django team will apply these patches, issue
  new releases and publicly disclose the issue.

Simultaneously, the reporter of the issue will receive notification of
the date on which we plan to take the issue public.

On the day of disclosure, we will take the following steps:

1. Apply the relevant patch(es) to Django's codebase. The commit
   messages for these patches will indicate that they are for security
   issues, but will not describe the issue in any detail; instead,
   they will warn of upcoming disclosure.

2. Issue the relevant release(s), by placing new packages on `the
   Python Package Index`_ and on the Django website, and tagging the
   new release(s) in Django's git repository.

3. Post a public entry on `the official Django development blog`_,
   describing the issue and its resolution in detail, pointing to the
   relevant patches and new releases, and crediting the reporter of
   the issue (if the reporter wishes to be publicly identified).

4. Post a notice to the |django-announce| and [email protected]
   mailing lists that links to the blog post.

.. _the Python Package Index: https://pypi.python.org/pypi
.. _the official Django development blog: https://www.djangoproject.com/weblog/

If a reported issue is believed to be particularly time-sensitive --
due to a known exploit in the wild, for example -- the time between
advance notification and public disclosure may be shortened
considerably.

Additionally, if we have reason to believe that an issue reported to
us affects other frameworks or tools in the Python/web ecosystem, we
may privately contact and discuss those issues with the appropriate
maintainers, and coordinate our own disclosure and resolution with
theirs.

The Django team also maintains an :doc:`archive of security issues
disclosed in Django</releases/security>`.


.. _security-notifications:

Who receives advance notification
=================================

The full list of people and organizations who receive advance
notification of security issues is not and will not be made public.

We also aim to keep this list as small as effectively possible, in
order to better manage the flow of confidential information prior to
disclosure. As such, our notification list is *not* simply a list of
users of Django, and merely being a user of Django is not sufficient
reason to be placed on the notification list.

In broad terms, recipients of security notifications fall into three
groups:

1. Operating-system vendors and other distributors of Django who
   provide a suitably-generic (i.e., *not* an individual's personal
   email address) contact address for reporting issues with their
   Django package, or for general security reporting. In either case,
   such addresses **must not** forward to public mailing lists or bug
   trackers. Addresses which forward to the private email of an
   individual maintainer or security-response contact are acceptable,
   although private security trackers or security-response groups are
   strongly preferred.

2. On a case-by-case basis, individual package maintainers who have
   demonstrated a commitment to responding to and responsibly acting
   on these notifications.

3. On a case-by-case basis, other entities who, in the judgment of the
   Django development team, need to be made aware of a pending
   security issue. Typically, membership in this group will consist of
   some of the largest and/or most likely to be severely impacted
   known users or distributors of Django, and will require a
   demonstrated ability to responsibly receive, keep confidential and
   act on these notifications.

Requesting notifications
========================

If you believe that you, or an organization you are authorized to
represent, fall into one of the groups listed above, you can ask to be
added to Django's notification list by emailing
``[email protected]``. Please use the subject line "Security
notification request".

Your request **must** include the following information:

* Your full, real name and the name of the organization you represent,
  if applicable, as well as your role within that organization.

* A detailed explanation of how you or your organization fit at least
  one set of criteria listed above.

* A detailed explanation of why you are requesting security
  notifications. Again, please keep in mind that this is *not* simply
  a list for users of Django, and the overwhelming majority of users
  of Django should not request notifications and will not be added to
  our notification list if they do.

* The email address you would like to have added to our notification
  list.

* An explanation of who will be receiving/reviewing mail sent to that
  address, as well as information regarding any automated actions that
  will be taken (i.e., filing of a confidential issue in a bug
  tracker).

* For individuals, the ID of a public key associated with your address
  which can be used to verify email received from you and encrypt
  email sent to you, as needed.

Once submitted, your request will be considered by the Django
development team; you will receive a reply notifying you of the result
of your request within 30 days.

Please also bear in mind that for any individual or organization,
receiving security notifications is a privilege granted at the sole
discretion of the Django development team, and that this privilege can
be revoked at any time, with or without explanation.

If you are added to the notification list, security-related emails
will be sent to you by Django's release team, and all notification
emails will be signed with a key authorized to issue Django
releases. The list of authorized keys is in `the Django releasers
file`_.

.. _the Django releasers file: https://www.djangoproject.com/m/pgp/django-releasers.txt

---

### 大一小学期 Week 3 Python Exam 2016 Docs Internals Team (`大一小学期/Week_3-Python/exam/2016/docs/internals/team.txt`)

===========
Django team
===========

.. _original-team-list:

The original team
=================

Django originally started at World Online, the Web department of the `Lawrence
Journal-World`_ of Lawrence, Kansas, USA.

`Adrian Holovaty`_
    Adrian is a Web developer with a background in journalism. He's known in
    journalism circles as one of the pioneers of "journalism via computer
    programming", and in technical circles as "the guy who invented Django."

    He was lead developer at World Online for 2.5 years, during which time
    Django was developed and implemented on World Online's sites. He was the
    leader and founder of EveryBlock_, a "news feed for your block." He now
    develops Soundslice_.

    Adrian lives in Chicago, USA.

`Simon Willison`_
    Simon is a well-respected Web developer from England. He had a one-year
    internship at World Online, during which time he and Adrian developed Django
    from scratch. The most enthusiastic Brit you'll ever meet, he's passionate
    about best practices in Web development and maintains a well-read
    `web-development blog`_.

    Simon lives in Brighton, England.

`Jacob Kaplan-Moss`_
    Jacob is Director of Platform Security at Heroku_. He worked at World
    Online for four years, where he helped open source Django and found
    the Django Software Foundation. Jacob lives on a hobby farm outside of
    Lawrence where he spends his weekends playing with dirt and power tools.

`Wilson Miner`_
    Wilson's design-fu is what makes Django look so nice. He created the design
    that was used for nearly the first ten years on the Django Project website,
    as well as the current design for Django's acclaimed admin interface. Wilson
    was the designer for EveryBlock and Rdio_. He now designs for Facebook.

    Wilson lives in San Francisco, USA.

.. _lawrence journal-world: http://ljworld.com/
.. _adrian holovaty: http://holovaty.com/
.. _everyblock: https://everyblock.com/
.. _soundslice: https://www.soundslice.com/
.. _simon willison: http://simonwillison.net/
.. _web-development blog: `simon willison`_
.. _jacob kaplan-moss: https://jacobian.org/
.. _revolution systems: http://revsys.com/
.. _wilson miner: http://wilsonminer.com/
.. _heroku: https://heroku.com/
.. _Rdio: http://rdio.com

.. _core-team-list:

The current team
================

These are the folks who have a long history of contributions, a solid track
record of being helpful on the mailing lists, and a proven desire to dedicate
serious time to Django. In return, they've been invited to join the :ref:`core
team <core-team>`.

`Luke Plant`_
    At University Luke studied physics and Materials Science and also
    met `Michael Meeks`_ who introduced him to Linux and Open Source,
    re-igniting an interest in programming.  Since then he has
    contributed to a number of Open Source projects and worked
    professionally as a developer.

    Luke has contributed many excellent improvements to Django,
    including database-level improvements, the CSRF middleware and
    many unit tests.

    Luke currently works for a church in Bradford, UK, and part-time
    as a freelance developer.

    .. _luke plant: http://lukeplant.me.uk/
    .. _michael meeks: https://en.wikipedia.org/wiki/Michael_Meeks_(software)

`Russell Keith-Magee`_
    Russell studied physics as an undergraduate, and studied neural networks for
    his PhD. His first job was with a startup in the defense industry developing
    simulation frameworks. Over time, mostly through work with Django, he's
    become more involved in Web development.

    Russell has helped with several major aspects of Django, including a
    couple major internal refactorings, creation of the test system, and more.

    Russell lives in the most isolated capital city in the world — Perth,
    Australia.

    .. _russell keith-magee: http://cecinestpasun.com/

`James Bennett`_
    James has been one of Django's release managers, and also
    contributes to the documentation and provide the occasional
    bugfix.

    James came to Web development from philosophy when he discovered
    that programmers get to argue just as much while collecting much
    better pay. He lives in San Mateo, California and previously
    worked at World Online and Mozilla; currently, he's part of the
    Web engineering team at `Clover`_.

    He `keeps a blog`_, and enjoys fine port and talking to his car.

    .. _james bennett: http://b-list.org/
    .. _Clover: https://www.cloverhealth.com/
    .. _keeps a blog: `james bennett`_

Justin Bronn
    Justin Bronn is a computer scientist and attorney specializing
    in legal topics related to intellectual property and spatial law.

    In 2007, Justin began developing ``django.contrib.gis`` in a branch,
    a.k.a. GeoDjango_, which was merged in time for Django 1.0.  While
    implementing GeoDjango, Justin obtained a deep knowledge of Django's
    internals including the ORM, the admin, and Oracle support.

    Justin lives in Houston, TX.

    .. _GeoDjango: http://geodjango.org/

Karen Tracey
    Karen has a background in distributed operating systems (graduate school),
    communications software (industry) and crossword puzzle construction
    (freelance).  The last of these brought her to Django, in late 2006, when
    she set out to put a Web front-end on her crossword puzzle database.
    That done, she stuck around in the community answering questions, debugging
    problems, etc. -- because coding puzzles are as much fun as word puzzles.

    Karen lives in Apex, NC, USA.

`Jannis Leidel`_
    Jannis graduated in media design from `Bauhaus-University Weimar`_,
    is the author of a number of pluggable Django apps and likes to
    contribute to Open Source projects like virtualenv_ and pip_.

    He has worked on Django's auth, admin and staticfiles apps as well as
    the form, core, internationalization and test systems. He currently works
    at Mozilla_.

    Jannis lives in Berlin, Germany.

    .. _Jannis Leidel: https://jezdez.com/
    .. _Bauhaus-University Weimar: http://www.uni-weimar.de/
    .. _virtualenv: http://www.virtualenv.org/
    .. _pip: https://pip.pypa.io/
    .. _Mozilla: https://www.mozilla.org/

`Andrew Godwin`_
    Andrew is a freelance Python developer and tinkerer, and has been
    developing against Django since 2007. He graduated from Oxford University
    with a degree in Computer Science, and has become most well known
    in the Django community for his work on South, the schema migrations
    library.

    Andrew lives in San Francisco, CA, USA.

    .. _Andrew Godwin: https://www.aeracode.org/

`Carl Meyer`_
    Carl has been a Django user since 2007 (long enough to remember
    queryset-refactor, but not magic-removal), and builds web apps at OddBird_.
    He became a Django contributor by accident, because fixing bugs is more
    interesting than working around them.

    Carl lives in Rapid City, SD, USA.

    .. _Carl Meyer: http://www.oddbird.net/
    .. _OddBird: http://www.oddbird.net/

Ramiro Morales
    Ramiro has been reading Django source code and submitting patches since
    mid-2006 after researching for a Python Web tool with matching awesomeness
    and being pointed to it by an old ninja.

    A software developer in the electronic transactions industry, he is a
    living proof of the fact that anyone with enough enthusiasm can contribute
    to Django, learning a lot and having fun in the process.

    Ramiro lives in Córdoba, Argentina.

`Chris Beaven`_
    Chris has been submitting patches and suggesting crazy ideas for Django
    since early 2006. An advocate for community involvement and a long-term
    triager, he is still often found answering questions in the #django IRC
    channel.

    Chris lives in Napier, New Zealand (adding to the pool of Oceanic core
    developers). He works remotely as a developer for `Lincoln Loop`_.

    .. _Chris Beaven: http://smileychris.com/
    .. _Lincoln Loop: https://lincolnloop.com/

Honza Král
    Honza first discovered Django in 2006 and started using it right away,
    first for school and personal projects and later in his full-time job. He
    contributed various patches and fixes mostly to the newforms library,
    newforms admin and, through participation in the Google Summer of Code
    project, assisted in creating the :ref:`model validation
    <validating-objects>` functionality.

    He is currently working for `Whiskey Media`_ in San Francisco developing
    awesome sites running on pure Django.

    .. _Whiskey Media: http://www.whiskeymedia.com/

Tim Graham
    When exploring Web frameworks for an independent study project in the fall
    of 2008, Tim discovered Django and was lured to it by the documentation.
    He enjoys contributing to the docs because they're awesome.

    Tim works as a software engineer and lives in Philadelphia, PA, USA.

Paul McMillan
    Paul found Django in 2008 while looking for a more
    structured approach to web programming. He stuck around after
    figuring out that the developers of Django had already invented
    many of the wheels he needed. His passion for breaking (and then
    fixing) things led to his current role working to maintain and
    improve the security of Django.

`Julien Phalip`_
    Julien has a background in software engineering and human-computer
    interaction. As a Web developer, he enjoys tinkering with the backend as
    much as designing and coding user interfaces. Julien discovered Django in
    2007 while doing his PhD in Computing Sciences. Since then he has
    contributed patches to various components of the framework, in particular
    the admin. Julien was a co-founder of the `Interaction Consortium`_. He
    now works at Odopod_, a digital agency based in San Francisco, CA, USA.

    .. _Julien Phalip: http://julienphalip.com
    .. _Interaction Consortium: http://interaction.net.au
    .. _Odopod: http://odopod.com

`Aymeric Augustin`_
    Aymeric is an engineer with a background in mathematics and computer
    science. He chose Django because he believes that software should be simple,
    explicit and tested. His perfectionist tendencies quickly led him to triage
    tickets and contribute patches.

    Aymeric has a pragmatic approach to software engineering, can't live without
    a continuous integration server, and likes proving that Django is a good
    choice for enterprise software.

    .. _Aymeric Augustin: https://myks.org/

`Claude Paroz`_
    Claude is a former teacher who fell in love with free software at the
    beginning of the 21st century. He's now working as freelancer in Web
    development in his native Switzerland. He has found in Django a perfect
    match for his needs of a stable, clean, documented and well-maintained Web
    framework.

    He's also helping the GNOME Translation Project as maintainer of the
    Django-based `l10n.gnome.org`_.

    .. _Claude Paroz: http://www.2xlibre.net
    .. _l10n.gnome.org: https://l10n.gnome.org

Anssi Kääriäinen
    Anssi works as a developer at Finnish National Institute for Health and
    Welfare. He is also a computer science student at Aalto University. In his
    work he uses Django for developing internal business applications and sees
    Django as a great match for that use case.

    Anssi is interested in developing the object relational mapper (ORM) and
    all related features. He's also a fan of benchmarking and he tries keep
    Django as fast as possible.

Florian Apolloner
    Florian is currently studying Physics at the `Graz University of Technology`_.
    Soon after he started using Django he joined the `Ubuntuusers webteam`_ to
    work on *Inyoka*, the software powering the whole Ubuntuusers site.

    For the time being he lives in Graz, Austria (not Australia ;)).

    .. _Graz University of Technology: http://tugraz.at/
    .. _Ubuntuusers webteam: https://wiki.ubuntuusers.de/ubuntuusers/Webteam

Jeremy Dunck
    Jeremy was rescued from corporate IT drudgery by Free Software and, in part,
    Django.  Many of Jeremy's interests center around access to information.

    Jeremy was the lead developer of Pegasus News, one of the first uses of
    Django outside World Online, and has since joined Votizen, a startup intent
    on reducing the influence of money in politics.

    He serves as DSF Secretary, organizes and helps organize sprints, cares
    about the health and equity of the Django community.  He has gone an
    embarrassingly long time without a working blog.

    Jeremy lives in Mountain View, CA, USA.

`Bryan Veloso`_
    Bryan found Django 0.96 through a fellow designer who was evangelizing
    its use. It was his first foray outside of the land that was PHP-based
    templating. Although he has only ever used Django for personal projects,
    it is the very reason he considers himself a designer/developer
    hybrid and is working to further design within the Django community.

    Bryan works as a designer at GitHub by day, and masquerades as a `vlogger`_
    and `shoutcaster`_ in the after-hours. Bryan lives in Los Angeles, CA, USA.

    .. _bryan veloso: http://avalonstar.com/
    .. _vlogger: https://youtube.com/bryanveloso/
    .. _shoutcaster: http://twitch.tv/vlogalonstar/

`Simon Charette`_
    Simon is a mathematics student who discovered Django while searching for a
    replacement framework to an in-house PHP entity. Since that faithful day
    Django has been a big part of his life. So far, he's been involved in some
    ORM and forms API fixes.

    Apart from contributing to multiple open source projects he spends most of
    his spare-time playing `Ultimate Frisbee`_ and working part-time
    at this awesome place called `Reptiletech`_.

    Simon lives in Montréal, Québec, Canada.

    .. _Simon Charette: https://github.com/charettes
    .. _Ultimate Frisbee: http://www.montrealultimate.ca
    .. _Reptiletech: https://www.reptiletech.com

Donald Stufft
    Donald found Python and Django in 2007 while trying to find a language,
    and web framework that he really enjoyed using after many years of PHP. He
    fell in love with the beauty of Python and the way Django made tasks simple
    and easy. His contributions to Django focus primarily on ensuring that it
    is and remains a secure web framework.

    Donald currently works at `Nebula Inc`_ as a Software Engineer for their
    security team and lives in the Greater Philadelphia Area.

    .. _Nebula Inc: https://www.nebula.com/

Marc Tamlyn
    Marc started life on the web using Django 1.2 back in 2010, and has never
    looked back. He was involved with rewriting the class-based view
    documentation at DjangoCon EU 2012, and also helped to develop `CCBV`_, an
    additional class-based view reference tool.

    Marc is currently a full-time parent, part-time developer, and lives in
    Oxford, UK.

    .. _CCBV: https://ccbv.co.uk/

Shai Berger
    Shai started working with Python back in 1998, and with Django just
    before 1.0. He is a Free Software enthusiast, but life happens, and
    he was driven by consulting gigs to contribute to the Oracle and
    SQL Server backends of South, and then the Oracle backend of Django
    itself. Finally, he joined core to help maintain the Oracle backend.

    Shai works for `Platonix`_, a small consulting company he started
    with a few friends in 1996, and lives near Tel Aviv, Israel.

    .. _Platonix: http://tech.platonix.com

Baptiste Mispelon
    Baptiste discovered Django around the 1.2 version and promptly switched away
    from his homegrown PHP framework. He started getting more involved in the
    project after attending DjangoCon EU 2012, mostly by triaging tickets and
    submitting small patches.

    Baptiste currently lives in Budapest, Hungary and works for `M2BPO`_,
    a small French company providing services to architects.

    .. _M2BPO: https://www.m2bpo.fr

Daniele Procida
    Daniele unexpectedly became a Django developer on 29th April 2009. Since
    then he has relied daily on Django's documentation, which has been a
    constant companion to him. More recently he has been able to contribute
    back to the project by helping improve the documentation itself.

    He is the author of `Arkestra`_ and `Don't be afraid to commit`_. He lives
    in Cardiff, Wales, and works for `Divio`_.

    .. _Divio: https://divio.ch/
    .. _Arkestra: http://arkestra-project.org/
    .. _Don\'t be afraid to commit: https://dont-be-afraid-to-commit.readthedocs.io

`Erik Romijn`_
    Erik started using Django in the days of 1.2. His largest contribution to Django was
    ``GenericIPAddressField``, and he has worked on all sorts of patches since.
    While developing with Django, he always keeps a little list of even the slightest
    Django frustrations, to tackle them at a later time and prevent other developers
    from having to deal with the same issues.

    Erik is an independent app maker, mostly developing web and mobile apps, as
    `Solid Links`_. He also enjoys helping ordinary developers to build safer web apps,
    for which Django is already a great start, and developed `Erik's Pony Checkup`_ with
    that goal in mind. Erik lives in Amsterdam, The Netherlands.

    .. _Erik Romijn: http://erik.io/
    .. _Solid Links: https://solidlinks.nl/
    .. _Erik's Pony Checkup: https://ponycheckup.com/

`Loïc Bistuer`_
    Loïc studied telecommunications engineering and works as an independent
    software developer and consultant.

    He discovered Django in 2008 shortly before the 1.0 release and has been
    hooked ever since. He contributes mostly to Django's ORM and Form
    components. His main contributions include advanced query prefetching,
    streamlining QuerySet and Manager to improve query reusability, and a
    significant refactor of forms error handling.

    Loïc is originally from the South of France and currently lives in
    Bangkok, Thailand.

    .. _Loïc Bistuer: https://github.com/loic

`Michael Manfre`_
    Michael started running Django on Windows against a Microsoft SQL Server
    (MSSQL) database in 2008. He quickly became the maintainer of the
    django-mssql 3rd party database backend. Much of his involvement with
    Django relates to the ORM, the private 3rd party database API, and using
    Django on Windows.

    Michael lives in Cary, NC, USA.

    .. _Michael Manfre: http://manfre.net

`Collin Anderson`_
    Collin found Django in November 2006. He was in awe of the admin and ORM
    and was amazed that the documentation was teaching him best web practices
    like redirecting after a successful POST request. Why had he never learned
    this before? No one knows to this day.

    He enjoys helping people on the |django-users| mailing list and making
    Django simple and easy for newcomers.

    Collin lives in South Bend, IN, USA where he uses Django to `increase
    unity`_.

    .. _Collin Anderson: https://github.com/collinanderson
    .. _increase unity: http://onetencommunications.com/about/

`Tom Christie`_
    Tom has background in speech recognition, networking, and web development.
    He has a particular interest in Web API design and is the original author
    of `Django REST framework`_.

    Tom lives in the seaside city of Brighton, UK.

    .. _Tom Christie: https://twitter.com/_tomchristie
    .. _Django REST framework: http://django-rest-framework.org

`Curtis Maloney`_
    Curtis is a self-taught programmer from Melbourne, Australia, who eschews
    specialization.  Upon finding Django when it was first open sourced, he
    realized it was possible to enjoy web development.

    He spends a lot of time helping people on the #django IRC channel, and has
    authored and released a number of `smaller django apps`_.

    .. _Curtis Maloney: http://musings.tinbrain.net/blog/
    .. _smaller django apps: https://github.com/funkybob/

`Markus Holtermann`_
    Markus is a senior backend developer at `LaterPay`_ in Munich. He studied
    Computer Science at the `Technical University of Berlin`_. He started
    working with Django in 2010 when he joined the `ubuntuusers.de`_ web team
    to work on *Inyoka*. Markus made his first contribution to the Django
    project during DjangoCon Europe 2013 in Warsaw. He was the web team leader
    for the `EuroPython 2014 website`_ and started regular contributions to
    Django after that.

    Markus lives in Berlin, Germany.

    .. _Markus Holtermann: https://github.com/MarkusH
    .. _LaterPay: https://www.laterpay.net/
    .. _Technical University of Berlin: http://www.tu-berlin.de/
    .. _ubuntuusers.de: https://ubuntuusers.de/
    .. _EuroPython 2014 website: https://ep2014.europython.eu/

`Josh Smeaton`_
    Josh was given the opportunity to work on a new Django app around version
    1.1 after working with a homegrown PHP reporting framework. The simplicity
    of the ORM and the power of the Admin were extremely liberating.

    Still being involved with custom reporting applications, he decided to try
    his hand at improving the ORM support for analytics. His contributions
    focus on giving more power to users of the ORM.

    Josh lives in Melbourne, Australia where he heads up development for a SaaS
    telecommunications company.

    .. _Josh Smeaton: https://github.com/jarshwah

`Preston Timmons`_
    Preston is a software developer with a background in mathematics. He enjoys
    Django because it enables consistent, simple, and tested systems to be
    built that even new programmers can quickly dive into. Preston lives in
    Dallas, TX.

    .. _Preston Timmons: https://github.com/prestontimmons

`Tomek Paczkowski`_
    Tomek started using Django in 2007 as a tool for quickly dealing with
    university projects. Since then, he worked with various technologies
    like Ruby on Rails, JavaScript and Android but always returned to
    Python and Django.

    Tomek loves the Django community. He organized multiple Django
    sprints, co-organized `DjangoCon Europe 2013`_ and has mentored at many
    `Django Girls`_ events.

    Originally from Poland, Tomek currently lives in London, where he
    works at Squirrel_.

    .. _Tomek Paczkowski: https://hauru.eu
    .. _DjangoCon Europe 2013: http://love.djangocircus.com
    .. _Django Girls: https://djangogirls.org
    .. _Squirrel: https://squirrel.me

`Ola Sitarska`_
    Ola started working with Django in 2009, when she discovered the power of
    the Django admin and quickly fell in love with the beauty of Python.

    She co-organized `DjangoCon Europe 2013`_ in Warsaw and co-authored the
    `Django Girls Tutorial`_, the most beginner friendly Django tutorial out
    there. Together with Ola Sendecka, she started `Django Girls`_, a community
    and series of Django workshops for women who've never programmed before.

    In 2015, she became a Django Software Foundation board member. Ola was also
    a part of the team responsible for shipping the djangoproject.com redesign.

    Originally from Poland, Ola currently lives in London, where she
    works with friends at `Potato`_.

    .. _Ola Sitarska: http://ola.sitarska.com/
    .. _DjangoCon Europe 2013: http://love.djangocircus.com
    .. _Django Girls Tutorial: http://tutorial.djangogirls.org
    .. _Django Girls: https://djangogirls.org
    .. _Potato: https://p.ota.to

`Ola Sendecka`_
    Ola started her adventure with Django when writing a university project in
    2009. After that she attended her first DjangoCon Europe which
    defined her future life as a Django professional.

    Since then she has been an active community member. Ola co-organized a number of
    Django sprints and conferences including:
    `DjangoCon Europe 2013`_, `Django Under the Hood 2015`_ and
    `DjangoCon Europe 2016`_. Together with Ola Sitarska she founded
    `Django Girls`_, co-authored the `Django Girls Tutorial`_ and
    is a member of the Django Girls Foundation. She is also an author of
    the `Coding is for Girls`_ YouTube series teaching programming and Django
    to beginners.

    Originally from Poland, Ola currently lives in London, where she works for `Potato`_.

    .. _Ola Sendecka: https://twitter.com/asendecka
    .. _DjangoCon Europe 2013: http://love.djangocircus.com
    .. _Django Under the Hood 2015: http://www.djangounderthehood.com/
    .. _DjangoCon Europe 2016: http://2016.djangocon.eu
    .. _Django Girls: https://djangogirls.org
    .. _Django Girls Tutorial: http://tutorial.djangogirls.org
    .. _Coding is for Girls: https://www.youtube.com/channel/UC0hNd2uW8jTR5K3KBzRuG2A
    .. _Potato: https://p.ota.to


Past team members
=================

Georg "Hugo" Bauer
    Georg created Django's internationalization system, managed i18n
    contributions and made a ton of excellent tweaks, feature additions and bug
    fixes.

Robert Wittams
    Robert was responsible for the *first* refactoring of Django's admin
    application to allow for easier reuse and has made a ton of
    excellent tweaks, feature additions and bug fixes.

`Alex Gaynor`_
    Alex was involved in many parts of Django, he contributed to the ORM,
    forms, admin, amongst others; he is most known for his work on
    multiple-database support in Django.

    Alex lives in Washington, DC, USA.

    .. _Alex Gaynor: https://alexgaynor.net

`Simon Meers`_
    Simon discovered Django 0.96 during his Computer Science PhD research and
    has been developing with it full-time ever since. His core code
    contributions are mostly in Django's admin application.

    Simon works as a freelance developer based in Wollongong, Australia.

    .. _Simon Meers: http://simonmeers.com/

`Gabriel Hurley`_
    Gabriel has been working with Django since 2008, shortly after the 1.0
    release. Convinced by his business partner that Python and Django were the
    right direction for the company, he couldn't have been more happy with the
    decision. His contributions range across many areas in Django, but years of
    copy-editing and an eye for detail lead him to be particularly at home
    while working on Django's documentation.

    Gabriel works as a developer in the SF Bay Area, CA, USA.

    .. _gabriel hurley: http://strikeawe.com/

Malcolm Tredinnick
    Malcolm originally wanted to be a mathematician and somehow ended up a
    software developer. He contributed to many Open Source projects, served on
    the board of the GNOME foundation, and was a great chess player.

    Malcolm was deeply involved in many part of Django - most notably, the
    ORM, but many other internals bear his fingerprints. Django’s support for
    unicode and autoescaping in templates can both be almost entirely
    attributed to Malcolm.

    He was an International Man of Mystery and lived in Sydney, Australia.

    *Malcolm passed away on March 17, 2013.*

`Preston Holmes`_
    Preston is a recovering neuroscientist who originally discovered Django as
    part of a sweeping move to Python from a grab bag of half a dozen
    languages. He was drawn to Django's balance of practical batteries included
    philosophy, care and thought in code design, and strong open source
    community. Currently working in the rent-your-infra space (aka Cloud), he
    is always looking for opportunities to volunteer for community oriented
    education projects, such as for kids and scientists (e.g. Software
    Carpentry).

    Preston lives with his family and animal menagerie in Santa Barbara, CA, USA.

    .. _Preston Holmes: http://www.ptone.com/

`Idan Gazit`_
    As a self-professed design geek, Idan was initially attracted to Django
    sometime between magic-removal and queryset-refactor. Formally trained
    as a software engineer, Idan straddles the worlds of design and code,
    jack of two trades and master of none. He is passionate about usability
    and finding novel ways to extract meaning from data, and is a longtime
    photographer_.

    Idan is currently hacking on all things data and visualization at Heroku_.

    .. _Idan Gazit: http://gazit.me
    .. _photographer: https://flickr.com/photos/idangazit

Matt Boersma
    Matt helped with Django's Oracle support.

Ian Kelly
    Ian also helped with Oracle support.

Joseph Kocherhans
    Joseph was the director of lead development at EveryBlock and previously
    developed at the Lawrence Journal-World. He often disappears for several
    days into the woods, attempts to teach himself computational linguistics,
    and annoys his neighbors with his Charango_ playing.

    Joseph's first contribution to Django was a series of improvements to the
    authorization system leading up to support for pluggable authorization.
    Since then, he's worked on the new forms system, its use in the admin, and
    many other smaller improvements.

    Joseph lives in Chicago, USA.

    .. _charango: https://en.wikipedia.org/wiki/Charango

`Gary Wilson`_
    Gary starting contributing patches to Django in 2006 while developing Web
    applications for `The University of Texas`_ (UT).  Since, he has made
    contributions to the email and forms systems, as well as many other
    improvements and code cleanups throughout the code base.

    Gary lives in Austin, Texas, USA.

    .. _Gary Wilson: http://thegarywilson.com/
    .. _The University of Texas: https://www.utexas.edu/

`Brian Rosner`_
    Brian enjoys learning more about programming languages and system
    architectures and contributing to open source projects.

    He helped immensely in getting Django's "newforms-admin" branch finished
    in time for Django 1.0.

    Brian lives in Denver, Colorado, USA.

    .. _brian rosner: http://brosner.com/

`James Tauber`_
    James is the lead developer of Pinax_ and the CEO and founder of
    Eldarion_. He has been doing open source software since 1993, Python
    since 1998 and Django since 2006. He serves on the board of the Python
    Software Foundation and is currently on a leave of absence from a PhD in
    linguistics.

    James currently lives in Boston, MA, USA but originally hails from
    Perth, Western Australia where he attended the same high school as
    Russell Keith-Magee.

    .. _James Tauber: http://jtauber.com/
    .. _eldarion: http://eldarion.com/
    .. _pinax: http://pinaxproject.com/

---

### 大一小学期 Week 3 Python Exam 2016 Docs Intro Contributing (`大一小学期/Week_3-Python/exam/2016/docs/intro/contributing.txt`)

===================================
Writing your first patch for Django
===================================

Introduction
============

Interested in giving back to the community a little? Maybe you've found a bug
in Django that you'd like to see fixed, or maybe there's a small feature you
want added.

Contributing back to Django itself is the best way to see your own concerns
addressed. This may seem daunting at first, but it's really pretty simple.
We'll walk you through the entire process, so you can learn by example.

Who's this tutorial for?
------------------------

.. seealso::

    If you are looking for a reference on how to submit patches, see the
    :doc:`/internals/contributing/writing-code/submitting-patches`
    documentation.

For this tutorial, we expect that you have at least a basic understanding of
how Django works. This means you should be comfortable going through the
existing tutorials on :doc:`writing your first Django app`.
In addition, you should have a good understanding of Python itself. But if you
don't, `Dive Into Python`__ is a fantastic (and free) online book for
beginning Python programmers.

Those of you who are unfamiliar with version control systems and Trac will find
that this tutorial and its links include just enough information to get started.
However, you'll probably want to read some more about these different tools if
you plan on contributing to Django regularly.

For the most part though, this tutorial tries to explain as much as possible,
so that it can be of use to the widest audience.

.. admonition:: Where to get help:

    If you're having trouble going through this tutorial, please post a message
    to |django-developers| or drop by `#django-dev on irc.freenode.net`__ to
    chat with other Django users who might be able to help.

__ http://www.diveintopython3.net/
__ irc://irc.freenode.net/django-dev

What does this tutorial cover?
------------------------------

We'll be walking you through contributing a patch to Django for the first time.
By the end of this tutorial, you should have a basic understanding of both the
tools and the processes involved. Specifically, we'll be covering the following:

* Installing Git.
* How to download a development copy of Django.
* Running Django's test suite.
* Writing a test for your patch.
* Writing the code for your patch.
* Testing your patch.
* Generating a patch file for your changes.
* Where to look for more information.

Once you're done with the tutorial, you can look through the rest of
:doc:`Django's documentation on contributing`.
It contains lots of great information and is a must read for anyone who'd like
to become a regular contributor to Django. If you've got questions, it's
probably got the answers.

.. admonition:: Python 3 required!

    This tutorial assumes you are using Python 3. Get the latest version at
    `Python's download page <https://www.python.org/download/>`_ or with your
    operating system's package manager.

.. admonition:: For Windows users

    When installing Python on Windows, make sure you check the option "Add
    python.exe to Path", so that it is always available on the command line.

Code of Conduct
===============

As a contributor, you can help us keep the Django community open and inclusive.
Please read and follow our `Code of Conduct <https://www.djangoproject.com/conduct/>`_.

Installing Git
==============

For this tutorial, you'll need Git installed to download the current
development version of Django and to generate patch files for the changes you
make.

To check whether or not you have Git installed, enter ``git`` into the command
line. If you get messages saying that this command could not be found, you'll
have to download and install it, see `Git's download page`__.

.. admonition:: For Windows users

    When installing Git on Windows, it is recommended that you pick the
    "Git Bash" option so that Git runs in its own shell. This tutorial assumes
    that's how you have installed it.

If you're not that familiar with Git, you can always find out more about its
commands (once it's installed) by typing ``git help`` into the command line.

__ http://git-scm.com/download

Getting a copy of Django's development version
==============================================

The first step to contributing to Django is to get a copy of the source code.
From the command line, use the ``cd`` command to navigate to the directory
where you'll want your local copy of Django to live.

Download the Django source code repository using the following command:

.. code-block:: console

    $ git clone https://github.com/django/django.git

Now that you have a local copy of Django, you can install it just like you would
install any package using ``pip``. The most convenient way to do so is by using
a *virtual environment* (or virtualenv) which is a feature built into Python
that allows you to keep a separate directory of installed packages for each of
your projects so that they don't interfere with each other.

It's a good idea to keep all your virtualenvs in one place, for example in
``.virtualenvs/`` in your home directory. Create it if it doesn't exist yet:

.. code-block:: console

    $ mkdir ~/.virtualenvs

Now create a new virtualenv by running:

.. code-block:: console

    $ python3 -m venv ~/.virtualenvs/djangodev

The path is where the new environment will be saved on your computer.

.. admonition:: For Windows users

    Using the built-in ``venv`` module will not work if you are also using the
    Git Bash shell on Windows, since activation scripts are only created for the
    system shell (``.bat``) and PowerShell (``.ps1``). Use the ``virtualenv``
    package instead:

    .. code-block:: none

        $ pip install virtualenv
        $ virtualenv ~/.virtualenvs/djangodev

.. admonition:: For Ubuntu users

    On some versions of Ubuntu the above command might fail. Use the
    ``virtualenv`` package instead, first making sure you have ``pip3``:

    .. code-block:: console

        $ sudo apt-get install python3-pip
        $ # Prefix the next command with sudo if it gives a permission denied error
        $ pip3 install virtualenv
        $ virtualenv --python=`which python3` ~/.virtualenvs/djangodev

The final step in setting up your virtualenv is to activate it:

.. code-block:: console

    $ source ~/.virtualenvs/djangodev/bin/activate

If the ``source`` command is not available, you can try using a dot instead:

.. code-block:: console

    $ . ~/.virtualenvs/djangodev/bin/activate

.. admonition:: For Windows users

    To activate your virtualenv on Windows, run:

    .. code-block:: none

        $ source ~/virtualenvs/djangodev/Scripts/activate

You have to activate the virtualenv whenever you open a new terminal window.
virtualenvwrapper__ is a useful tool for making this more convenient.

__ https://virtualenvwrapper.readthedocs.io/en/latest/

Anything you install through ``pip`` from now on will be installed in your new
virtualenv, isolated from other environments and system-wide packages. Also, the
name of the currently activated virtualenv is displayed on the command line to
help you keep track of which one you are using. Go ahead and install the
previously cloned copy of Django:

.. code-block:: console

    $ pip install -e /path/to/your/local/clone/django/

The installed version of Django is now pointing at your local copy. You will
immediately see any changes you make to it, which is of great help when writing
your first patch.

Rolling back to a previous revision of Django
=============================================

For this tutorial, we'll be using ticket :ticket:`24788` as a case study, so
we'll rewind Django's version history in git to before that ticket's patch was
applied. This will allow us to go through all of the steps involved in writing
that patch from scratch, including running Django's test suite.

**Keep in mind that while we'll be using an older revision of Django's trunk
for the purposes of the tutorial below, you should always use the current
development revision of Django when working on your own patch for a ticket!**

.. note::

    The patch for this ticket was written by Paweł Marczewski, and it was
    applied to Django as `commit 4df7e8483b2679fc1cba3410f08960bac6f51115`__.
    Consequently, we'll be using the revision of Django just prior to that,
    `commit 4ccfc4439a7add24f8db4ef3960d02ef8ae09887`__.

__ https://github.com/django/django/commit/4df7e8483b2679fc1cba3410f08960bac6f51115
__ https://github.com/django/django/commit/4ccfc4439a7add24f8db4ef3960d02ef8ae09887

Navigate into Django's root directory (that's the one that contains ``django``,
``docs``, ``tests``, ``AUTHORS``, etc.). You can then check out the older
revision of Django that we'll be using in the tutorial below:

.. code-block:: console

    $ git checkout 4ccfc4439a7add24f8db4ef3960d02ef8ae09887

Running Django's test suite for the first time
==============================================

When contributing to Django it's very important that your code changes don't
introduce bugs into other areas of Django. One way to check that Django still
works after you make your changes is by running Django's test suite. If all
the tests still pass, then you can be reasonably sure that your changes
haven't completely broken Django. If you've never run Django's test suite
before, it's a good idea to run it once beforehand just to get familiar with
what its output is supposed to look like.

Before running the test suite, install its dependencies by first ``cd``-ing
into the Django ``tests/`` directory and then running:

.. code-block:: console

    $ pip install -r requirements/py3.txt

If you encounter an error during the installation, your system might be missing
a dependency for one or more of the Python packages. Consult the failing
package's documentation or search the Web with the error message that you
encounter.

Now we are ready to run the test suite. If you're using GNU/Linux, Mac OS X or
some other flavor of Unix, run:

.. code-block:: console

    $ ./runtests.py

Now sit back and relax. Django's entire test suite has over 9,600 different
tests, so it can take anywhere from 5 to 15 minutes to run, depending on the
speed of your computer.

While Django's test suite is running, you'll see a stream of characters
representing the status of each test as it's run. ``E`` indicates that an error
was raised during a test, and ``F`` indicates that a test's assertions failed.
Both of these are considered to be test failures. Meanwhile, ``x`` and ``s``
indicated expected failures and skipped tests, respectively. Dots indicate
passing tests.

Skipped tests are typically due to missing external libraries required to run
the test; see :ref:`running-unit-tests-dependencies` for a list of dependencies
and be sure to install any for tests related to the changes you are making (we
won't need any for this tutorial). Some tests are specific to a particular
database backend and will be skipped if not testing with that backend. SQLite
is the database backend for the default settings. To run the tests using a
different backend, see :ref:`running-unit-tests-settings`.

Once the tests complete, you should be greeted with a message informing you
whether the test suite passed or failed. Since you haven't yet made any changes
to Django's code, the entire test suite **should** pass. If you get failures or
errors make sure you've followed all of the previous steps properly. See
:ref:`running-unit-tests` for more information. If you're using Python 3.5+,
there will be a couple failures related to deprecation warnings that you can
ignore. These failures have since been fixed in Django.

Note that the latest Django trunk may not always be stable. When developing
against trunk, you can check `Django's continuous integration builds`__ to
determine if the failures are specific to your machine or if they are also
present in Django's official builds. If you click to view a particular build,
you can view the "Configuration Matrix" which shows failures broken down by
Python version and database backend.

__ http://djangoci.com

.. note::

    For this tutorial and the ticket we're working on, testing against SQLite
    is sufficient, however, it's possible (and sometimes necessary) to
    :ref:`run the tests using a different database
    <running-unit-tests-settings>`.

Writing some tests for your ticket
==================================

In most cases, for a patch to be accepted into Django it has to include tests.
For bug fix patches, this means writing a regression test to ensure that the
bug is never reintroduced into Django later on. A regression test should be
written in such a way that it will fail while the bug still exists and pass
once the bug has been fixed. For patches containing new features, you'll need
to include tests which ensure that the new features are working correctly.
They too should fail when the new feature is not present, and then pass once it
has been implemented.

A good way to do this is to write your new tests first, before making any
changes to the code. This style of development is called
`test-driven development`__ and can be applied to both entire projects and
single patches. After writing your tests, you then run them to make sure that
they do indeed fail (since you haven't fixed that bug or added that feature
yet). If your new tests don't fail, you'll need to fix them so that they do.
After all, a regression test that passes regardless of whether a bug is present
is not very helpful at preventing that bug from reoccurring down the road.

Now for our hands-on example.

__ https://en.wikipedia.org/wiki/Test-driven_development

Writing some tests for ticket #24788
------------------------------------

Ticket :ticket:`24788` proposes a small feature addition: the ability to
specify the class level attribute ``prefix`` on Form classes, so that::

    […] forms which ship with apps could effectively namespace themselves such
    that N overlapping form fields could be POSTed at once and resolved to the
    correct form.

In order to resolve this ticket, we'll add a ``prefix`` attribute to the
``BaseForm`` class. When creating instances of this class, passing a prefix to
the ``__init__()`` method will still set that prefix on the created instance.
But not passing a prefix (or passing ``None``) will use the class-level prefix.
Before we make those changes though, we're going to write a couple tests to
verify that our modification functions correctly and continues to function
correctly in the future.

Navigate to Django's ``tests/forms_tests/tests/`` folder and open the
``test_forms.py`` file. Add the following code on line 1674 right before the
``test_forms_with_null_boolean`` function::

    def test_class_prefix(self):
        # Prefix can be also specified at the class level.
        class Person(Form):
            first_name = CharField()
            prefix = 'foo'

        p = Person()
        self.assertEqual(p.prefix, 'foo')

        p = Person(prefix='bar')
        self.assertEqual(p.prefix, 'bar')

This new test checks that setting a class level prefix works as expected, and
that passing a ``prefix`` parameter when creating an instance still works too.

.. admonition:: But this testing thing looks kinda hard...

    If you've never had to deal with tests before, they can look a little hard
    to write at first glance. Fortunately, testing is a *very* big subject in
    computer programming, so there's lots of information out there:

    * A good first look at writing tests for Django can be found in the
      documentation on :doc:`/topics/testing/overview`.
    * Dive Into Python (a free online book for beginning Python developers)
      includes a great `introduction to Unit Testing`__.
    * After reading those, if you want something a little meatier to sink
      your teeth into, there's always the Python :mod:`unittest` documentation.

__ http://www.diveintopython.net/unit_testing/index.html

Running your new test
---------------------

Remember that we haven't actually made any modifications to ``BaseForm`` yet,
so our tests are going to fail. Let's run all the tests in the ``forms_tests``
folder to make sure that's really what happens. From the command line, ``cd``
into the Django ``tests/`` directory and run:

.. code-block:: console

    $ ./runtests.py forms_tests

If the tests ran correctly, you should see one failure corresponding to the test
method we added. If all of the tests passed, then you'll want to make sure that
you added the new test shown above to the appropriate folder and class.

Writing the code for your ticket
================================

Next we'll be adding the functionality described in ticket :ticket:`24788` to
Django.

Writing the code for ticket #24788
----------------------------------

Navigate to the ``django/django/forms/`` folder and open the ``forms.py`` file.
Find the ``BaseForm`` class on line 72 and add the ``prefix`` class attribute
right after the ``field_order`` attribute::

    class BaseForm(object):
        # This is the main implementation of all the Form logic. Note that this
        # class is different than Form. See the comments by the Form class for
        # more information. Any improvements to the form API should be made to
        # *this* class, not to the Form class.
        field_order = None
        prefix = None

Verifying your test now passes
------------------------------

Once you're done modifying Django, we need to make sure that the tests we wrote
earlier pass, so we can see whether the code we wrote above is working
correctly. To run the tests in the ``forms_tests`` folder, ``cd`` into the
Django ``tests/`` directory and run:

.. code-block:: console

    $ ./runtests.py forms_tests

Oops, good thing we wrote those tests! You should still see one failure with
the following exception::

    AssertionError: None != 'foo'

We forgot to add the conditional statement in the ``__init__`` method. Go ahead
and change ``self.prefix = prefix`` that is now on line 87 of
``django/forms/forms.py``, adding a conditional statement::

    if prefix is not None:
        self.prefix = prefix

Re-run the tests and everything should pass. If it doesn't, make sure you
correctly modified the ``BaseForm`` class as shown above and copied the new test
correctly.

Running Django's test suite for the second time
===============================================

Once you've verified that your patch and your test are working correctly, it's
a good idea to run the entire Django test suite just to verify that your change
hasn't introduced any bugs into other areas of Django. While successfully
passing the entire test suite doesn't guarantee your code is bug free, it does
help identify many bugs and regressions that might otherwise go unnoticed.

To run the entire Django test suite, ``cd`` into the Django ``tests/``
directory and run:

.. code-block:: console

    $ ./runtests.py

As long as you don't see any failures, you're good to go.

Writing Documentation
=====================

This is a new feature, so it should be documented. Add the following section on
line 1068 (at the end of the file) of ``django/docs/ref/forms/api.txt``::

    The prefix can also be specified on the form class::

        >>> class PersonForm(forms.Form):
        ...     ...
        ...     prefix = 'person'

    .. versionadded:: 1.9

        The ability to specify ``prefix`` on the form class was added.

Since this new feature will be in an upcoming release it is also added to the
release notes for Django 1.9, on line 164 under the "Forms" section in the file
``docs/releases/1.9.txt``::

    * A form prefix can be specified inside a form class, not only when
      instantiating a form. See :ref:`form-prefix` for details.

For more information on writing documentation, including an explanation of what
the ``versionadded`` bit is all about, see
:doc:`/internals/contributing/writing-documentation`. That page also includes
an explanation of how to build a copy of the documentation locally, so you can
preview the HTML that will be generated.

Generating a patch for your changes
===================================

Now it's time to generate a patch file that can be uploaded to Trac or applied
to another copy of Django. To get a look at the content of your patch, run the
following command:

.. code-block:: console

    $ git diff

This will display the differences between your current copy of Django (with
your changes) and the revision that you initially checked out earlier in the
tutorial.

Once you're done looking at the patch, hit the ``q`` key to exit back to the
command line. If the patch's content looked okay, you can run the following
command to save the patch file to your current working directory:

.. code-block:: console

    $ git diff > 24788.diff

You should now have a file in the root Django directory called ``24788.diff``.
This patch file contains all your changes and should look this:

.. code-block:: diff

    diff --git a/django/forms/forms.py b/django/forms/forms.py
    index 509709f..d1370de 100644
    --- a/django/forms/forms.py
    +++ b/django/forms/forms.py
    @@ -75,6 +75,7 @@ class BaseForm(object):
         # information. Any improvements to the form API should be made to *this*
         # class, not to the Form class.
         field_order = None
    +    prefix = None

         def __init__(self, data=None, files=None, auto_id='id_%s', prefix=None,
                      initial=None, error_class=ErrorList, label_suffix=None,
    @@ -83,7 +84,8 @@ class BaseForm(object):
             self.data = data or {}
             self.files = files or {}
             self.auto_id = auto_id
    -        self.prefix = prefix
    +        if prefix is not None:
    +            self.prefix = prefix
             self.initial = initial or {}
             self.error_class = error_class
             # Translators: This is the default suffix added to form field labels
    diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
    index 3bc39cd..008170d 100644
    --- a/docs/ref/forms/api.txt
    +++ b/docs/ref/forms/api.txt
    @@ -1065,3 +1065,13 @@ You can put several Django forms inside one ``<form>`` tag. To give each
         >>> print(father.as_ul())
         <li><label for="id_father-first_name">First name:</label> </li>
         <li><label for="id_father-last_name">Last name:</label> </li>
    +
    +The prefix can also be specified on the form class::
    +
    +    >>> class PersonForm(forms.Form):
    +    ...     ...
    +    ...     prefix = 'person'
    +
    +.. versionadded:: 1.9
    +
    +    The ability to specify ``prefix`` on the form class was added.
    diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
    index 5b58f79..f9bb9de 100644
    --- a/docs/releases/1.9.txt
    +++ b/docs/releases/1.9.txt
    @@ -161,6 +161,9 @@ Forms
       :attr:`~django.forms.Form.field_order` attribute, the ``field_order``
       constructor argument , or the :meth:`~django.forms.Form.order_fields` method.

    +* A form prefix can be specified inside a form class, not only when
    +  instantiating a form. See :ref:`form-prefix` for details.
    +
     Generic Views
     ^^^^^^^^^^^^^

    diff --git a/tests/forms_tests/tests/test_forms.py b/tests/forms_tests/tests/test_forms.py
    index 690f205..e07fae2 100644
    --- a/tests/forms_tests/tests/test_forms.py
    +++ b/tests/forms_tests/tests/test_forms.py
    @@ -1671,6 +1671,18 @@ class FormsTestCase(SimpleTestCase):
             self.assertEqual(p.cleaned_data['last_name'], 'Lennon')
             self.assertEqual(p.cleaned_data['birthday'], datetime.date(1940, 10, 9))

    +    def test_class_prefix(self):
    +        # Prefix can be also specified at the class level.
    +        class Person(Form):
    +            first_name = CharField()
    +            prefix = 'foo'
    +
    +        p = Person()
    +        self.assertEqual(p.prefix, 'foo')
    +
    +        p = Person(prefix='bar')
    +        self.assertEqual(p.prefix, 'bar')
    +
         def test_forms_with_null_boolean(self):
             # NullBooleanField is a bit of a special case because its presentation (widget)
             # is different than its data. This is handled transparently, though.

So what do I do next?
=====================

Congratulations, you've generated your very first Django patch! Now that you've
got that under your belt, you can put those skills to good use by helping to
improve Django's codebase. Generating patches and attaching them to Trac
tickets is useful, however, since we are using git - adopting a more :doc:`git
oriented workflow ` is
recommended.

Since we never committed our changes locally, perform the following to get your
git branch back to a good starting point:

.. code-block:: console

    $ git reset --hard HEAD
    $ git checkout master

More information for new contributors
-------------------------------------

Before you get too into writing patches for Django, there's a little more
information on contributing that you should probably take a look at:

* You should make sure to read Django's documentation on
  :doc:`claiming tickets and submitting patches
  `.
  It covers Trac etiquette, how to claim tickets for yourself, expected
  coding style for patches, and many other important details.
* First time contributors should also read Django's :doc:`documentation
  for first time contributors`.
  It has lots of good advice for those of us who are new to helping out
  with Django.
* After those, if you're still hungry for more information about
  contributing, you can always browse through the rest of
  :doc:`Django's documentation on contributing`.
  It contains a ton of useful information and should be your first source
  for answering any questions you might have.

Finding your first real ticket
------------------------------

Once you've looked through some of that information, you'll be ready to go out
and find a ticket of your own to write a patch for. Pay special attention to
tickets with the "easy pickings" criterion. These tickets are often much
simpler in nature and are great for first time contributors. Once you're
familiar with contributing to Django, you can move on to writing patches for
more difficult and complicated tickets.

If you just want to get started already (and nobody would blame you!), try
taking a look at the list of `easy tickets that need patches`__ and the
`easy tickets that have patches which need improvement`__. If you're familiar
with writing tests, you can also look at the list of
`easy tickets that need tests`__. Just remember to follow the guidelines about
claiming tickets that were mentioned in the link to Django's documentation on
:doc:`claiming tickets and submitting patches
`.

__ https://code.djangoproject.com/query?status=new&status=reopened&has_patch=0&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority
__ https://code.djangoproject.com/query?status=new&status=reopened&needs_better_patch=1&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority
__ https://code.djangoproject.com/query?status=new&status=reopened&needs_tests=1&easy=1&col=id&col=summary&col=status&col=owner&col=type&col=milestone&order=priority

What's next?
------------

After a ticket has a patch, it needs to be reviewed by a second set of eyes.
After uploading a patch or submitting a pull request, be sure to update the
ticket metadata by setting the flags on the ticket to say "has patch",
"doesn't need tests", etc, so others can find it for review. Contributing
doesn't necessarily always mean writing a patch from scratch. Reviewing
existing patches is also a very helpful contribution. See
:doc:`/internals/contributing/triaging-tickets` for details.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Intro Index (`大一小学期/Week_3-Python/exam/2016/docs/intro/index.txt`)

===============
Getting started
===============

New to Django? Or to Web development in general? Well, you came to the right
place: read this material to quickly get up and running.

.. toctree::
   :maxdepth: 1

   overview
   install
   tutorial01
   tutorial02
   tutorial03
   tutorial04
   tutorial05
   tutorial06
   tutorial07
   reusable-apps
   whatsnext
   contributing

.. seealso::

    If you're new to Python_, you might want to start by getting an idea of what
    the language is like. Django is 100% Python, so if you've got minimal
    comfort with Python you'll probably get a lot more out of Django.

    If you're new to programming entirely, you might want to start with this
    `list of Python resources for non-programmers`_

    If you already know a few other languages and want to get up to speed with
    Python quickly, we recommend `Dive Into Python`_. If that's not quite your
    style, there are many other `books about Python`_.

    .. _python: https://python.org/
    .. _list of Python resources for non-programmers: https://wiki.python.org/moin/BeginnersGuide/NonProgrammers
    .. _Dive Into Python: http://www.diveintopython3.net/
    .. _books about Python: https://wiki.python.org/moin/PythonBooks

---

### 大一小学期 Week 3 Python Exam 2016 Docs Intro Install (`大一小学期/Week_3-Python/exam/2016/docs/intro/install.txt`)

===================
Quick install guide
===================

Before you can use Django, you'll need to get it installed. We have a
:doc:`complete installation guide </topics/install>` that covers all the
possibilities; this guide will guide you to a simple, minimal installation
that'll work while you walk through the introduction.

Install Python
==============

Being a Python Web framework, Django requires Python. See
:ref:`faq-python-version-support` for details. Python includes a lightweight
database called SQLite_ so you won't need to set up a database just yet.

.. _sqlite: https://sqlite.org/

Get the latest version of Python at https://www.python.org/download/ or with
your operating system's package manager.

.. admonition:: Django on Jython

    If you use Jython_ (a Python implementation for the Java platform), you'll
    need to follow a few additional steps. See :doc:`/howto/jython` for details.

.. _jython: http://www.jython.org/

You can verify that Python is installed by typing ``python`` from your shell;
you should see something like::

    Python 3.4.x
    [GCC 4.x] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>>

Set up a database
=================

This step is only necessary if you'd like to work with a "large" database engine
like PostgreSQL, MySQL, or Oracle. To install such a database, consult the
:ref:`database installation information <database-installation>`.

Remove any old versions of Django
=================================

If you are upgrading your installation of Django from a previous version, you
will need to :ref:`uninstall the old Django version before installing the new
version <removing-old-versions-of-django>`.

Install Django
==============

You've got three easy options to install Django:

* Install a version of Django :doc:`provided by your operating system
  distribution </misc/distributions>`. This is the quickest option for those
  who have operating systems that distribute Django.

* :ref:`Install an official release `. This
  is the best approach for most users.

* :ref:`Install the latest development version
  `. This option is for enthusiasts who want
  the latest-and-greatest features and aren't afraid of running brand new code.
  You might encounter new bugs in the development version, but reporting them
  helps the development of Django. Also, releases of third-party packages are
  less likely to be compatible with the development version than with the
  latest stable release.

.. admonition:: Always refer to the documentation that corresponds to the
    version of Django you're using!

    If you do either of the first two steps, keep an eye out for parts of the
    documentation marked **new in development version**. That phrase flags
    features that are only available in development versions of Django, and
    they likely won't work with an official release.


Verifying
=========

To verify that Django can be seen by Python, type ``python`` from your shell.
Then at the Python prompt, try to import Django:

.. parsed-literal::

    >>> import django
    >>> print(django.get_version())
    |version|

You may have another version of Django installed.

That's it!
==========

That's it -- you can now :doc:`move onto the tutorial `.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Intro Overview (`大一小学期/Week_3-Python/exam/2016/docs/intro/overview.txt`)

==================
Django at a glance
==================

Because Django was developed in a fast-paced newsroom environment, it was
designed to make common Web-development tasks fast and easy. Here's an informal
overview of how to write a database-driven Web app with Django.

The goal of this document is to give you enough technical specifics to
understand how Django works, but this isn't intended to be a tutorial or
reference -- but we've got both! When you're ready to start a project, you can
:doc:`start with the tutorial ` or :doc:`dive right into more
detailed documentation </topics/index>`.

Design your model
=================

Although you can use Django without a database, it comes with an
`object-relational mapper`_ in which you describe your database layout in Python
code.

.. _object-relational mapper: https://en.wikipedia.org/wiki/Object-relational_mapping

The :doc:`data-model syntax </topics/db/models>` offers many rich ways of
representing your models -- so far, it's been solving many years' worth of
database-schema problems. Here's a quick example:

.. snippet::
    :filename: mysite/news/models.py

    from django.db import models

    class Reporter(models.Model):
        full_name = models.CharField(max_length=70)

        def __str__(self):              # __unicode__ on Python 2
            return self.full_name

    class Article(models.Model):
        pub_date = models.DateField()
        headline = models.CharField(max_length=200)
        content = models.TextField()
        reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)

        def __str__(self):              # __unicode__ on Python 2
            return self.headline

Install it
==========

Next, run the Django command-line utility to create the database tables
automatically:

.. code-block:: console

    $ python manage.py migrate

The :djadmin:`migrate` command looks at all your available models and creates
tables in your database for whichever tables don't already exist, as well as
optionally providing :doc:`much richer schema control </topics/migrations>`.

Enjoy the free API
==================

With that, you've got a free, and rich, :doc:`Python API </topics/db/queries>`
to access your data. The API is created on the fly, no code generation
necessary:

.. code-block:: python

    # Import the models we created from our "news" app
    >>> from news.models import Reporter, Article

    # No reporters are in the system yet.
    >>> Reporter.objects.all()
    <QuerySet []>

    # Create a new Reporter.
    >>> r = Reporter(full_name='John Smith')

    # Save the object into the database. You have to call save() explicitly.
    >>> r.save()

    # Now it has an ID.
    >>> r.id
    1

    # Now the new reporter is in the database.
    >>> Reporter.objects.all()
    <QuerySet [<Reporter: John Smith>]>

    # Fields are represented as attributes on the Python object.
    >>> r.full_name
    'John Smith'

    # Django provides a rich database lookup API.
    >>> Reporter.objects.get(id=1)
    <Reporter: John Smith>
    >>> Reporter.objects.get(full_name__startswith='John')
    <Reporter: John Smith>
    >>> Reporter.objects.get(full_name__contains='mith')
    <Reporter: John Smith>
    >>> Reporter.objects.get(id=2)
    Traceback (most recent call last):
        ...
    DoesNotExist: Reporter matching query does not exist.

    # Create an article.
    >>> from datetime import date
    >>> a = Article(pub_date=date.today(), headline='Django is cool',
    ...     content='Yeah.', reporter=r)
    >>> a.save()

    # Now the article is in the database.
    >>> Article.objects.all()
    <QuerySet [<Article: Django is cool>]>

    # Article objects get API access to related Reporter objects.
    >>> r = a.reporter
    >>> r.full_name
    'John Smith'

    # And vice versa: Reporter objects get API access to Article objects.
    >>> r.article_set.all()
    <QuerySet [<Article: Django is cool>]>

    # The API follows relationships as far as you need, performing efficient
    # JOINs for you behind the scenes.
    # This finds all articles by a reporter whose name starts with "John".
    >>> Article.objects.filter(reporter__full_name__startswith='John')
    <QuerySet [<Article: Django is cool>]>

    # Change an object by altering its attributes and calling save().
    >>> r.full_name = 'Billy Goat'
    >>> r.save()

    # Delete an object with delete().
    >>> r.delete()

A dynamic admin interface: it's not just scaffolding -- it's the whole house
============================================================================

Once your models are defined, Django can automatically create a professional,
production ready :doc:`administrative interface </ref/contrib/admin/index>` --
a website that lets authenticated users add, change and delete objects. It's
as easy as registering your model in the admin site:

.. snippet::
    :filename: mysite/news/models.py

    from django.db import models

    class Article(models.Model):
        pub_date = models.DateField()
        headline = models.CharField(max_length=200)
        content = models.TextField()
        reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)

.. snippet::
    :filename: mysite/news/admin.py

    from django.contrib import admin

    from . import models

    admin.site.register(models.Article)

The philosophy here is that your site is edited by a staff, or a client, or
maybe just you -- and you don't want to have to deal with creating backend
interfaces just to manage content.

One typical workflow in creating Django apps is to create models and get the
admin sites up and running as fast as possible, so your staff (or clients) can
start populating data. Then, develop the way data is presented to the public.

Design your URLs
================

A clean, elegant URL scheme is an important detail in a high-quality Web
application. Django encourages beautiful URL design and doesn't put any cruft
in URLs, like ``.php`` or ``.asp``.

To design URLs for an app, you create a Python module called a :doc:`URLconf
</topics/http/urls>`. A table of contents for your app, it contains a simple
mapping between URL patterns and Python callback functions. URLconfs also serve
to decouple URLs from Python code.

Here's what a URLconf might look like for the ``Reporter``/``Article``
example above:

.. snippet::
    :filename: mysite/news/urls.py

    from django.conf.urls import url

    from . import views

    urlpatterns = [
        url(r'^articles/([0-9]{4})/$', views.year_archive),
        url(r'^articles/([0-9]{4})/([0-9]{2})/$', views.month_archive),
        url(r'^articles/([0-9]{4})/([0-9]{2})/([0-9]+)/$', views.article_detail),
    ]

The code above maps URLs, as simple :ref:`regular expressions <regex-howto>`,
to the location of Python callback functions ("views"). The regular expressions
use parenthesis to "capture" values from the URLs. When a user requests a page,
Django runs through each pattern, in order, and stops at the first one that
matches the requested URL. (If none of them matches, Django calls a
special-case 404 view.) This is blazingly fast, because the regular expressions
are compiled at load time.

Once one of the regexes matches, Django imports and calls the given view, which
is a simple Python function. Each view gets passed a request object --
which contains request metadata -- and the values captured in the regex.

For example, if a user requested the URL "/articles/2005/05/39323/", Django
would call the function ``news.views.article_detail(request,
'2005', '05', '39323')``.

Write your views
================

Each view is responsible for doing one of two things: Returning an
:class:`~django.http.HttpResponse` object containing the content for the
requested page, or raising an exception such as :class:`~django.http.Http404`.
The rest is up to you.

Generally, a view retrieves data according to the parameters, loads a template
and renders the template with the retrieved data. Here's an example view for
``year_archive`` from above:

.. snippet::
    :filename: mysite/news/views.py

    from django.shortcuts import render

    from .models import Article

    def year_archive(request, year):
        a_list = Article.objects.filter(pub_date__year=year)
        context = {'year': year, 'article_list': a_list}
        return render(request, 'news/year_archive.html', context)

This example uses Django's :doc:`template system </topics/templates>`, which has
several powerful features but strives to stay simple enough for non-programmers
to use.

Design your templates
=====================

The code above loads the ``news/year_archive.html`` template.

Django has a template search path, which allows you to minimize redundancy among
templates. In your Django settings, you specify a list of directories to check
for templates with :setting:`DIRS <TEMPLATES-DIRS>`. If a template doesn't exist
in the first directory, it checks the second, and so on.

Let's say the ``news/year_archive.html`` template was found. Here's what that
might look like:

.. snippet:: html+django
    :filename: mysite/news/templates/news/year_archive.html

    {% extends "base.html" %}

    {% block title %}Articles for {{ year }}{% endblock %}

    {% block content %}
    <h1>Articles for {{ year }}</h1>

    {% for article in article_list %}
        {{ article.headline }}
        By {{ article.reporter.full_name }}
        Published {{ article.pub_date|date:"F j, Y" }}
    {% endfor %}
    {% endblock %}

Variables are surrounded by double-curly braces. ``{{ article.headline }}``
means "Output the value of the article's headline attribute." But dots aren't
used only for attribute lookup. They also can do dictionary-key lookup, index
lookup and function calls.

Note ``{{ article.pub_date|date:"F j, Y" }}`` uses a Unix-style "pipe" (the "|"
character). This is called a template filter, and it's a way to filter the value
of a variable. In this case, the date filter formats a Python datetime object in
the given format (as found in PHP's date function).

You can chain together as many filters as you'd like. You can write :ref:`custom
template filters <howto-writing-custom-template-filters>`. You can write
:doc:`custom template tags </howto/custom-template-tags>`, which run custom
Python code behind the scenes.

Finally, Django uses the concept of "template inheritance". That's what the
``{% extends "base.html" %}`` does. It means "First load the template called
'base', which has defined a bunch of blocks, and fill the blocks with the
following blocks." In short, that lets you dramatically cut down on redundancy
in templates: each template has to define only what's unique to that template.

Here's what the "base.html" template, including the use of :doc:`static files
</howto/static-files/index>`, might look like:

.. snippet:: html+django
    :filename: mysite/templates/base.html

    {% load static %}
    <html>
    <head>
        <title>{% block title %}{% endblock %}</title>
    </head>
    
        
        {% block content %}{% endblock %}
    
    </html>

Simplistically, it defines the look-and-feel of the site (with the site's logo),
and provides "holes" for child templates to fill. This makes a site redesign as
easy as changing a single file -- the base template.

It also lets you create multiple versions of a site, with different base
templates, while reusing child templates. Django's creators have used this
technique to create strikingly different mobile versions of sites -- simply by
creating a new base template.

Note that you don't have to use Django's template system if you prefer another
system. While Django's template system is particularly well-integrated with
Django's model layer, nothing forces you to use it. For that matter, you don't
have to use Django's database API, either. You can use another database
abstraction layer, you can read XML files, you can read files off disk, or
anything you want. Each piece of Django -- models, views, templates -- is
decoupled from the next.

This is just the surface
========================

This has been only a quick overview of Django's functionality. Some more useful
features:

* A :doc:`caching framework </topics/cache>` that integrates with memcached
  or other backends.

* A :doc:`syndication framework </ref/contrib/syndication>` that makes
  creating RSS and Atom feeds as easy as writing a small Python class.

* More sexy automatically-generated admin features -- this overview barely
  scratched the surface.

The next obvious steps are for you to `download Django`_, read :doc:`the
tutorial ` and join `the community`_. Thanks for your
interest!

.. _download Django: https://www.djangoproject.com/download/
.. _the community: https://www.djangoproject.com/community/

---

### 大一小学期 Week 3 Python Exam 2016 Docs Intro Reusable Apps (`大一小学期/Week_3-Python/exam/2016/docs/intro/reusable-apps.txt`)

=============================================
Advanced tutorial: How to write reusable apps
=============================================

This advanced tutorial begins where :doc:`Tutorial 7 `
left off. We'll be turning our Web-poll into a standalone Python package
you can reuse in new projects and share with other people.

If you haven't recently completed Tutorials 1–7, we encourage you to review
these so that your example project matches the one described below.

Reusability matters
===================

It's a lot of work to design, build, test and maintain a web application. Many
Python and Django projects share common problems. Wouldn't it be great if we
could save some of this repeated work?

Reusability is the way of life in Python. `The Python Package Index (PyPI)
<https://pypi.python.org/pypi>`_ has a vast range of packages you can use in
your own Python programs. Check out `Django Packages
<https://www.djangopackages.com>`_ for existing reusable apps you could
incorporate in your project. Django itself is also just a Python package. This
means that you can take existing Python packages or Django apps and compose
them into your own web project. You only need to write the parts that make
your project unique.

Let's say you were starting a new project that needed a polls app like the one
we've been working on. How do you make this app reusable? Luckily, you're well
on the way already. In :doc:`Tutorial 3 `, we saw how we
could decouple polls from the project-level URLconf using an ``include``.
In this tutorial, we'll take further steps to make the app easy to use in new
projects and ready to publish for others to install and use.

.. admonition:: Package? App?

    A Python :term:`package` provides a way of grouping related Python code for
    easy reuse. A package contains one or more files of Python code (also known
    as "modules").

    A package can be imported with ``import foo.bar`` or ``from foo import
    bar``. For a directory (like ``polls``) to form a package, it must contain
    a special file ``__init__.py``, even if this file is empty.

    A Django *application* is just a Python package that is specifically
    intended for use in a Django project. An application may use common Django
    conventions, such as having ``models``, ``tests``, ``urls``, and ``views``
    submodules.

    Later on we use the term *packaging* to describe the process of making a
    Python package easy for others to install. It can be a little confusing, we
    know.

Your project and your reusable app
==================================

After the previous tutorials, our project should look like this::

    mysite/
        manage.py
        mysite/
            __init__.py
            settings.py
            urls.py
            wsgi.py
        polls/
            __init__.py
            admin.py
            migrations/
                __init__.py
                0001_initial.py
            models.py
            static/
                polls/
                    images/
                        background.gif
                    style.css
            templates/
                polls/
                    detail.html
                    index.html
                    results.html
            tests.py
            urls.py
            views.py
        templates/
            admin/
                base_site.html

You created ``mysite/templates`` in :doc:`Tutorial 7 `,
and ``polls/templates`` in :doc:`Tutorial 3 `. Now perhaps
it is clearer why we chose to have separate template directories for the
project and application: everything that is part of the polls application is in
``polls``. It makes the application self-contained and easier to drop into a
new project.

The ``polls`` directory could now be copied into a new Django project and
immediately reused. It's not quite ready to be published though. For that, we
need to package the app to make it easy for others to install.

.. _installing-reusable-apps-prerequisites:

Installing some prerequisites
=============================

The current state of Python packaging is a bit muddled with various tools. For
this tutorial, we're going to use setuptools_ to build our package. It's the
recommended packaging tool (merged with the ``distribute`` fork). We'll also be
using `pip`_ to install and uninstall it. You should install these
two packages now. If you need help, you can refer to :ref:`how to install
Django with pip`. You can install ``setuptools``
the same way.

.. _setuptools: https://pypi.python.org/pypi/setuptools
.. _pip: https://pypi.python.org/pypi/pip

Packaging your app
==================

Python *packaging* refers to preparing your app in a specific format that can
be easily installed and used. Django itself is packaged very much like
this. For a small app like polls, this process isn't too difficult.

1. First, create a parent directory for ``polls``, outside of your Django
   project. Call this directory ``django-polls``.

   .. admonition::  Choosing a name for your app

       When choosing a name for your package, check resources like PyPI to avoid
       naming conflicts with existing packages. It's often useful to prepend
       ``django-`` to your module name when creating a package to distribute.
       This helps others looking for Django apps identify your app as Django
       specific.

       Application labels (that is, the final part of the dotted path to
       application packages) *must* be unique in :setting:`INSTALLED_APPS`.
       Avoid using the same label as any of the Django :doc:`contrib packages
       </ref/contrib/index>`, for example ``auth``, ``admin``, or
       ``messages``.

2. Move the ``polls`` directory into the ``django-polls`` directory.

3. Create a file ``django-polls/README.rst`` with the following contents:

   .. snippet::
       :filename: django-polls/README.rst

       =====
       Polls
       =====

       Polls is a simple Django app to conduct Web-based polls. For each
       question, visitors can choose between a fixed number of answers.

       Detailed documentation is in the "docs" directory.

       Quick start
       -----------

       1. Add "polls" to your INSTALLED_APPS setting like this::

           INSTALLED_APPS = [
               ...
               'polls',
           ]

       2. Include the polls URLconf in your project urls.py like this::

           url(r'^polls/', include('polls.urls')),

       3. Run `python manage.py migrate` to create the polls models.

       4. Start the development server and visit http://127.0.0.1:8000/admin/
          to create a poll (you'll need the Admin app enabled).

       5. Visit http://127.0.0.1:8000/polls/ to participate in the poll.

4. Create a ``django-polls/LICENSE`` file. Choosing a license is beyond the
   scope of this tutorial, but suffice it to say that code released publicly
   without a license is *useless*. Django and many Django-compatible apps are
   distributed under the BSD license; however, you're free to pick your own
   license. Just be aware that your licensing choice will affect who is able
   to use your code.

5. Next we'll create a ``setup.py`` file which provides details about how to
   build and install the app.  A full explanation of this file is beyond the
   scope of this tutorial, but the `setuptools docs
   <https://setuptools.readthedocs.io/en/latest/>`_ have a good
   explanation. Create a file ``django-polls/setup.py`` with the following
   contents:

   .. snippet::
       :filename: django-polls/setup.py

       import os
       from setuptools import find_packages, setup

       with open(os.path.join(os.path.dirname(__file__), 'README.rst')) as readme:
           README = readme.read()

       # allow setup.py to be run from any path
       os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir)))

       setup(
           name='django-polls',
           version='0.1',
           packages=find_packages(),
           include_package_data=True,
           license='BSD License',  # example license
           description='A simple Django app to conduct Web-based polls.',
           long_description=README,
           url='https://www.example.com/',
           author='Your Name',
           author_email='[email protected]',
           classifiers=[
               'Environment :: Web Environment',
               'Framework :: Django',
               'Framework :: Django :: X.Y',  # replace "X.Y" as appropriate
               'Intended Audience :: Developers',
               'License :: OSI Approved :: BSD License',  # example license
               'Operating System :: OS Independent',
               'Programming Language :: Python',
               # Replace these appropriately if you are stuck on Python 2.
               'Programming Language :: Python :: 3',
               'Programming Language :: Python :: 3.4',
               'Programming Language :: Python :: 3.5',
               'Topic :: Internet :: WWW/HTTP',
               'Topic :: Internet :: WWW/HTTP :: Dynamic Content',
           ],
       )

6. Only Python modules and packages are included in the package by default. To
   include additional files, we'll need to create a ``MANIFEST.in`` file. The
   setuptools docs referred to in the previous step discuss this file in more
   details. To include the templates, the ``README.rst`` and our ``LICENSE``
   file, create a file ``django-polls/MANIFEST.in`` with the following
   contents:

   .. snippet::
       :filename: django-polls/MANIFEST.in

       include LICENSE
       include README.rst
       recursive-include polls/static *
       recursive-include polls/templates *

7. It's optional, but recommended, to include detailed documentation with your
   app. Create an empty directory ``django-polls/docs`` for future
   documentation. Add an additional line to ``django-polls/MANIFEST.in``::

    recursive-include docs *

   Note that the ``docs`` directory won't be included in your package unless
   you add some files to it. Many Django apps also provide their documentation
   online through sites like `readthedocs.org <https://readthedocs.org>`_.

8. Try building your package with ``python setup.py sdist`` (run from inside
   ``django-polls``). This creates a directory called ``dist`` and builds your
   new package, ``django-polls-0.1.tar.gz``.

For more information on packaging, see Python's `Tutorial on Packaging and
Distributing Projects <https://packaging.python.org/en/latest/distributing.html>`_.

Using your own package
======================

Since we moved the ``polls`` directory out of the project, it's no longer
working. We'll now fix this by installing our new ``django-polls`` package.

.. admonition:: Installing as a user library

   The following steps install ``django-polls`` as a user library. Per-user
   installs have a lot of advantages over installing the package system-wide,
   such as being usable on systems where you don't have administrator access
   as well as preventing the package from affecting system services and other
   users of the machine.

   Note that per-user installations can still affect the behavior of system
   tools that run as that user, so ``virtualenv`` is a more robust solution
   (see below).

1. To install the package, use pip (you already :ref:`installed it
   `, right?)::

    pip install --user django-polls/dist/django-polls-0.1.tar.gz

2. With luck, your Django project should now work correctly again. Run the
   server again to confirm this.

3. To uninstall the package, use pip::

    pip uninstall django-polls

.. _pip: https://pypi.python.org/pypi/pip

Publishing your app
===================

Now that we've packaged and tested ``django-polls``, it's ready to share with
the world! If this wasn't just an example, you could now:

* Email the package to a friend.

* Upload the package on your website.

* Post the package on a public repository, such as `the Python Package Index
  (PyPI)`_. `packaging.python.org <https://packaging.python.org>`_ has `a good
  tutorial <https://packaging.python.org/en/latest/distributing.html#uploading-your-project-to-pypi>`_
  for doing this.

Installing Python packages with virtualenv
==========================================

Earlier, we installed the polls app as a user library. This has some
disadvantages:

* Modifying the user libraries can affect other Python software on your system.

* You won't be able to run multiple versions of this package (or others with
  the same name).

Typically, these situations only arise once you're maintaining several Django
projects. When they do, the best solution is to use `virtualenv
<http://www.virtualenv.org/>`_. This tool allows you to maintain multiple
isolated Python environments, each with its own copy of the libraries and
package namespace.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Intro Tutorial01 (`大一小学期/Week_3-Python/exam/2016/docs/intro/tutorial01.txt`)

=====================================
Writing your first Django app, part 1
=====================================

Let's learn by example.

Throughout this tutorial, we'll walk you through the creation of a basic
poll application.

It'll consist of two parts:

* A public site that lets people view polls and vote in them.
* An admin site that lets you add, change, and delete polls.

We'll assume you have :doc:`Django installed ` already. You can
tell Django is installed and which version by running the following command:

.. code-block:: console

    $ python -m django --version

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".

This tutorial is written for Django |version| and Python 3.4 or 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 are still using Python
2.7, you will need to adjust the code samples slightly, as described in
comments.

See :doc:`How to install Django </topics/install>` for advice on how to remove
older versions of Django and install a newer one.

.. 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
    `_ to chat with other Django users who might
    be able to help.

Creating a project
==================

If this is your first time using Django, you'll have to take care of some
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,
including database configuration, Django-specific options and
application-specific settings.

From the command line, ``cd`` into a directory where you'd like to store your
code, then run the following command:

.. code-block:: console

   $ django-admin startproject mysite

This will create a ``mysite`` directory in your current directory. If it didn't
work, see :ref:`troubleshooting-django-admin`.

.. 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 ``test`` (which
    conflicts with a built-in Python package).

.. admonition:: Where should this code live?

    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.

    Put your code in some directory **outside** of the document root, such as
    :file:`/home/mycode`.

Let's look at what :djadmin:`startproject` created::

    mysite/
        manage.py
        mysite/
            __init__.py
            settings.py
            urls.py
            wsgi.py

These files are:

* The outer :file:`mysite/` root directory is just a container for your
  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`.

* 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
  anything inside it (e.g. ``mysite.urls``).

* :file:`mysite/__init__.py`: An empty file that tells Python that this
  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.

* :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`.

* :file:`mysite/wsgi.py`: An entry-point for WSGI-compatible web servers to
  serve your project. See :doc:`/howto/deployment/wsgi/index` for more details.

The development server
======================

Let's verify your Django project works. Change into the outer :file:`mysite` directory, if
you haven't already, and run the following commands:

.. code-block:: console

   $ python manage.py runserver

You'll see the following output on the command line:

.. parsed-literal::

    Performing system checks...

    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.

    |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.

.. note::
    Ignore the warning about unapplied database migrations for now; we'll deal
    with the database shortly.

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
browser. You'll see a "Welcome to Django" page, in pleasant, light-blue pastel.
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:

    .. code-block:: console

        $ python manage.py runserver 8080

    If you want to change the server's IP, pass it along with the port. So to
    listen on all public IPs (useful if you want to show off your work on other
    computers on your network), use:

    .. code-block:: console

        $ python manage.py runserver 0.0.0.0:8000

    Full docs for the development server can be found in the
    :djadmin:`runserver` reference.

.. 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.

Creating the Polls app
======================

Now that your environment -- a "project" -- is set up, you're set to start
doing work.

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.

.. admonition:: Projects vs. apps

    What's the difference between a project and an app? An app is a Web
    application that does something -- e.g., a Weblog system, a database of
    public records or a simple poll app. A project is a collection of
    configuration and apps for a particular website. A project can contain
    multiple apps. An app can be in multiple projects.

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``.

To create your app, make sure you're in the same directory as :file:`manage.py`
and type this command:

.. code-block:: console

    $ python manage.py startapp polls

That'll create a directory :file:`polls`, which is laid out like this::

    polls/
        __init__.py
        admin.py
        apps.py
        migrations/
            __init__.py
        models.py
        tests.py
        views.py

This directory structure will house the poll application.

Write your first view
=====================

Let's write the first view. Open the file ``polls/views.py``
and put the following Python code in it:

.. snippet::
    :filename: polls/views.py

    from django.http import HttpResponse


    def index(request):
        return HttpResponse("Hello, world. You're at the polls index.")

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.

To create a URLconf in the polls directory, create a file called ``urls.py``.
Your app directory should now look like::

    polls/
        __init__.py
        admin.py
        apps.py
        migrations/
            __init__.py
        models.py
        tests.py
        urls.py
        views.py

In the ``polls/urls.py`` file include the following code:

.. snippet::
    :filename: polls/urls.py

    from django.conf.urls import url

    from . import views

    urlpatterns = [
        url(r'^$', views.index, name='index'),
    ]

The next step is to point the root URLconf at the ``polls.urls`` module. In
``mysite/urls.py``, add an import for ``django.conf.urls.include`` and insert
an :func:`~django.conf.urls.include` in the ``urlpatterns`` list, so you have:

.. snippet::
    :filename: mysite/urls.py

    from django.conf.urls import include, url
    from django.contrib import admin

    urlpatterns = [
        url(r'^polls/', include('polls.urls')),
        url(r'^admin/', admin.site.urls),
    ]

The :func:`~django.conf.urls.include` function allows referencing other
URLconfs. Note that the regular expressions for the
:func:`~django.conf.urls.include` function doesn't have a ``$`` (end-of-string
match character) but rather a trailing slash. Whenever Django encounters
:func:`~django.conf.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.

The idea behind :func:`~django.conf.urls.include` is to make it easy to
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.

.. admonition:: When to use :func:`~django.conf.urls.include()`

    You should always use ``include()`` when you include other URL patterns.
    ``admin.site.urls`` is the only exception to this.

.. admonition:: Doesn't match what you see?

    If you're seeing ``include(admin.site.urls)`` instead of just
    ``admin.site.urls``, you're probably using a version of Django that
    doesn't match this tutorial version.  You'll want to either switch to the
    older tutorial or the newer Django version.

You have now wired an ``index`` view into the URLconf. Lets verify it's
working, run the following command:

.. code-block:: console

   $ python manage.py runserver

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.

The :func:`~django.conf.urls.url` function is passed four arguments, two
required: ``regex`` and ``view``, and two optional: ``kwargs``, and ``name``.
At this point, it's worth reviewing what these arguments are for.

:func:`~django.conf.urls.url` argument: regex
---------------------------------------------

The term "regex" is a commonly used short form meaning "regular expression",
which is a syntax for matching patterns in strings, or in this case, url
patterns. Django starts at the first regular expression and makes its way down
the list,  comparing the requested URL against each regular expression until it
finds one that matches.

Note that these regular expressions do not 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/``.

If you need help with regular expressions, see `Wikipedia's entry`_ and the
documentation of the :mod:`re` module. Also, the O'Reilly book "Mastering
Regular Expressions" by Jeffrey Friedl is fantastic. In practice, however,
you don't need to be an expert on regular expressions, as you really only need
to know how to capture simple patterns. In fact, complex regexes can have poor
lookup performance, so you probably shouldn't rely on the full power of regexes.

Finally, a performance note: these regular expressions are compiled the first
time the URLconf module is loaded. They're super fast (as long as the lookups
aren't too complex as noted above).

.. _Wikipedia's entry: https://en.wikipedia.org/wiki/Regular_expression

:func:`~django.conf.urls.url` argument: view
--------------------------------------------

When Django finds a regular expression match, Django calls the specified view
function, with an :class:`~django.http.HttpRequest` object as the first
argument and any “captured” values from the regular expression as other
arguments. If the regex uses simple captures, values are passed as positional
arguments; if it uses named captures, values are passed as keyword arguments.
We'll give an example of this in a bit.

:func:`~django.conf.urls.url` argument: kwargs
----------------------------------------------

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.

:func:`~django.conf.urls.url` argument: name
---------------------------------------------

Naming your URL lets you refer to it unambiguously from elsewhere in Django,
especially from within templates. This powerful feature allows you to make
global changes to the URL patterns of your project while only touching a single
file.

When you're comfortable with the basic request and response flow, read
:doc:`part 2 of this tutorial ` to start working with the
database.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Intro Tutorial02 (`大一小学期/Week_3-Python/exam/2016/docs/intro/tutorial02.txt`)

=====================================
Writing your first Django app, part 2
=====================================

This tutorial begins where :doc:`Tutorial 1 ` left off.
We'll setup the database, create your first model, and get a quick introduction
to Django's automatically-generated admin site.

Database setup
==============

Now, open up :file:`mysite/settings.py`. It's a normal Python module with
module-level variables representing Django settings.

By default, the configuration uses SQLite. If you're new to databases, or
you're just interested in trying Django, this is the easiest choice. SQLite is
included in Python, so you won't need to install anything else to support your
database. When starting your first real project, however, you may want to use a
more robust database like PostgreSQL, to avoid database-switching headaches
down the road.

If you wish to use another database, install the appropriate :ref:`database
bindings <database-installation>` and change the following keys in the
:setting:`DATABASES` ``'default'`` item to match your database connection
settings:

* :setting:`ENGINE <DATABASE-ENGINE>` -- Either
  ``'django.db.backends.sqlite3'``,
  ``'django.db.backends.postgresql'``,
  ``'django.db.backends.mysql'``, or
  ``'django.db.backends.oracle'``. Other backends are :ref:`also available
  `.

* :setting:`NAME` -- The name of your database. If you're using SQLite, the
  database will be a file on your computer; in that case, :setting:`NAME`
  should be the full absolute path, including filename, of that file. The
  default value, ``os.path.join(BASE_DIR, 'db.sqlite3')``, will store the file
  in your project directory.

If you are not using SQLite as your database, additional settings such as
:setting:`USER`, :setting:`PASSWORD`, and :setting:`HOST` must be added.
For more details, see the reference documentation for :setting:`DATABASES`.

.. admonition:: For databases other than SQLite

    If you're using a database besides SQLite, make sure you've created a
    database by this point. Do that with "``CREATE DATABASE database_name;``"
    within your database's interactive prompt.

    Also make sure that the database user provided in :file:`mysite/settings.py`
    has "create database" privileges. This allows automatic creation of a
    :ref:`test database ` which will be needed in a later
    tutorial.

    If you're using SQLite, you don't need to create anything beforehand - the
    database file will be created automatically when it is needed.

While you're editing :file:`mysite/settings.py`, set :setting:`TIME_ZONE` to
your time zone.

Also, note the :setting:`INSTALLED_APPS` setting at the top of the file. That
holds the names of all Django applications that are activated in this Django
instance. Apps can be used in multiple projects, and you can package and
distribute them for use by others in their projects.

By default, :setting:`INSTALLED_APPS` contains the following apps, all of which
come with Django:

* :mod:`django.contrib.admin` -- The admin site. You'll use it shortly.

* :mod:`django.contrib.auth` -- An authentication system.

* :mod:`django.contrib.contenttypes` -- A framework for content types.

* :mod:`django.contrib.sessions` -- A session framework.

* :mod:`django.contrib.messages` -- A messaging framework.

* :mod:`django.contrib.staticfiles` -- A framework for managing
  static files.

These applications are included by default as a convenience for the common case.

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

.. code-block:: console

    $ python manage.py migrate

The :djadmin:`migrate` command looks at the :setting:`INSTALLED_APPS` setting
and creates any necessary database tables according to the database settings
in your :file:`mysite/settings.py` file and the database migrations shipped
with the app (we'll cover those later). You'll see a message for each
migration it applies. If you're interested, run the command-line client for your
database and type ``\dt`` (PostgreSQL), ``SHOW TABLES;`` (MySQL), ``.schema``
(SQLite), or ``SELECT TABLE_NAME FROM USER_TABLES;`` (Oracle) to display the
tables Django created.

.. admonition:: For the minimalists

    Like we said above, the default applications are included for the common
    case, but not everybody needs them. If you don't need any or all of them,
    feel free to comment-out or delete the appropriate line(s) from
    :setting:`INSTALLED_APPS` before running :djadmin:`migrate`. The
    :djadmin:`migrate` command will only run migrations for apps in
    :setting:`INSTALLED_APPS`.

.. _creating-models:

Creating models
===============

Now we'll define your models -- essentially, your database layout, with
additional metadata.

.. admonition:: Philosophy

   A model is the single, definitive source of truth about your data. It contains
   the essential fields and behaviors of the data you're storing. Django follows
   the :ref:`DRY Principle <dry>`. The goal is to define your data model in one
   place and automatically derive things from it.

   This includes the migrations - unlike in Ruby On Rails, for example, migrations
   are entirely derived from your models file, and are essentially just a
   history that Django can roll through to update your database schema to
   match your current models.

In our simple poll app, we'll create two models: ``Question`` and ``Choice``.
A ``Question`` has a question and a publication date. A ``Choice`` has two
fields: the text of the choice and a vote tally. Each ``Choice`` is associated
with a ``Question``.

These concepts are represented by simple Python classes. Edit the
:file:`polls/models.py` file so it looks like this:

.. snippet::
    :filename: polls/models.py

    from django.db import models


    class Question(models.Model):
        question_text = models.CharField(max_length=200)
        pub_date = models.DateTimeField('date published')


    class Choice(models.Model):
        question = models.ForeignKey(Question, on_delete=models.CASCADE)
        choice_text = models.CharField(max_length=200)
        votes = models.IntegerField(default=0)

The code is straightforward. Each model is represented by a class that
subclasses :class:`django.db.models.Model`. Each model has a number of class
variables, each of which represents a database field in the model.

Each field is represented by an instance of a :class:`~django.db.models.Field`
class -- e.g., :class:`~django.db.models.CharField` for character fields and
:class:`~django.db.models.DateTimeField` for datetimes. This tells Django what
type of data each field holds.

The name of each :class:`~django.db.models.Field` instance (e.g.
``question_text`` or ``pub_date``) is the field's name, in machine-friendly
format. You'll use this value in your Python code, and your database will use
it as the column name.

You can use an optional first positional argument to a
:class:`~django.db.models.Field` to designate a human-readable name. That's used
in a couple of introspective parts of Django, and it doubles as documentation.
If this field isn't provided, Django will use the machine-readable name. In this
example, we've only defined a human-readable name for ``Question.pub_date``.
For all other fields in this model, the field's machine-readable name will
suffice as its human-readable name.

Some :class:`~django.db.models.Field` classes have required arguments.
:class:`~django.db.models.CharField`, for example, requires that you give it a
:attr:`~django.db.models.CharField.max_length`. That's used not only in the
database schema, but in validation, as we'll soon see.

A :class:`~django.db.models.Field` can also have various optional arguments; in
this case, we've set the :attr:`~django.db.models.Field.default` value of
``votes`` to 0.

Finally, note a relationship is defined, using
:class:`~django.db.models.ForeignKey`. That tells Django each ``Choice`` is
related to a single ``Question``. Django supports all the common database
relationships: many-to-one, many-to-many, and one-to-one.

Activating models
=================

That small bit of model code gives Django a lot of information. With it, Django
is able to:

* Create a database schema (``CREATE TABLE`` statements) for this app.
* Create a Python database-access API for accessing ``Question`` and ``Choice`` objects.

But first we need to tell our project that the ``polls`` app is installed.

.. admonition:: Philosophy

    Django apps are "pluggable": You can use an app in multiple projects, and
    you can distribute apps, because they don't have to be tied to a given
    Django installation.

Edit the :file:`mysite/settings.py` file again, and change the
:setting:`INSTALLED_APPS` setting to include the string
``'polls.apps.PollsConfig'``. It'll look like this:

.. snippet::
    :filename: mysite/settings.py

    INSTALLED_APPS = [
        'polls.apps.PollsConfig',
        'django.contrib.admin',
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.messages',
        'django.contrib.staticfiles',
    ]

Now Django knows to include the ``polls`` app. Let's run another command:

.. code-block:: console

    $ python manage.py makemigrations polls

You should see something similar to the following:

.. code-block:: text

    Migrations for 'polls':
      polls/migrations/0001_initial.py:
        - Create model Choice
        - Create model Question
        - Add field question to choice

By running ``makemigrations``, you're telling Django that you've made
some changes to your models (in this case, you've made new ones) and that
you'd like the changes to be stored as a *migration*.

Migrations are how Django stores changes to your models (and thus your
database schema) - they're just files on disk. You can read the migration
for your new model if you like; it's the file
``polls/migrations/0001_initial.py``. Don't worry, you're not expected to read
them every time Django makes one, but they're designed to be human-editable
in case you want to manually tweak how Django changes things.

There's a command that will run the migrations for you and manage your database
schema automatically - that's called :djadmin:`migrate`, and we'll come to it in a
moment - but first, let's see what SQL that migration would run. The
:djadmin:`sqlmigrate` command takes migration names and returns their SQL:

.. code-block:: console

    $ python manage.py sqlmigrate polls 0001

You should see something similar to the following (we've reformatted it for
readability):

.. code-block:: sql

    BEGIN;
    --
    -- Create model Choice
    --
    CREATE TABLE "polls_choice" (
        "id" serial NOT NULL PRIMARY KEY,
        "choice_text" varchar(200) NOT NULL,
        "votes" integer NOT NULL
    );
    --
    -- Create model Question
    --
    CREATE TABLE "polls_question" (
        "id" serial NOT NULL PRIMARY KEY,
        "question_text" varchar(200) NOT NULL,
        "pub_date" timestamp with time zone NOT NULL
    );
    --
    -- Add field question to choice
    --
    ALTER TABLE "polls_choice" ADD COLUMN "question_id" integer NOT NULL;
    ALTER TABLE "polls_choice" ALTER COLUMN "question_id" DROP DEFAULT;
    CREATE INDEX "polls_choice_7aa0f6ee" ON "polls_choice" ("question_id");
    ALTER TABLE "polls_choice"
      ADD CONSTRAINT "polls_choice_question_id_246c99a640fbbd72_fk_polls_question_id"
        FOREIGN KEY ("question_id")
        REFERENCES "polls_question" ("id")
        DEFERRABLE INITIALLY DEFERRED;

    COMMIT;

Note the following:

* The exact output will vary depending on the database you are using. The
  example above is generated for PostgreSQL.

* Table names are automatically generated by combining the name of the app
  (``polls``) and the lowercase name of the model -- ``question`` and
  ``choice``. (You can override this behavior.)

* Primary keys (IDs) are added automatically. (You can override this, too.)

* By convention, Django appends ``"_id"`` to the foreign key field name.
  (Yes, you can override this, as well.)

* The foreign key relationship is made explicit by a ``FOREIGN KEY``
  constraint. Don't worry about the ``DEFERRABLE`` parts; that's just telling
  PostgreSQL to not enforce the foreign key until the end of the transaction.

* It's tailored to the database you're using, so database-specific field types
  such as ``auto_increment`` (MySQL), ``serial`` (PostgreSQL), or ``integer
  primary key autoincrement`` (SQLite) are handled for you automatically. Same
  goes for the quoting of field names -- e.g., using double quotes or
  single quotes.

* The :djadmin:`sqlmigrate` command doesn't actually run the migration on your
  database - it just prints it to the screen so that you can see what SQL
  Django thinks is required. It's useful for checking what Django is going to
  do or if you have database administrators who require SQL scripts for
  changes.

If you're interested, you can also run
:djadmin:`python manage.py check <check>`; this checks for any problems in
your project without making migrations or touching the database.

Now, run :djadmin:`migrate` again to create those model tables in your database:

.. code-block:: console

    $ python manage.py migrate
    Operations to perform:
      Apply all migrations: admin, auth, contenttypes, polls, sessions
    Running migrations:
      Rendering model states... DONE
      Applying polls.0001_initial... OK

The :djadmin:`migrate` command takes all the migrations that haven't been
applied (Django tracks which ones are applied using a special table in your
database called ``django_migrations``) and runs them against your database -
essentially, synchronizing the changes you made to your models with the schema
in the database.

Migrations are very powerful and let you change your models over time, as you
develop your project, without the need to delete your database or tables and
make new ones - it specializes in upgrading your database live, without
losing data. We'll cover them in more depth in a later part of the tutorial,
but for now, remember the three-step guide to making model changes:

* Change your models (in ``models.py``).
* Run :djadmin:`python manage.py makemigrations <makemigrations>` to create
  migrations for those changes
* Run :djadmin:`python manage.py migrate <migrate>` to apply those changes to
  the database.

The reason that there are separate commands to make and apply migrations is
because you'll commit migrations to your version control system and ship them
with your app; they not only make your development easier, they're also
useable by other developers and in production.

Read the :doc:`django-admin documentation </ref/django-admin>` for full
information on what the ``manage.py`` utility can do.

Playing with the API
====================

Now, let's hop into the interactive Python shell and play around with the free
API Django gives you. To invoke the Python shell, use this command:

.. code-block:: console

    $ python manage.py shell

We're using this instead of simply typing "python", because :file:`manage.py`
sets the ``DJANGO_SETTINGS_MODULE`` environment variable, which gives Django
the Python import path to your :file:`mysite/settings.py` file.

.. admonition:: Bypassing manage.py

    If you'd rather not use :file:`manage.py`, no problem. Just set the
    :envvar:`DJANGO_SETTINGS_MODULE` environment variable to
    ``mysite.settings``, start a plain Python shell, and set up Django:

    .. code-block:: pycon

        >>> import django
        >>> django.setup()

    If this raises an :exc:`AttributeError`, you're probably using
    a version of Django that doesn't match this tutorial version. You'll want
    to either switch to the older tutorial or the newer Django version.

    You must run ``python`` from the same directory :file:`manage.py` is in,
    or ensure that directory is on the Python path, so that ``import mysite``
    works.

    For more information on all of this, see the :doc:`django-admin
    documentation </ref/django-admin>`.

Once you're in the shell, explore the :doc:`database API </topics/db/queries>`::

    >>> from polls.models import Question, Choice   # Import the model classes we just wrote.

    # No questions are in the system yet.
    >>> Question.objects.all()
    <QuerySet []>

    # Create a new Question.
    # Support for time zones is enabled in the default settings file, so
    # Django expects a datetime with tzinfo for pub_date. Use timezone.now()
    # instead of datetime.datetime.now() and it will do the right thing.
    >>> from django.utils import timezone
    >>> q = Question(question_text="What's new?", pub_date=timezone.now())

    # Save the object into the database. You have to call save() explicitly.
    >>> q.save()

    # Now it has an ID. Note that this might say "1L" instead of "1", depending
    # on which database you're using. That's no biggie; it just means your
    # database backend prefers to return integers as Python long integer
    # objects.
    >>> q.id
    1

    # Access model field values via Python attributes.
    >>> q.question_text
    "What's new?"
    >>> q.pub_date
    datetime.datetime(2012, 2, 26, 13, 0, 0, 775217, tzinfo=)

    # Change values by changing the attributes, then calling save().
    >>> q.question_text = "What's up?"
    >>> q.save()

    # objects.all() displays all the questions in the database.
    >>> Question.objects.all()
    <QuerySet [<Question: Question object>]>

Wait a minute. ``<Question: Question object>`` is, utterly, an unhelpful representation
of this object. Let's fix that by editing the ``Question`` model (in the
``polls/models.py`` file) and adding a
:meth:`~django.db.models.Model.__str__` method to both ``Question`` and
``Choice``:

.. snippet::
    :filename: polls/models.py

    from django.db import models
    from django.utils.encoding import python_2_unicode_compatible

    @python_2_unicode_compatible  # only if you need to support Python 2
    class Question(models.Model):
        # ...
        def __str__(self):
            return self.question_text

    @python_2_unicode_compatible  # only if you need to support Python 2
    class Choice(models.Model):
        # ...
        def __str__(self):
            return self.choice_text

It's important to add :meth:`~django.db.models.Model.__str__` methods to your
models, not only for your own convenience when dealing with the interactive
prompt, but also because objects' representations are used throughout Django's
automatically-generated admin.

Note these are normal Python methods. Let's add a custom method, just for
demonstration:

.. snippet::
    :filename: polls/models.py

    import datetime

    from django.db import models
    from django.utils import timezone


    class Question(models.Model):
        # ...
        def was_published_recently(self):
            return self.pub_date >= timezone.now() - datetime.timedelta(days=1)

Note the addition of ``import datetime`` and ``from django.utils import
timezone``, to reference Python's standard :mod:`datetime` module and Django's
time-zone-related utilities in :mod:`django.utils.timezone`, respectively. If
you aren't familiar with time zone handling in Python, you can learn more in
the :doc:`time zone support docs </topics/i18n/timezones>`.

Save these changes and start a new Python interactive shell by running
``python manage.py shell`` again::

    >>> from polls.models import Question, Choice

    # Make sure our __str__() addition worked.
    >>> Question.objects.all()
    <QuerySet [<Question: What's up?>]>

    # Django provides a rich database lookup API that's entirely driven by
    # keyword arguments.
    >>> Question.objects.filter(id=1)
    <QuerySet [<Question: What's up?>]>
    >>> Question.objects.filter(question_text__startswith='What')
    <QuerySet [<Question: What's up?>]>

    # Get the question that was published this year.
    >>> from django.utils import timezone
    >>> current_year = timezone.now().year
    >>> Question.objects.get(pub_date__year=current_year)
    <Question: What's up?>

    # Request an ID that doesn't exist, this will raise an exception.
    >>> Question.objects.get(id=2)
    Traceback (most recent call last):
        ...
    DoesNotExist: Question matching query does not exist.

    # Lookup by a primary key is the most common case, so Django provides a
    # shortcut for primary-key exact lookups.
    # The following is identical to Question.objects.get(id=1).
    >>> Question.objects.get(pk=1)
    <Question: What's up?>

    # Make sure our custom method worked.
    >>> q = Question.objects.get(pk=1)
    >>> q.was_published_recently()
    True

    # Give the Question a couple of Choices. The create call constructs a new
    # Choice object, does the INSERT statement, adds the choice to the set
    # of available choices and returns the new Choice object. Django creates
    # a set to hold the "other side" of a ForeignKey relation
    # (e.g. a question's choice) which can be accessed via the API.
    >>> q = Question.objects.get(pk=1)

    # Display any choices from the related object set -- none so far.
    >>> q.choice_set.all()
    <QuerySet []>

    # Create three choices.
    >>> q.choice_set.create(choice_text='Not much', votes=0)
    <Choice: Not much>
    >>> q.choice_set.create(choice_text='The sky', votes=0)
    <Choice: The sky>
    >>> c = q.choice_set.create(choice_text='Just hacking again', votes=0)

    # Choice objects have API access to their related Question objects.
    >>> c.question
    <Question: What's up?>

    # And vice versa: Question objects get access to Choice objects.
    >>> q.choice_set.all()
    <QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>
    >>> q.choice_set.count()
    3

    # 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 question whose pub_date is in this year
    # (reusing the 'current_year' variable we created above).
    >>> Choice.objects.filter(question__pub_date__year=current_year)
    <QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>

    # Let's delete one of the choices. Use delete() for that.
    >>> c = q.choice_set.filter(choice_text__startswith='Just hacking')
    >>> c.delete()

For more information on model relations, see :doc:`Accessing related objects
</ref/models/relations>`. For more on how to use double underscores to perform
field lookups via the API, see :ref:`Field lookups <field-lookups-intro>`. For
full details on the database API, see our :doc:`Database API reference
</topics/db/queries>`.

Introducing the Django Admin
============================

.. admonition:: Philosophy

    Generating admin sites for your staff or clients to add, change, and delete
    content is tedious work that doesn't require much creativity. For that
    reason, Django entirely automates creation of admin interfaces for models.

    Django was written in a newsroom environment, with a very clear separation
    between "content publishers" and the "public" site. Site managers use the
    system to add news stories, events, sports scores, etc., and that content is
    displayed on the public site. Django solves the problem of creating a
    unified interface for site administrators to edit content.

    The admin isn't intended to be used by site visitors. It's for site
    managers.

Creating an admin user
----------------------

First we'll need to create a user who can login to the admin site. Run the
following command:

.. code-block:: console

    $ python manage.py createsuperuser

Enter your desired username and press enter.

.. code-block:: text

    Username: admin

You will then be prompted for your desired email address:

.. code-block:: text

    Email address: [email protected]

The final step is to enter your password. You will be asked to enter your
password twice, the second time as a confirmation of the first.

.. code-block:: text

    Password: **********
    Password (again): *********
    Superuser created successfully.

Start the development server
----------------------------

The Django admin site is activated by default. Let's start the development
server and explore it.

If the server is not running start it like so:

.. code-block:: console

    $ python manage.py runserver

Now, open a Web browser and go to "/admin/" on your local domain -- e.g.,
http://127.0.0.1:8000/admin/. You should see the admin's login screen:

.. image:: _images/admin01.png
   :alt: Django admin login screen

Since :doc:`translation </topics/i18n/translation>` is turned on by default,
the login screen may be displayed in your own language, depending on your
browser's settings and if Django has a translation for this language.

Enter the admin site
--------------------

Now, try logging in with the superuser account you created in the previous step.
You should see the Django admin index page:

.. image:: _images/admin02.png
   :alt: Django admin index page

You should see a few types of editable content: groups and users. They are
provided by :mod:`django.contrib.auth`, the authentication framework shipped
by Django.

Make the poll app modifiable in the admin
-----------------------------------------

But where's our poll app? It's not displayed on the admin index page.

Just one thing to do: we need to tell the admin that ``Question``
objects have an admin interface. To do this, open the :file:`polls/admin.py`
file, and edit it to look like this:

.. snippet::
    :filename: polls/admin.py

    from django.contrib import admin

    from .models import Question

    admin.site.register(Question)

Explore the free admin functionality
------------------------------------

Now that we've registered ``Question``, Django knows that it should be displayed on
the admin index page:

.. image:: _images/admin03t.png
   :alt: Django admin index page, now with polls displayed

Click "Questions". Now you're at the "change list" page for questions. This page
displays all the questions in the database and lets you choose one to change it.
There's the "What's up?" question we created earlier:

.. image:: _images/admin04t.png
   :alt: Polls change list page

Click the "What's up?" question to edit it:

.. image:: _images/admin05t.png
   :alt: Editing form for question object

Things to note here:

* The form is automatically generated from the ``Question`` model.

* The different model field types (:class:`~django.db.models.DateTimeField`,
  :class:`~django.db.models.CharField`) correspond to the appropriate HTML
  input widget. Each type of field knows how to display itself in the Django
  admin.

* Each :class:`~django.db.models.DateTimeField` gets free JavaScript
  shortcuts. Dates get a "Today" shortcut and calendar popup, and times get
  a "Now" shortcut and a convenient popup that lists commonly entered times.

The bottom part of the page gives you a couple of options:

* Save -- Saves changes and returns to the change-list page for this type of
  object.

* Save and continue editing -- Saves changes and reloads the admin page for
  this object.

* Save and add another -- Saves changes and loads a new, blank form for this
  type of object.

* Delete -- Displays a delete confirmation page.

If the value of "Date published" doesn't match the time when you created the
question in :doc:`Tutorial 1`, it probably
means you forgot to set the correct value for the :setting:`TIME_ZONE` setting.
Change it, reload the page and check that the correct value appears.

Change the "Date published" by clicking the "Today" and "Now" shortcuts. Then
click "Save and continue editing." Then click "History" in the upper right.
You'll see a page listing all changes made to this object via the Django admin,
with the timestamp and username of the person who made the change:

.. image:: _images/admin06t.png
   :alt: History page for question object

When you're comfortable with the models API and have familiarized yourself with
the admin site, read :doc:`part 3 of this tutorial` to learn
about how to add more views to our polls app.

---

### 大一小学期 Week 3 Python Exam 2016 Docs Intro Tutorial03 (`大一小学期/Week_3-Python/exam/2016/docs/intro/tutorial03.txt`)

=====================================
Writing your first Django app, part 3
=====================================

This tutorial begins where :doc:`Tutorial 2 ` left off. We're
continuing the Web-poll application and will focus on creating the public
interface -- "views."

Overview
========

A view is a "type" of Web page in your Django application that generally serves
a specific function and has a specific template. For example, in a blog
application, you might have the following views:

* Blog homepage -- displays the latest few entries.

* Entry "detail" page -- permalink page for a single entry.

* Year-based archive page -- displays all months with entries in the
  given year.

* Month-based archive page -- displays all days with entries in the
  given month.

* Day-based archive page -- displays all entries in the given day.

* Comment action -- handles posting comments to a given entry.

In our poll application, we'll have the following four views:

* Question "index" page -- displays the latest few questions.

* Question "detail" page -- displays a question text, with no results but
  with a form to vote.

* Question "results" page -- displays results for a particular question.

* Vote action -- handles voting for a particular choice in a particular
  question.

In Django, web pages and other content are delivered by views. Each view is
represented by a simple Python function (or method, in the case of class-based
views). Django will choose a view by examining the URL that's requested (to be
precise, the part of the URL after the domain name).

Now in your time on the web you may have come across such beauties as
"ME2/Sites/dirmod.asp?sid=&type=gen&mod=Core+Pages&gid=A6CD4967199A42D9B65B1B".
You will be pleased to know that Django allows us much more elegant
*URL patterns* than that.

A URL pattern is simply the general form of a URL - for example:
``/newsarchive/<year>/<month>/``.

To get from a URL to a view, Django uses what are known as 'URLconfs'. A
URLconf maps URL patterns (described as regular expressions) to views.

This tutorial provides basic instruction in the use of URLconfs, and you can
refer to :mod:`django.urls` for more information.

Writing more views
==================

Now let's add a few more views to ``polls/views.py``. These views are
slightly different, because they take an argument:

.. snippet::
    :filename: polls/views.py

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

    def results(request, question_id):
        response = "You're looking at the results of question %s."
        return HttpResponse(response % question_id)

    def vote(request, question_id):
        return HttpResponse("You're voting on question %s." % question_id)

Wire these new views into the ``polls.urls`` module by adding the following
:func:`~django.conf.urls.url` calls:

.. snippet::
    :filename: polls/urls.py

    from django.conf.urls import url

    from . import views

    urlpatterns = [
        # ex: /polls/
        url(r'^$', views.index, name='index'),
        # ex: /polls/5/
        url(r'^(?P<question_id>[0-9]+)/$', views.detail, name='detail'),
        # ex: /polls/5/results/
        url(r'^(?P<question_id>[0-9]+)/results/$', views.results, name='results'),
        # ex: /polls/5/vote/
        url(r'^(?P<question_id>[0-9]+)/vote/$', views.vote, name='vote'),
    ]

Take a look in your browser, at "/polls/34/". It'll run the ``detail()``
method and display whatever ID you provide in the URL. Try
"/polls/34/results/" and "/polls/34/vote/" too -- these will display the
placeholder results and voting pages.

When somebody requests a page from your website -- say, "/polls/34/", Django
will load the ``mysite.urls`` Python module because it's pointed to by the
:setting:`ROOT_URLCONF` setting. It finds the variable named ``urlpatterns``
and traverses the regular expressions in order. After finding the match at
``'^polls/'``, it strips off the matching text (``"polls/"``) and sends the
remaining text -- ``"34/"`` -- to the 'polls.urls' URLconf for further
processing. There it matches ``r'^(?P<question_id>[0-9]+)/$'``, resulting in a
call to the ``detail()`` view like so::

    detail(request=<HttpRequest object>, question_id='34')

The ``question_id='34'`` part comes from ``(?P<question_id>[0-9]+)``. Using parentheses
around a pattern "captures" the text matched by that pattern and sends it as an
argument to the view function; ``?P<question_id>`` defines the name that will
be used to identify the matched pattern; and ``[0-9]+`` is a regular expression to
match a sequence of digits (i.e., a number).

Because the URL patterns are regular expressions, there really is no limit on
what you can do with them. And there's no need to add URL cruft such as
``.html`` -- unless you want to, in which case you can do something like
this::

    url(r'^polls/latest\.html$', views.index),

But, don't do that. It's silly.

Write views that actually do something
======================================

Each view is responsible for doing one of two things: returning an
:class:`~django.http.HttpResponse` object containing the content for the
requested page, or raising an exception such as :exc:`~django.http.Http404`. The
rest is up to you.

Your view can read records from a database, or not. It can use a template
system such as Django's -- or a third-party Python template system -- or not.
It can generate a PDF file, output XML, create a ZIP file on the fly, anything
you want, using whatever Python libraries you want.

All Django wants is that :class:`~django.http.HttpResponse`. Or an exception.

Because it's convenient, let's use Django's own database API, which we covered
in :doc:`Tutorial 2 `. Here's one stab at a new ``index()``
view, which displays the latest 5 poll questions in the system, separated by
commas, according to publication date:

.. snippet::
    :filename: polls/views.py

    from django.http import HttpResponse

    from .models import Question


    def index(request):
        latest_question_list = Question.objects.order_by('-pub_date')[:5]
        output = ', '.join([q.question_text for q in latest_question_list])
        return HttpResponse(output)

    # Leave the rest of the views (detail, results, vote) unchanged

There's a problem here, though: the page's design is hard-coded in the view. If
you want to change the way the page looks, you'll have to edit this Python code.
So let's use Django's template system to separate the design from Python by
creating a template that the view can use.

First, create a directory called ``templates`` in your ``polls`` directory.
Django will look for templates in there.

Your project's :setting:`TEMPLATES` setting describes how Django will load and
render templates. The default settings file configures a ``DjangoTemplates``
backend whose :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` option is set to
``True``. By convention ``DjangoTemplates`` looks for a "templates"
subdirectory in each of the :setting:`INSTALLED_APPS`.

Within the ``templates`` directory you have just created, create another
directory called ``polls``, and within that create a file called
``index.html``. In other words, your template should be at
``polls/templates/polls/index.html``. Because of how the ``app_directories``
template loader works as described above, you can refer to this template within
Django simply as ``polls/index.html``.

.. admonition:: Template namespacing

    Now we *might* be able to get away with putting our templates directly in
    ``polls/templates`` (rather than creating another ``polls`` subdirectory),
    but it would actually be a bad idea. Django will choose the first template
    it finds whose name matches, and if you had a template with the same name
    in a *different* application, Django would be unable to distinguish between
    them. We need to be able to point Django at the right one, and the easiest
    way to ensure this is by *namespacing* them. That is, by putting those
    templates inside *another* directory named for the application itself.

Put the following code in that template:

.. snippet:: html+django
    :filename: polls/templates/polls/index.html

    {% if latest_question_list %}
        
        {% for question in latest_question_list %}
            <li>[{{ question.question_text }}](/polls/{{ question.id }}/)</li>
        {% endfor %}
        
    {% else %}
        No polls are available.
    {% endif %}

Now let's update our ``index`` view in ``polls/views.py`` to use the template:

.. snippet::
    :filename: polls/views.py

    from django.http import HttpResponse
    from django.template import loader

    from .models import Question


    def index(request):
        latest_question_list = Question.objects.order_by('-pub_date')[:5]
        template = loader.get_template('polls/index.html')
        context = {
            'latest_question_list': latest_question_list,
        }
        return HttpResponse(template.render(context, request))

That code loads the template called  ``polls/index.html`` and passes it a
context. The context is a dictionary mapping template variable names to Python
objects.

Load the page by pointing your browser at "/polls/", and you should see a
bulleted-list containing the "What's up" question from :doc:`Tutorial 2
`. The link points to the question's detail page.

A shortcut: :func:`~django.shortcuts.render`
--------------------------------------------

It's a very common idiom to load a template, fill a context and return an
:class:`~django.http.HttpResponse` object with the result of the rendered
template. Django provides a shortcut. Here's the full ``index()`` view,
rewritten:

.. snippet::
    :filename: polls/views.py

    from django.shortcuts import render

    from .models import Question


    def index(request):
        latest_question_list = Question.objects.order_by('-pub_date')[:5]
        context = {'latest_question_list': latest_question_list}
        return render(request, 'polls/index.html', context)

Note that once we've done this in all these views, we no longer need to import
:mod:`~django.template.loader` and :class:`~django.http.HttpResponse` (you'll
want to keep ``HttpResponse`` if you still have the stub methods for ``detail``,
``results``, and ``vote``).

The :func:`~django.shortcuts.render` function takes the request object as its
first argument, a template name as its second argument and a dictionary as its
optional third argument. It returns an :class:`~django.http.HttpResponse`
object of the given template rendered with the given context.

Raising a 404 error
===================

Now, let's tackle the question detail view -- the page that displays the question text
for a given poll. Here's the view:

.. snippet::
    :filename: polls/views.py

    from django.http import Http404
    from django.shortcuts import render

    from .models import Question
    # ...
    def detail(request, question_id):
        try:
            question = Question.objects.get(pk=question_id)
        except Question.DoesNotExist:
            raise Http404("Question does not exist")
        return render(request, 'polls/detail.html', {'question': question})

The new concept here: The view raises the :exc:`~django.http.Http404` exception
if a question with the requested ID doesn't exist.

We'll discuss what you could put in that ``polls/detail.html`` template a bit
later, but if you'd like to quickly get the above example working, a file
containing just:

.. snippet:: html+django
    :filename: polls/templates/polls/detail.html

    {{ question }}

will get you started for now.

A shortcut: :func:`~django.shortcuts.get_object_or_404`
-------------------------------------------------------

It's a very common idiom to use :meth:`~django.db.models.query.QuerySet.get`
and raise :exc:`~django.http.Htt