p15693087
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Edited some docs and docstrings until [17685] 

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17686 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2012-03-12 20:05:48 +00:00
parent 20c69c5e51
commit dd246a62c7
8 changed files with 60 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
django/contrib/auth/management/commands/changepassword.py
View File

@ -9,8 +9,7 @@ from django.db import DEFAULT_DB_ALIAS
class Command(BaseCommand):
option_list = BaseCommand.option_list + (
make_option('--database', action='store', dest='database',
default=DEFAULT_DB_ALIAS, help='Nominates a database to query for the user. '
'Defaults to the "default" database.'),
default=DEFAULT_DB_ALIAS, help='Specifies the database to use. Default is "default".'),
)
help = "Change a user's password for django.contrib.auth."

3
django/contrib/auth/management/commands/createsuperuser.py
View File

@ -39,8 +39,7 @@ class Command(BaseCommand):
'superusers created with --noinput will not be able to log '
'in until they\'re given a valid password.')),
make_option('--database', action='store', dest='database',
default=DEFAULT_DB_ALIAS, help='Nominates a database to save the user to. '
'Defaults to the "default" database.'),
default=DEFAULT_DB_ALIAS, help='Specifies the database to use. Default is "default".'),
)
help = 'Used to create a superuser.'

8
docs/ref/django-admin.txt
View File

@ -1199,8 +1199,8 @@ change the password whose username matches the current user.
.. versionadded:: 1.4
The ``--database`` option can be used to specify the database to query for the
user. If it is not supplied the ``default`` database will be used.
Use the ``--database`` option to specify the database to query for the user. If
it's not supplied, Django will use the ``default`` database.
Example usage::
@ -1234,8 +1234,8 @@ it when running interactively.
.. versionadded:: 1.4
The ``--database`` option can be used to specify the database into which the
superuser object will be saved.
Use the ``--database`` option to specify the database into which the superuser
object will be saved.
``django.contrib.gis``
----------------------

2
docs/ref/models/querysets.txt
View File

@ -1377,7 +1377,7 @@ This has a number of caveats though:
maximum is defined by the SQLITE_MAX_VARIABLE_NUMBER_ compilation option,
which defaults to 999. For instance, if your model has 8 fields (including
the primary key), you cannot create more than 999 // 8 = 124 instances at
a time. If you exceed this limit, you will get an exception::
a time. If you exceed this limit, you'll get an exception::
django.db.utils.DatabaseError: too many SQL variables

6
docs/releases/1.4.txt
View File

@ -617,9 +617,9 @@ Django 1.4 also includes several smaller improvements worth noting:
* A new :class:`django.test.SimpleTestCase` subclass of
:class:`unittest.TestCase`
that is comparatively lighter than :class:`django.test.TestCase` and
company. It can be useful in testing scenarios where e.g. no database
interaction is needed. See :ref:`testcase_hierarchy_diagram`.
that's lighter than :class:`django.test.TestCase` and company. It can be
useful in tests that don't need to hit a database. See
:ref:`testcase_hierarchy_diagram`.
Backwards incompatible changes in 1.4
=====================================

81
docs/topics/i18n/timezones.txt
View File

