mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-08-03 18:38:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Added missing markup to docs.

Browse source
This commit is contained in:
Tim Graham 2013-03-22 05:50:45 -04:00
parent 0df59bc212
commit 93cffc3b37
37 changed files with 170 additions and 155 deletions
Download patch file Download diff file Expand all files Collapse all files

56
docs/topics/auth/customizing.txt
View file

@ -103,12 +103,14 @@ the time, it'll just look like this::
class MyBackend(object):
def authenticate(self, username=None, password=None):
# Check the username/password and return a User.
...
But it could also authenticate a token, like so::
class MyBackend(object):
def authenticate(self, token=None):
# Check the token and return a User.
...
Either way, ``authenticate`` should check the credentials it gets, and it
should return a ``User`` object that matches those credentials, if the
@ -183,9 +185,7 @@ The simple backend above could implement permissions for the magic admin
fairly simply::
class SettingsBackend(object):
# ...
...
def has_perm(self, user_obj, perm, obj=None):
if user_obj.username == settings.ADMIN_LOGIN:
return True
@ -482,7 +482,7 @@ Django expects your custom User model to meet some minimum requirements.
The easiest way to construct a compliant custom User model is to inherit from
:class:`~django.contrib.auth.models.AbstractBaseUser`.
:class:`~django.contrib.auth.models.AbstractBaseUser` provides the core
implementation of a `User` model, including hashed passwords and tokenized
implementation of a ``User`` model, including hashed passwords and tokenized
password resets. You must then provide some key implementation details:
.. currentmodule:: django.contrib.auth
@ -497,7 +497,7 @@ password resets. You must then provide some key implementation details:
identifier. The field *must* be unique (i.e., have ``unique=True``
set in it's definition).
In the following example, the field `identifier` is used
In the following example, the field ``identifier`` is used
as the identifying field::
class MyUser(AbstractBaseUser):
@ -605,11 +605,11 @@ The following methods are available on any subclass of
:meth:`~django.contrib.auth.models.AbstractBaseUser.set_unusable_password()` has
been called for this user.
You should also define a custom manager for your User model. If your User
model defines `username` and `email` fields the same as Django's default User,
you can just install Django's
:class:`~django.contrib.auth.models.UserManager`; however, if your User model
defines different fields, you will need to define a custom manager that
You should also define a custom manager for your ``User`` model. If your
``User`` model defines ``username`` and ``email`` fields the same as Django's
default ``User``, you can just install Django's
:class:`~django.contrib.auth.models.UserManager`; however, if your ``User``
model defines different fields, you will need to define a custom manager that
extends :class:`~django.contrib.auth.models.BaseUserManager` providing two
additional methods:
@ -617,26 +617,28 @@ additional methods:
.. method:: models.CustomUserManager.create_user(*username_field*, password=None, \**other_fields)
The prototype of `create_user()` should accept the username field,
The prototype of ``create_user()`` should accept the username field,
plus all required fields as arguments. For example, if your user model
uses `email` as the username field, and has `date_of_birth` as a required
fields, then create_user should be defined as::
uses ``email`` as the username field, and has ``date_of_birth`` as a
required fields, then ``create_user`` should be defined as::
def create_user(self, email, date_of_birth, password=None):
# create user here
...
.. method:: models.CustomUserManager.create_superuser(*username_field*, password, \**other_fields)
The prototype of `create_superuser()` should accept the username field,
plus all required fields as arguments. For example, if your user model
uses `email` as the username field, and has `date_of_birth` as a required
fields, then create_superuser should be defined as::
The prototype of ``create_superuser()`` should accept the username
field, plus all required fields as arguments. For example, if your user
model uses ``email`` as the username field, and has ``date_of_birth``
as a required fields, then ``create_superuser`` should be defined as::
def create_superuser(self, email, date_of_birth, password):
# create superuser here
...
Unlike `create_user()`, `create_superuser()` *must* require the caller
to provider a password.
Unlike ``create_user()``, ``create_superuser()`` *must* require the
caller to provider a password.
:class:`~django.contrib.auth.models.BaseUserManager` provides the following
utility methods:
@ -705,7 +707,7 @@ auth views.
* :class:`~django.contrib.auth.forms.PasswordResetForm`
Assumes that the user model has an integer primary key, has a field named
`email` that can be used to identify the user, and a boolean field
``email`` that can be used to identify the user, and a boolean field
named `is_active` to prevent password resets for inactive users.
* :class:`~django.contrib.auth.forms.SetPasswordForm`
@ -721,8 +723,8 @@ auth views.
Works with any subclass of :class:`~django.contrib.auth.models.AbstractBaseUser`
Custom users and django.contrib.admin
-------------------------------------
Custom users and :mod:`django.contrib.admin`
--------------------------------------------
If you want your custom User model to also work with Admin, your User model must
define some additional attributes and methods. These methods allow the admin to
@ -732,21 +734,21 @@ control access of the User to admin content:
.. attribute:: is_staff
Returns True if the user is allowed to have access to the admin site.
Returns ``True`` if the user is allowed to have access to the admin site.
.. attribute:: is_active
Returns True if the user account is currently active.
Returns ``True`` if the user account is currently active.
.. method:: has_perm(perm, obj=None):
Returns True if the user has the named permission. If `obj` is
Returns ``True`` if the user has the named permission. If ``obj`` is
provided, the permission needs to be checked against a specific object
instance.
.. method:: has_module_perms(app_label):
Returns True if the user has permission to access models in
Returns ``True`` if the user has permission to access models in
the given app.
You will also need to register your custom User model with the admin. If
@ -911,7 +913,7 @@ A full example
Here is an example of an admin-compliant custom user app. This user model uses
an email address as the username, and has a required date of birth; it
provides no permission checking, beyond a simple `admin` flag on the user
provides no permission checking, beyond a simple ``admin`` flag on the user
account. This model would be compatible with all the built-in auth forms and
views, except for the User creation forms. This example illustrates how most of
the components work together, but is not intended to be copied directly into

6
docs/topics/auth/passwords.txt
View file

@ -102,9 +102,9 @@ algorithm.
There are several other implementations that allow bcrypt to be
used with Django. Django's bcrypt support is NOT directly
compatible with these. To upgrade, you will need to modify the
hashes in your database to be in the form `bcrypt$(raw bcrypt
output)`. For example:
`bcrypt$$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy`.
hashes in your database to be in the form ``bcrypt$(raw bcrypt
output)``. For example:
``bcrypt$$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy``.
Increasing the work factor
--------------------------

2
docs/topics/class-based-views/mixins.txt
View file

@ -13,7 +13,7 @@ but some of it you may want to use separately. For instance, you may
want to write a view that renders a template to make the HTTP
response, but you can't use
:class:`~django.views.generic.base.TemplateView`; perhaps you need to
render a template only on `POST`, with `GET` doing something else
render a template only on ``POST``, with ``GET`` doing something else
entirely. While you could use
:class:`~django.template.response.TemplateResponse` directly, this
will likely result in duplicate code.

36
docs/topics/db/aggregation.txt
View file

@ -43,7 +43,9 @@ used to track the inventory for a series of online bookstores:
Cheat sheet
===========
In a hurry? Here's how to do common aggregate queries, assuming the models above::
In a hurry? Here's how to do common aggregate queries, assuming the models above:
.. code-block:: python
# Total number of books.
>>> Book.objects.count()
@ -140,8 +142,10 @@ will be annotated with the specified values.
The syntax for these annotations is identical to that used for the
``aggregate()`` clause. Each argument to ``annotate()`` describes an
aggregate that is to be calculated. For example, to annotate Books with
the number of authors::
aggregate that is to be calculated. For example, to annotate books with
the number of authors:
.. code-block:: python
# Build an annotated queryset
>>> q = Book.objects.annotate(Count('authors'))
@ -190,8 +194,8 @@ you could use the annotation::
>>> Store.objects.annotate(min_price=Min('books__price'), max_price=Max('books__price'))
This tells Django to retrieve the Store model, join (through the
many-to-many relationship) with the Book model, and aggregate on the
This tells Django to retrieve the ``Store`` model, join (through the
many-to-many relationship) with the ``Book`` model, and aggregate on the
price field of the book model to produce a minimum and maximum value.
The same rules apply to the ``aggregate()`` clause. If you wanted to
@ -215,32 +219,32 @@ querying can include traversing "reverse" relationships. The lowercase name
of related models and double-underscores are used here too.
For example, we can ask for all publishers, annotated with their respective
total book stock counters (note how we use `'book'` to specify the
Publisher->Book reverse foreign key hop)::
total book stock counters (note how we use ``'book'`` to specify the
``Publisher`` -> ``Book`` reverse foreign key hop)::
>>> from django.db.models import Count, Min, Sum, Max, Avg
>>> Publisher.objects.annotate(Count('book'))
(Every Publisher in the resulting QuerySet will have an extra attribute called
``book__count``.)
(Every ``Publisher`` in the resulting ``QuerySet`` will have an extra attribute
called ``book__count``.)
We can also ask for the oldest book of any of those managed by every publisher::
>>> Publisher.objects.aggregate(oldest_pubdate=Min('book__pubdate'))
(The resulting dictionary will have a key called ``'oldest_pubdate'``. If no
such alias was specified, it would be the rather long ``'book__pubdate__min'``.)
such alias were specified, it would be the rather long ``'book__pubdate__min'``.)
This doesn't apply just to foreign keys. It also works with many-to-many
relations. For example, we can ask for every author, annotated with the total
number of pages considering all the books he/she has (co-)authored (note how we
use `'book'` to specify the Author->Book reverse many-to-many hop)::
use ``'book'`` to specify the ``Author`` -> ``Book`` reverse many-to-many hop)::
>>> Author.objects.annotate(total_pages=Sum('book__pages'))
(Every Author in the resulting QuerySet will have an extra attribute called
``total_pages``. If no such alias was specified, it would be the rather long
``book__pages__sum``.)
(Every ``Author`` in the resulting ``QuerySet`` will have an extra attribute
called ``total_pages``. If no such alias were specified, it would be the rather
long ``book__pages__sum``.)
Or ask for the average rating of all the books written by author(s) we have on
file::
@ -248,7 +252,7 @@ file::
>>> Author.objects.aggregate(average_rating=Avg('book__rating'))
(The resulting dictionary will have a key called ``'average__rating'``. If no
such alias was specified, it would be the rather long ``'book__rating__avg'``.)
such alias were specified, it would be the rather long ``'book__rating__avg'``.)
Aggregations and other QuerySet clauses
=======================================
@ -308,7 +312,7 @@ and the query::
>>> Publisher.objects.filter(book__rating__gt=3.0).annotate(num_books=Count('book'))
Both queries will return a list of Publishers that have at least one good
Both queries will return a list of publishers that have at least one good
book (i.e., a book with a rating exceeding 3.0). However, the annotation in
the first query will provide the total number of all books published by the
publisher; the second query will only include good books in the annotated

