diff --git a/django/contrib/auth/management/commands/changepassword.py b/django/contrib/auth/management/commands/changepassword.py index e2815ed117..d125dfe5b6 100644 --- a/django/contrib/auth/management/commands/changepassword.py +++ b/django/contrib/auth/management/commands/changepassword.py @@ -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." diff --git a/django/contrib/auth/management/commands/createsuperuser.py b/django/contrib/auth/management/commands/createsuperuser.py index 89a76b3279..ad659773f8 100644 --- a/django/contrib/auth/management/commands/createsuperuser.py +++ b/django/contrib/auth/management/commands/createsuperuser.py @@ -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.' diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 3fbf3cac59..5ea72803fb 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -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`` ---------------------- diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 2b24fdd05c..e25bea0e69 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -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 diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index be3434d797..585e7ff591 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -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 ===================================== diff --git a/docs/topics/i18n/timezones.txt b/docs/topics/i18n/timezones.txt index e30de2997b..e5453ef960 100644 --- a/docs/topics/i18n/timezones.txt +++ b/docs/topics/i18n/timezones.txt @@ -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 `. 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 `. 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=) 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 diff --git a/docs/topics/install.txt b/docs/topics/install.txt index ab4a86084e..947ff0580b 100644 --- a/docs/topics/install.txt +++ b/docs/topics/install.txt @@ -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. diff --git a/tests/regressiontests/delete_regress/tests.py b/tests/regressiontests/delete_regress/tests.py index 8ef00e92a5..e7f4619dcf 100644 --- a/tests/regressiontests/delete_regress/tests.py +++ b/tests/regressiontests/delete_regress/tests.py @@ -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.