Author: adrian
Date: 2012-03-12 13:05:48 -0700 (Mon, 12 Mar 2012)
New Revision: 17686
Modified:
django/trunk/django/contrib/auth/management/commands/changepassword.py
django/trunk/django/contrib/auth/management/commands/createsuperuser.py
django/trunk/docs/ref/django-admin.txt
django/trunk/docs/ref/models/querysets.txt
django/trunk/docs/releases/1.4.txt
django/trunk/docs/topics/i18n/timezones.txt
django/trunk/docs/topics/install.txt
django/trunk/tests/regressiontests/delete_regress/tests.py
Log:
Edited some docs and docstrings until [17685]
Modified: django/trunk/django/contrib/auth/management/commands/changepassword.py
===================================================================
--- django/trunk/django/contrib/auth/management/commands/changepassword.py
2012-03-12 19:41:31 UTC (rev 17685)
+++ django/trunk/django/contrib/auth/management/commands/changepassword.py
2012-03-12 20:05:48 UTC (rev 17686)
@@ -9,8 +9,7 @@
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."
Modified:
django/trunk/django/contrib/auth/management/commands/createsuperuser.py
===================================================================
--- django/trunk/django/contrib/auth/management/commands/createsuperuser.py
2012-03-12 19:41:31 UTC (rev 17685)
+++ django/trunk/django/contrib/auth/management/commands/createsuperuser.py
2012-03-12 20:05:48 UTC (rev 17686)
@@ -39,8 +39,7 @@
'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.'
Modified: django/trunk/docs/ref/django-admin.txt
===================================================================
--- django/trunk/docs/ref/django-admin.txt 2012-03-12 19:41:31 UTC (rev
17685)
+++ django/trunk/docs/ref/django-admin.txt 2012-03-12 20:05:48 UTC (rev
17686)
@@ -1199,8 +1199,8 @@
.. 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 @@
.. 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``
----------------------
Modified: django/trunk/docs/ref/models/querysets.txt
===================================================================
--- django/trunk/docs/ref/models/querysets.txt 2012-03-12 19:41:31 UTC (rev
17685)
+++ django/trunk/docs/ref/models/querysets.txt 2012-03-12 20:05:48 UTC (rev
17686)
@@ -1377,7 +1377,7 @@
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
Modified: django/trunk/docs/releases/1.4.txt
===================================================================
--- django/trunk/docs/releases/1.4.txt 2012-03-12 19:41:31 UTC (rev 17685)
+++ django/trunk/docs/releases/1.4.txt 2012-03-12 20:05:48 UTC (rev 17686)
@@ -617,9 +617,9 @@
* 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
=====================================
Modified: django/trunk/docs/topics/i18n/timezones.txt
===================================================================
--- django/trunk/docs/topics/i18n/timezones.txt 2012-03-12 19:41:31 UTC (rev
17685)
+++ django/trunk/docs/topics/i18n/timezones.txt 2012-03-12 20:05:48 UTC (rev
17686)
@@ -12,22 +12,22 @@
========
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 @@
.. 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
...
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 @@
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 @@
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 @@
: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 @@
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 @@
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 @@
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
Modified: django/trunk/docs/topics/install.txt
===================================================================
--- django/trunk/docs/topics/install.txt 2012-03-12 19:41:31 UTC (rev
17685)
+++ django/trunk/docs/topics/install.txt 2012-03-12 20:05:48 UTC (rev
17686)
@@ -210,17 +210,19 @@
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 @@
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 @@
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 @@
.. 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.
Modified: django/trunk/tests/regressiontests/delete_regress/tests.py
===================================================================
--- django/trunk/tests/regressiontests/delete_regress/tests.py 2012-03-12
19:41:31 UTC (rev 17685)
+++ django/trunk/tests/regressiontests/delete_regress/tests.py 2012-03-12
20:05:48 UTC (rev 17686)
@@ -152,7 +152,7 @@
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 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 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.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