5
docs/topics/db/managers.txt
View file

@ -191,7 +191,7 @@ by the default manager.
If the normal plain manager class (:class:`django.db.models.Manager`) is not
appropriate for your circumstances, you can force Django to use the same class
as the default manager for your model by setting the `use_for_related_fields`
as the default manager for your model by setting the ``use_for_related_fields``
attribute on the manager class. This is documented fully below_.
.. _below: manager-types_
@ -369,7 +369,7 @@ it will use :class:`django.db.models.Manager`.
Writing correct Managers for use in automatic Manager instances
---------------------------------------------------------------
As already suggested by the `django.contrib.gis` example, above, the
As already suggested by the :mod:`django.contrib.gis` example, above, the
``use_for_related_fields`` feature is primarily for managers that need to
return a custom ``QuerySet`` subclass. In providing this functionality in your
manager, there are a couple of things to remember.
@ -413,4 +413,3 @@ used in a model, since the attribute's value is processed when the model class
is created and not subsequently reread. Set the attribute on the manager class
when it is first defined, as in the initial example of this section and
everything will work smoothly.

2
docs/topics/db/optimization.txt
View file

@ -157,7 +157,7 @@ Doing the following is potentially quite slow:
>>> entry = Entry.objects.get(headline__startswith="News")
First of all, `headline` is not indexed, which will make the underlying
First of all, ``headline`` is not indexed, which will make the underlying
database fetch slower.
Second, the lookup doesn't guarantee that only one object will be returned.