@ -12,22 +12,22 @@ Overview
========
When support for time zones is enabled, Django stores date and time
information in UTC in the database, uses time zone-aware datetime objects
information in UTC in the database, uses time-zone-aware datetime objects
internally, and translates them to the end user's time zone in templates and
forms.
This is handy if your users live in more than one time zone and you want to
display date and time information according to each user's wall clock. Even if
your website is available in only one time zone, it's still a good practice to
store data in UTC in your database. Here is why.
display date and time information according to each user's wall clock.
Many countries have a system of daylight saving time (DST), where clocks are
moved forwards in spring and backwards in autumn. If you're working in local
time, you're likely to encounter errors twice a year, when the transitions
happen. The pytz_ documentation discusses `these issues`_ in greater detail.
It probably doesn't matter for your blog, but it's more annoying if you
over-bill or under-bill your customers by one hour, twice a year, every year.
The solution to this problem is to use UTC in the code and local time only when
Even if your Web site is available in only one time zone, it's still good
practice to store data in UTC in your database. One main reason is Daylight
Saving Time (DST). Many countries have a system of DST, where clocks are moved
forward in spring and backward in autumn. If you're working in local time,
you're likely to encounter errors twice a year, when the transitions happen.
(The pytz_ documentation discusses `these issues`_ in greater detail.) This
probably doesn't matter for your blog, but it's a problem if you over-bill or
under-bill your customers by one hour, twice a year, every year. The solution
to this problem is to use UTC in the code and use local time only when
interacting with end users.
Time zone support is disabled by default. To enable it, set :setting:`USE_TZ =
@ -47,10 +47,10 @@ but not mandatory. It's as simple as:
.. note::
There is also an independent but related :setting:`USE_L10N` setting that
controls if Django should activate format localization. See
controls whether Django should activate format localization. See
:doc:`/topics/i18n/formatting` for more details.
If you're stumbling on a particular problem, start with the :ref:`time zone
If you're wrestling with a particular problem, start with the :ref:`time zone
FAQ <time-zones-faq>`.
Concepts
@ -62,11 +62,11 @@ Naive and aware datetime objects
Python's :class:`datetime.datetime` objects have a ``tzinfo`` attribute that
can be used to store time zone information, represented as an instance of a
subclass of :class:`datetime.tzinfo`. When this attribute is set and describes
an offset, a datetime object is **aware**; otherwise, it's **naive**.
an offset, a datetime object is **aware**. Otherwise, it's **naive**.
You can use :func:`~django.utils.timezone.is_aware` and
:func:`~django.utils.timezone.is_naive` to determine if datetimes are aware or
naive.
:func:`~django.utils.timezone.is_naive` to determine whether datetimes are
aware or naive.
When time zone support is disabled, Django uses naive datetime objects in local
time. This is simple and sufficient for many use cases. In this mode, to obtain
@ -76,7 +76,7 @@ the current time, you would write::
now = datetime.datetime.now()
When time zone support is enabled, Django uses time zone aware datetime
When time zone support is enabled, Django uses time-zone-aware datetime
objects. If your code creates datetime objects, they should be aware too. In
this mode, the example above becomes::
@ -173,7 +173,7 @@ time zone automatically. Instead, Django provides :ref:`time zone selection
functions <time-zone-selection-functions>`. Use them to build the time zone
selection logic that makes sense for you.
Most websites who care about time zones just ask users in which time zone they
Most Web sites that care about time zones just ask users in which time zone they
live and store this information in the user's profile. For anonymous users,
they use the time zone of their primary audience or UTC. pytz_ provides
helpers_, like a list of time zones per country, that you can use to pre-select
@ -481,9 +481,9 @@ Setup
Yes. When time zone support is enabled, Django uses a more accurate model
of local time. This shields you from subtle and unreproducible bugs around
daylight saving time (DST) transitions. Remember that your website runs 24/7!
Daylight Saving Time (DST) transitions.
In this regard, time zones is comparable to ``unicode`` in Python. At first
In this regard, time zones are comparable to ``unicode`` in Python. At first
it's hard. You get encoding and decoding errors. Then you learn the rules.
And some problems disappear -- you never get mangled output again when your
application receives non-ASCII input.
@ -501,14 +501,14 @@ Setup
For these reasons, time zone support is enabled by default in new projects,
and you should keep it unless you have a very good reason not to.
2. **I've enabled time zone support, am I safe?**
2. **I've enabled time zone support. Am I safe?**
Maybe. You're better protected from DST-related bugs, but you can still
shoot yourself in the foot by carelessly turning naive datetimes into aware
datetimes, and vice-versa.
If your application connects to other systems, for instance if it queries
a webservice, make sure datetimes are properly specified. To transmit
If your application connects to other systems -- for instance, if it queries
a Web service -- make sure datetimes are properly specified. To transmit
datetimes safely, their representation should include the UTC offset, or
their values should be in UTC (or both!).
@ -549,8 +549,7 @@ Troubleshooting
1. **My application crashes with** ``TypeError: can't compare offset-naive``
``and offset-aware datetimes`` **-- what's wrong?**
First, don't panic. Then, let's reproduce this error, simply by comparing a
naive and an aware datetime::
Let's reproduce this error by comparing a naive and an aware datetime::
>>> import datetime
>>> from django.utils import timezone
@ -561,10 +560,11 @@ Troubleshooting
...
TypeError: can't compare offset-naive and offset-aware datetimes
If you encounter this error, most likely, your code is comparing:
If you encounter this error, most likely your code is comparing these two
things:
- a datetime provided by Django, for instance a value read from a form or
a model field: since you enabled time zone support, it is aware;
- a datetime provided by Django -- for instance, a value read from a form or
a model field. Since you enabled time zone support, it's aware.
- a datetime generated by your code, which is naive (or you wouldn't be
reading this).
@ -575,12 +575,12 @@ Troubleshooting
independently of the value of :setting:`USE_TZ`, you may find
:func:`django.utils.timezone.now` useful. This function returns the current
date and time as a naive datetime when ``USE_TZ = False`` and as an aware
datetime when ``USE_TZ = True``. You can add or substract
datetime when ``USE_TZ = True``. You can add or subtract
:class:`datetime.timedelta` as needed.
2. **I see lots of** ``RuntimeWarning: DateTimeField received a naive
datetime`` ``(YYYY-MM-DD HH:MM:SS)`` ``while time zone support is active``
**-- is it bad?**
**-- is that bad?**
When time zone support is enabled, the database layer expects to receive
only aware datetimes from your code. This warning occurs when it receives a
@ -617,15 +617,14 @@ Troubleshooting
datetime.datetime(2012, 3, 2, 19, 30, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>)
As this example shows, the same datetime has a different date, depending on
the time zone in which it is representend. But the real problem is more
the time zone in which it is represented. But the real problem is more
fundamental.
A datetime represents a **point in time**. It's absolute: it doesn't depend
on anything (barring relativistic effects). On the contrary, a date is a
**calendaring concept**. It's a period of time whose bounds depend on the
time zone in which the date is considered. As you can see, these two
concepts are fundamentally different and converting a datetime to a date
isn't a deterministic operation.
on anything. On the contrary, a date is a **calendaring concept**. It's a
period of time whose bounds depend on the time zone in which the date is
considered. As you can see, these two concepts are fundamentally different,
and converting a datetime to a date isn't a deterministic operation.
What does this mean in practice?
@ -633,7 +632,7 @@ Troubleshooting
:class:`~datetime.date`. For instance, you can use the :tfilter:`date`
template filter to only show the date part of a datetime. This filter will
convert the datetime into the current time zone before formatting it,
ensuring the results appear correct for the user.
ensuring the results appear correctly.
If you really need to do the conversion yourself, you must ensure the
datetime is converted to the appropriate time zone first. Usually, this
@ -654,7 +653,7 @@ Troubleshooting
Usage
-----
1. **I have this string** ``"2012-02-21 10:28:45"`` **and I know it's in the**
1. **I have a string** ``"2012-02-21 10:28:45"`` **and I know it's in the**
``"Europe/Helsinki"`` **time zone. How do I turn that into an aware
datetime?**
@ -668,7 +667,7 @@ Usage
Note that ``localize`` is a pytz extension to the :class:`~datetime.tzinfo`
API. Also, you may want to catch :exc:`~pytz.InvalidTimeError`. The
documentation of pytz contains `more examples`_; you should review it
documentation of pytz contains `more examples`_. You should review it
before attempting to manipulate aware datetimes.
2. **How can I obtain the current time in the local time zone?**
@ -685,8 +684,8 @@ Usage
the datetime in UTC returned by :func:`django.utils.timezone.now` will be
sufficient.
For the sake of completeness, if you really wanted the current time in the
local time zone, here's how you would obtain it::
For the sake of completeness, though, if you really wanted the current time
in the local time zone, here's how you would obtain it::
>>> import datetime
>>> from django.utils import timezone

13
docs/topics/install.txt
View File

@ -210,17 +210,19 @@ Installing an official release with ``pip``
This is the recommended way to install Django.
1. Install pip_. The easiest is to use the `standalone pip installer`_. If your
distribution has ``pip`` already installed, make sure it isn't too outdated.
distribution already has ``pip`` installed, you might need to update it if
it's outdated. (If it's outdated, you'll know because installation won't
work.)
2. (optional) Take a look at virtualenv_ and virtualenvwrapper_. These tools
provide isolated Python environments, which are more practical than
installing packages system-wide. They also allow installing packages
installing packages systemwide. They also allow installing packages
without administrator privileges. It's up to you to decide if you want to
learn and use them.
3. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
command ``sudo pip install Django`` at the shell prompt. If you're using
Windows, start up a command shell with administrator privileges and run
Windows, start a command shell with administrator privileges and run
the command ``pip install Django``. This will install Django in your Python
installation's ``site-packages`` directory.
@ -228,7 +230,6 @@ This is the recommended way to install Django.
privileges, and this will install Django in the virtualenv's
``site-packages`` directory.
.. _pip: http://www.pip-installer.org/
.. _virtualenv: http://www.virtualenv.org/
.. _virtualenvwrapper: http://www.doughellmann.com/docs/virtualenvwrapper/
@ -248,7 +249,7 @@ Installing an official release manually
4. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
command ``sudo python setup.py install`` at the shell prompt. If you're
using Windows, start up a command shell with administrator privileges and
using Windows, start a command shell with administrator privileges and
run the command ``python setup.py install``. This will install Django in
your Python installation's ``site-packages`` directory.
@ -343,7 +344,7 @@ latest bug fixes and improvements, follow these instructions:
.. warning::
You mustn't run ``sudo python setup.py install``, because you've already
Don't run ``sudo python setup.py install``, because you've already
carried out the equivalent actions in steps 3 and 4. Furthermore, this is
known to cause problems when updating to a more recent version of Django.

6
tests/regressiontests/delete_regress/tests.py
View File

@ -152,7 +152,7 @@ class LargeDeleteTests(TestCase):
class ProxyDeleteTest(TestCase):
"""
Tests on_delete behaviour for proxy models. Deleting the *proxy*
Tests on_delete behavior for proxy models. Deleting the *proxy*
instance bubbles through to its non-proxy and *all* referring objects
are deleted.
@ -188,7 +188,7 @@ class ProxyDeleteTest(TestCase):
class ProxyOfProxyDeleteTest(ProxyDeleteTest):
"""
Tests on_delete behaviour for proxy-of-proxy models. Deleting the *proxy*
Tests on_delete behavior for proxy-of-proxy models. Deleting the *proxy*
instance should bubble through to its proxy and non-proxy variants.
Deleting *all* referring objects.
@ -224,7 +224,7 @@ class ProxyOfProxyDeleteTest(ProxyDeleteTest):
class ProxyParentDeleteTest(ProxyDeleteTest):
"""
Tests on_delete cascade behaviour for proxy models. Deleting the
Tests on_delete cascade behavior for proxy models. Deleting the
*non-proxy* instance of a model should delete objects referencing the
proxy.