4
docs/topics/db/queries.txt
View file

@ -297,8 +297,8 @@ the query - in this case, it will be a
:class:`~django.db.models.query.QuerySet` containing a single element.
If you know there is only one object that matches your query, you can use the
:meth:`~django.db.models.query.QuerySet.get` method on a `Manager` which
returns the object directly::
:meth:`~django.db.models.query.QuerySet.get` method on a
:class:`~django.db.models.Manager` which returns the object directly::
>>> one_entry = Entry.objects.get(pk=1)

5
docs/topics/http/shortcuts.txt
View file

@ -169,8 +169,9 @@ This example is equivalent to::
* A model: the model's `get_absolute_url()` function will be called.
* A view name, possibly with arguments: `urlresolvers.reverse()` will
be used to reverse-resolve the name.
* A view name, possibly with arguments: :func:`urlresolvers.reverse
<django.core.urlresolvers.reverse>` will be used to reverse-resolve the
name.
* A URL, which will be used as-is for the redirect location.

12
docs/topics/logging.txt
View file

@ -308,7 +308,7 @@ This logging configuration does the following things:
* ``simple``, that just outputs the log level name (e.g.,
``DEBUG``) and the log message.
The `format` string is a normal Python formatting string
The ``format`` string is a normal Python formatting string
describing the details that are to be output on each logging
line. The full list of detail that can be output can be
found in the `formatter documentation`_.
@ -330,7 +330,7 @@ This logging configuration does the following things:
higher) message to ``/dev/null``.
* ``console``, a StreamHandler, which will print any ``DEBUG``
(or higher) message to stderr. This handler uses the `simple` output
(or higher) message to stderr. This handler uses the ``simple`` output
format.
* ``mail_admins``, an AdminEmailHandler, which will email any
@ -544,7 +544,7 @@ logging module.
This filter is used as follows in the default :setting:`LOGGING`
configuration to ensure that the :class:`AdminEmailHandler` only sends error
emails to admins when :setting:`DEBUG` is `False`::
emails to admins when :setting:`DEBUG` is ``False``::
'filters': {
'require_debug_false': {
@ -564,7 +564,7 @@ logging module.
.. versionadded:: 1.5
This filter is similar to :class:`RequireDebugFalse`, except that records are
passed only when :setting:`DEBUG` is `True`.
passed only when :setting:`DEBUG` is ``True``.
.. _default-logging-configuration:
@ -576,8 +576,8 @@ with ``ERROR`` or ``CRITICAL`` level are sent to :class:`AdminEmailHandler`, as
long as the :setting:`DEBUG` setting is set to ``False``.
All messages reaching the ``django`` catch-all logger when :setting:`DEBUG` is
`True` are sent to the console. They are simply discarded (sent to
``NullHandler``) when :setting:`DEBUG` is `False`.
``True`` are sent to the console. They are simply discarded (sent to
``NullHandler``) when :setting:`DEBUG` is ``False``.
.. versionchanged:: 1.5

24
docs/topics/serialization.txt
View file

@ -90,11 +90,11 @@ If you only serialize the Restaurant model::
data = serializers.serialize('xml', Restaurant.objects.all())
the fields on the serialized output will only contain the `serves_hot_dogs`
attribute. The `name` attribute of the base class will be ignored.
the fields on the serialized output will only contain the ``serves_hot_dogs``
attribute. The ``name`` attribute of the base class will be ignored.
In order to fully serialize your Restaurant instances, you will need to
serialize the Place models as well::
In order to fully serialize your ``Restaurant`` instances, you will need to
serialize the ``Place`` models as well::
all_objects = list(Restaurant.objects.all()) + list(Place.objects.all())
data = serializers.serialize('xml', all_objects)
@ -176,7 +176,7 @@ XML
~~~
The basic XML serialization format is quite simple::
<?xml version="1.0" encoding="utf-8"?>
<django-objects version="1.0">
<object pk="123" model="sessions.session">
@ -196,7 +196,7 @@ fields "type" and "name". The text content of the element represents the value
that should be stored.
Foreign keys and other relational fields are treated a little bit differently::
<object pk="27" model="auth.permission">
<!-- ... -->
<field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>
@ -208,7 +208,7 @@ a foreign key to the contenttypes.ContentType instance with the PK 9.
ManyToMany-relations are exported for the model that binds them. For instance,
the auth.User model has such a relation to the auth.Permission model::
<object pk="1" model="auth.user">
<!-- ... -->
<field to="auth.permission" name="user_permissions" rel="ManyToManyRel">
@ -224,7 +224,7 @@ JSON
When staying with the same example data as before it would be serialized as
JSON in the following way::
[
{
"pk": "4b678b301dfd8a4e0dad910de3ae245b",
@ -242,7 +242,7 @@ with three properties: "pk", "model" and "fields". "fields" is again an object
containing each field's name and value as property and property-value
respectively.
Foreign keys just have the PK of the linked object as property value.
Foreign keys just have the PK of the linked object as property value.
ManyToMany-relations are serialized for the model that defines them and are
represented as a list of PKs.
@ -273,7 +273,7 @@ YAML
YAML serialization looks quite similar to JSON. The object list is serialized
as a sequence mappings with the keys "pk", "model" and "fields". Each field is
again a mapping with the key being name of the field and the value the value::
- fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'}
model: sessions.session
pk: 4b678b301dfd8a4e0dad910de3ae245b
@ -439,7 +439,7 @@ When ``use_natural_keys=True`` is specified, Django will use the
type that defines the method.
If you are using :djadmin:`dumpdata` to generate serialized data, you
use the `--natural` command line flag to generate natural keys.
use the :djadminopt:`--natural` command line flag to generate natural keys.
.. note::
@ -458,7 +458,7 @@ Dependencies during serialization
Since natural keys rely on database lookups to resolve references, it
is important that the data exists before it is referenced. You can't make
a `forward reference` with natural keys -- the data you're referencing
a "forward reference" with natural keys -- the data you're referencing
must exist before you include a natural key reference to that data.
To accommodate this limitation, calls to :djadmin:`dumpdata` that use

10
docs/topics/testing/overview.txt
View file

@ -975,8 +975,8 @@ This class provides some additional capabilities that can be useful for testing
Web sites.
Converting a normal :class:`unittest.TestCase` to a Django :class:`TestCase` is
easy: Just change the base class of your test from `'unittest.TestCase'` to
`'django.test.TestCase'`. All of the standard Python unit test functionality
easy: Just change the base class of your test from ``'unittest.TestCase'`` to
``'django.test.TestCase'``. All of the standard Python unit test functionality
will continue to be available, but it will be augmented with some useful
additions, including:
@ -1010,7 +1010,7 @@ This allows the use of automated test clients other than the
client, to execute a series of functional tests inside a browser and simulate a
real user's actions.
By default the live server's address is `'localhost:8081'` and the full URL
By default the live server's address is ``'localhost:8081'`` and the full URL
can be accessed during the tests with ``self.live_server_url``. If you'd like
to change the default address (in the case, for example, where the 8081 port is
already taken) then you may pass a different one to the :djadmin:`test` command
@ -1117,7 +1117,7 @@ out the `full reference`_ for more details.
(for example, just after clicking a link or submitting a form), you might
need to check that a response is received by Selenium and that the next
page is loaded before proceeding with further test execution.
Do this, for example, by making Selenium wait until the `<body>` HTML tag
Do this, for example, by making Selenium wait until the ``<body>`` HTML tag
is found in the response (requires Selenium > 2.13):
.. code-block:: python
@ -1134,7 +1134,7 @@ out the `full reference`_ for more details.
The tricky thing here is that there's really no such thing as a "page load,"
especially in modern Web apps that generate HTML dynamically after the
server generates the initial document. So, simply checking for the presence
of `<body>` in the response might not necessarily be appropriate for all
of ``<body>`` in the response might not necessarily be appropriate for all
use cases. Please refer to the `Selenium FAQ`_ and
`Selenium documentation`_ for more information.