Ticket #16586: 16586.2.patch
| File 16586.2.patch, 51.8 KB (added by , 13 years ago) |
|---|
-
docs/glossary.txt
43 43 44 44 property 45 45 Also known as "managed attributes", and a feature of Python since 46 version 2.2. From `the property documentation`__: 46 version 2.2. This is a neat way to implement attributes whose usage 47 resembles attribute access, but whose implementation uses method calls. 47 48 48 Properties are a neat way to implement attributes whose usage 49 resembles attribute access, but whose implementation uses method 50 calls. [...] You 51 could only do this by overriding ``__getattr__`` and 52 ``__setattr__``; but overriding ``__setattr__`` slows down all 53 attribute assignments considerably, and overriding ``__getattr__`` 54 is always a bit tricky to get right. Properties let you do this 55 painlessly, without having to override ``__getattr__`` or 56 ``__setattr__``. 49 See :func:`property`. 57 50 58 __ http://www.python.org/download/releases/2.2/descrintro/#property59 60 51 queryset 61 52 An object representing some set of rows to be fetched from the database. 62 53 -
docs/intro/tutorial03.txt
122 122 ``http://www.example.com/myapp/?page=3``, the URLconf will look for ``myapp/``. 123 123 124 124 If you need help with regular expressions, see `Wikipedia's entry`_ and the 125 `Python documentation`_. Also, the O'Reilly book "Mastering Regular Expressions" 126 by Jeffrey Friedl is fantastic.125 :mod:`Python documentation<re>`. Also, the O'Reilly book "Mastering Regular 126 Expressions" by Jeffrey Friedl is fantastic. 127 127 128 128 Finally, a performance note: these regular expressions are compiled the first 129 129 time the URLconf module is loaded. They're super fast. 130 130 131 131 .. _Wikipedia's entry: http://en.wikipedia.org/wiki/Regular_expression 132 .. _Python documentation: http://docs.python.org/library/re.html133 132 134 133 Write your first view 135 134 ===================== -
docs/misc/design-philosophies.txt
73 73 Explicit is better than implicit 74 74 -------------------------------- 75 75 76 This , a `core Python principle`_, means Django shouldn't do too much "magic."77 Magic shouldn't happen unless there's a really good reason for it. Magic is 78 worth using only if it creates a huge convenience unattainable in other ways, 79 and it isn't implemented in a way that confuses developers who are trying to 80 learn how to use the feature.76 This is a core Python principle listed in :pep:`20`, and it means Django 77 shouldn't do too much "magic." Magic shouldn't happen unless there's a really 78 good reason for it. Magic is worth using only if it creates a huge convenience 79 unattainable in other ways, and it isn't implemented in a way that confuses 80 developers who are trying to learn how to use the feature. 81 81 82 .. _`core Python principle`: http://www.python.org/dev/peps/pep-0020/83 84 82 .. _consistency: 85 83 86 84 Consistency -
docs/internals/contributing/writing-documentation.txt
43 43 Then, building the HTML is easy; just ``make html`` (or ``make.bat html`` on 44 44 Windows) from the ``docs`` directory. 45 45 46 To get started contributing, you'll want to read the `reStructuredText 47 Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__ 48 that's used to manage metadata, indexing, and cross-references.46 To get started contributing, you'll want to read the `reStructuredText Primer 47 <rst-primer>`. After that, you'll want to read about the `Sphinx-specific markup 48 <sphinxmarkup>` that's used to manage metadata, indexing, and cross-references. 49 49 50 __ http://sphinx.pocoo.org/rest.html51 __ http://sphinx.pocoo.org/markup/52 53 50 Commonly used terms 54 51 ------------------- 55 52 … … 113 110 greatly helps readers. There's basically no limit to the amount of 114 111 useful markup you can add. 115 112 113 * Use :mod:`intersphinx links <sphinx.ext.intersphinx>` to reference 114 Python's documentation. 115 116 116 Django-specific markup 117 117 ---------------------- 118 118 … … 220 220 You can find both in the :doc:`settings reference document 221 221 </ref/settings>`. 222 222 223 We use the Sphinx doc_ cross reference element when we want to linkto224 another document as a whole and the ref_ element when we want to link to225 an arbitrary location in a document.223 We use the Sphinx :rst:role:`doc` cross reference element when we want to 224 link to another document as a whole and the :rst:role:`ref` element when 225 we want to link to an arbitrary location in a document. 226 226 227 .. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc228 .. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref229 230 227 * Next, notice how the settings are annotated: 231 228 232 229 .. code-block:: rst -
docs/internals/contributing/writing-code/coding-style.txt
10 10 * Unless otherwise specified, follow :pep:`8`. 11 11 12 12 You could use a tool like `pep8`_ to check for some problems in this 13 area, but remember that PEP 8is only a guide, so respect the style of13 area, but remember that :pep:`8` is only a guide, so respect the style of 14 14 the surrounding code as a primary goal. 15 15 16 16 * Use four spaces for indentation. -
docs/internals/contributing/writing-code/branch-policy.txt
146 146 location of the branch's ``django`` package. If you want to switch back, just 147 147 change the symlink to point to the old code. 148 148 149 A third option is to use a `path file`_ (``<something>.pth``). First, make sure150 there are no files, directories or symlinks named ``django`` in your149 A third option is to use a :mod:`path file<site>` (``<something>.pth``). First, 150 make sure there are no files, directories or symlinks named ``django`` in your 151 151 ``site-packages`` directory. Then create a text file named ``django.pth`` and 152 152 save it to your ``site-packages`` directory. That file should contain a path to 153 153 your copy of Django on a single line and optional comments. Here is an example … … 168 168 # On windows a path may look like this: 169 169 # C:/path/to/<branch> 170 170 171 .. _path file: http://docs.python.org/library/site.html172 171 .. _django-developers: http://groups.google.com/group/django-developers -
docs/howto/deployment/modwsgi.txt
9 9 .. _mod_wsgi: http://code.google.com/p/modwsgi/ 10 10 11 11 mod_wsgi is an Apache module which can be used to host any Python application 12 which supports the `Python WSGI interface`_, including Django. Django will work13 with any version of Apache which supports mod_wsgi.12 which supports the Python WSGI interface described in :pep:`3333`, including 13 Django. Django will work with any version of Apache which supports mod_wsgi. 14 14 15 .. _python wsgi interface: http://www.python.org/dev/peps/pep-0333/16 17 15 The `official mod_wsgi documentation`_ is fantastic; it's your source for all 18 16 the details about how to use mod_wsgi. You'll probably want to start with the 19 17 `installation and configuration documentation`_. -
docs/howto/outputting-csv.txt
3 3 ========================== 4 4 5 5 This document explains how to output CSV (Comma Separated Values) dynamically 6 using Django views. To do this, you can either use the `Python CSV library`_ or7 theDjango template system.6 using Django views. To do this, you can either use the Python CSV library or the 7 Django template system. 8 8 9 .. _Python CSV library: http://docs.python.org/library/csv.html10 11 9 Using the Python CSV library 12 10 ============================ 13 11 14 Python comes with a CSV library, ``csv``. The key to using it with Django is15 that the ``csv`` module's CSV-creation capability acts on file-like objects, and16 Django's :class:`~django.http.HttpResponse` objects are file-like objects.12 Python comes with a CSV library, :mod:`csv`. The key to using it with Django is 13 that the :mod:`csv` module's CSV-creation capability acts on file-like objects, 14 and Django's :class:`~django.http.HttpResponse` objects are file-like objects. 17 15 18 16 Here's an example:: 19 17 … … 72 70 * Use the `python-unicodecsv module`_, which aims to be a drop-in 73 71 replacement for ``csv`` that gracefully handles Unicode. 74 72 75 For more information, see the Python `CSV File Reading and Writing`_73 For more information, see the Python :mod:`CSV File Reading and Writing<csv>` 76 74 documentation. 77 75 78 76 .. _`csv module's examples section`: http://docs.python.org/library/csv.html#examples 79 77 .. _`python-unicodecsv module`: https://github.com/jdunck/python-unicodecsv 80 .. _`CSV File Reading and Writing`: http://docs.python.org/library/csv.html81 78 82 79 Using the template system 83 80 ========================= -
docs/howto/custom-template-tags.txt
335 335 336 336 For example, let's write a template tag, ``{% current_time %}``, that displays 337 337 the current date/time, formatted according to a parameter given in the tag, in 338 `strftime syntax`_. It's a good idea to decide the tag syntax before anything 339 else. In our case, let's say the tag should be used like this: 338 :func:`strftime syntax<time.strftime>`. It's a good idea to decide the tag 339 syntax before anything else. In our case, let's say the tag should be used like 340 this: 340 341 341 342 .. code-block:: html+django 342 343 343 344 <p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p> 344 345 345 .. _`strftime syntax`: http://docs.python.org/library/time.html#time.strftime346 347 346 The parser for this function should grab the parameter and create a ``Node`` 348 347 object:: 349 348 -
docs/howto/outputting-pdf.txt
97 97 ============ 98 98 99 99 If you're creating a complex PDF document with ReportLab, consider using the 100 cStringIO_ library as a temporary holding place for your PDF file. The cStringIO 101 library provides a file-like object interface that is particularly efficient. 102 Here's the above "Hello World" example rewritten to use ``cStringIO``:: 100 :mod:`cStringIO` library as a temporary holding place for your PDF file. The 101 ``cStringIO`` library provides a file-like object interface that is particularly 102 efficient. Here's the above "Hello World" example rewritten to use 103 ``cStringIO``:: 103 104 104 105 # Fall back to StringIO in environments where cStringIO is not available 105 106 try: … … 133 134 response.write(pdf) 134 135 return response 135 136 136 .. _cStringIO: http://docs.python.org/library/stringio.html#module-cStringIO137 138 137 Further resources 139 138 ================= 140 139 -
docs/topics/http/file-uploads.txt
149 149 150 150 :setting:`FILE_UPLOAD_PERMISSIONS` 151 151 The numeric mode (i.e. ``0644``) to set newly uploaded files to. For 152 more information about what these modes mean, see the `documentation for153 os.chmod`_152 more information about what these modes mean, see the documentation for 153 :func:`os.chmod`. 154 154 155 155 If this isn't given or is ``None``, you'll get operating-system 156 156 dependent behavior. On most platforms, temporary files will have a mode … … 179 179 Which means "try to upload to memory first, then fall back to temporary 180 180 files." 181 181 182 .. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod183 184 182 ``UploadedFile`` objects 185 183 ======================== 186 184 -
docs/topics/http/sessions.txt
553 553 ================= 554 554 555 555 * The session dictionary should accept any pickleable Python object. See 556 `the pickle module`_for more information.556 :mod:`the pickle module <pickle>` for more information. 557 557 558 558 * Session data is stored in a database table named ``django_session`` . 559 559 560 560 * Django only sends a cookie if it needs to. If you don't set any session 561 561 data, it won't send a session cookie. 562 562 563 .. _`the pickle module`: http://docs.python.org/library/pickle.html564 565 563 Session IDs in URLs 566 564 =================== 567 565 -
docs/topics/install.txt
52 52 for information on how to configure mod_wsgi once you have it 53 53 installed. 54 54 55 If you can't use mod_wsgi for some reason, fear not: Django supports 56 many other deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`; 57 it works very well with `nginx`_. Another is :doc:`FastCGI 58 </howto/deployment/fastcgi>`, perfect for using Django with servers 59 other than Apache. Additionally, Django follows the WSGI_ spec, which 60 allows it to run on a variety of server platforms. See the 61 `server-arrangements wiki page`_ for specific installation 62 instructions for each platform. 55 If you can't use mod_wsgi for some reason, fear not: Django supports many other 56 deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`; it works 57 very well with `nginx`_. Another is :doc:`FastCGI </howto/deployment/fastcgi>`, 58 perfect for using Django with servers other than Apache. Additionally, Django 59 follows the WSGI spec (:pep:`3333`), which allows it to run on a variety of 60 server platforms. See the `server-arrangements wiki page`_ for specific 61 installation instructions for each platform. 63 62 64 63 .. _Apache: http://httpd.apache.org/ 65 64 .. _nginx: http://nginx.net/ 66 65 .. _mod_wsgi: http://code.google.com/p/modwsgi/ 67 .. _WSGI: http://www.python.org/dev/peps/pep-0333/68 66 .. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements 69 67 70 68 .. _database-installation: -
docs/topics/db/models.txt
676 676 return '%s %s' % (self.first_name, self.last_name) 677 677 full_name = property(_get_full_name) 678 678 679 The last method in this example is a :term:`property`. `Read more about 680 properties`_. 679 The last method in this example is a :term:`property`. 681 680 682 .. _Read more about properties: http://www.python.org/download/releases/2.2/descrintro/#property683 684 681 The :doc:`model instance reference </ref/models/instances>` has a complete list 685 682 of :ref:`methods automatically given to each model <model-instance-methods>`. 686 683 You can override most of these -- see `overriding predefined model methods`_, -
docs/topics/db/sql.txt
259 259 Connections and cursors 260 260 ----------------------- 261 261 262 ``connection`` and ``cursor`` mostly implement the standard `Python DB-API`_ 263 (except when it comes to :doc:`transaction handling </topics/db/transactions>`). 264 If you're not familiar with the Python DB-API, note that the SQL statement in 265 ``cursor.execute()`` uses placeholders, ``"%s"``, rather than adding parameters 266 directly within the SQL. If you use this technique, the underlying database 267 library will automatically add quotes and escaping to your parameter(s) as 268 necessary. (Also note that Django expects the ``"%s"`` placeholder, *not* the 269 ``"?"`` placeholder, which is used by the SQLite Python bindings. This is for 270 the sake of consistency and sanity.) 271 272 .. _Python DB-API: http://www.python.org/dev/peps/pep-0249/ 262 ``connection`` and ``cursor`` mostly implement the standard Python DB-API 263 described in :pep:`249` (except when it comes to :doc:`transaction handling 264 </topics/db/transactions>`). If you're not familiar with the Python DB-API, note 265 that the SQL statement in ``cursor.execute()`` uses placeholders, ``"%s"``, 266 rather than adding parameters directly within the SQL. If you use this 267 technique, the underlying database library will automatically add quotes and 268 escaping to your parameter(s) as necessary. (Also note that Django expects the 269 ``"%s"`` placeholder, *not* the ``"?"`` placeholder, which is used by the SQLite 270 Python bindings. This is for the sake of consistency and sanity.) -
docs/topics/testing.txt
68 68 Writing unit tests 69 69 ------------------ 70 70 71 Django's unit tests use a Python standard library module: unittest_. This71 Django's unit tests use a Python standard library module: :mod:`unittest`. This 72 72 module defines tests in class-based approach. 73 73 74 74 .. admonition:: unittest2 … … 136 136 Python documentation for more details on how to construct a complex test 137 137 suite. 138 138 139 For more details about ``unittest``, see the `standard library unittest140 documentation `_.139 For more details about ``unittest``, see the :mod:`standard library unittest 140 documentation <unittest>`. 141 141 142 .. _unittest: http://docs.python.org/library/unittest.html143 .. _standard library unittest documentation: unittest_144 142 .. _suggested organization: http://docs.python.org/library/unittest.html#organizing-tests 145 143 146 144 Writing doctests 147 145 ---------------- 148 146 149 Doctests use Python's standard doctest_ module, which searches your docstrings150 for statements that resemble a session of the Python interactive interpreter. 151 A full explanation of how doctest works is out of the scope of this document; 152 read Python's official documentation for the details.147 Doctests use :mod:`Python's standard doctest module <doctest>`, which searches 148 your docstrings for statements that resemble a session of the Python interactive 149 interpreter. A full explanation of how doctest works is out of the scope of this 150 document; read Python's official documentation for the details. 153 151 154 152 .. admonition:: What's a **docstring**? 155 153 … … 221 219 on this.) Note that to use this feature, the database user Django is connecting 222 220 as must have ``CREATE DATABASE`` rights. 223 221 224 For more details about how doctest works, see the `standard library225 documentation for doctest `_.222 For more details about how doctest works, see the :mod:`standard library 223 documentation for doctest<doctest>`. 226 224 227 .. _doctest: http://docs.python.org/library/doctest.html228 .. _standard library documentation for doctest: doctest_229 230 231 225 Which should I use? 232 226 ------------------- 233 227 … … 639 633 640 634 The test client is not capable of retrieving Web pages that are not 641 635 powered by your Django project. If you need to retrieve other Web pages, 642 use a Python standard library module such as urllib_ or urllib2_. 636 use a Python standard library module such as :mod:`urllib` or 637 :mod:`urllib2`. 643 638 644 639 * To resolve URLs, the test client uses whatever URLconf is pointed-to by 645 640 your :setting:`ROOT_URLCONF` setting. … … 668 663 >>> from django.test import Client 669 664 >>> csrf_client = Client(enforce_csrf_checks=True) 670 665 671 672 .. _urllib: http://docs.python.org/library/urllib.html673 .. _urllib2: http://docs.python.org/library/urllib2.html674 675 666 Making requests 676 667 ~~~~~~~~~~~~~~~ 677 668 … … 1003 994 .. attribute:: Client.cookies 1004 995 1005 996 A Python ``SimpleCookie`` object, containing the current values of all the 1006 client cookies. See the `Cookie module documentation`_for more.997 client cookies. See the :mod:`Cookie module documentation<cookie>` for more. 1007 998 1008 999 .. attribute:: Client.session 1009 1000 … … 1019 1010 session['somekey'] = 'test' 1020 1011 session.save() 1021 1012 1022 .. _Cookie module documentation: http://docs.python.org/library/cookie.html1023 1024 1013 Example 1025 1014 ~~~~~~~ 1026 1015 … … 1408 1397 1409 1398 .. versionadded:: 1.4 1410 1399 1411 For testing purposes it's often useful to change a setting temporarily 1412 and revert to the original value after running the testing code. For 1413 this use case Django provides a standard `Python context manager`_ 1400 For testing purposes it's often useful to change a setting temporarily and 1401 revert to the original value after running the testing code. For this use case 1402 Django provides a standard `Python context manager` (see :pep:`343`) 1414 1403 :meth:`~django.test.TestCase.settings`, which can be used like this:: 1415 1404 1416 1405 from django.test import TestCase … … 1437 1426 1438 1427 In case you want to override a setting for just one test method or even the 1439 1428 whole TestCase class, Django provides the 1440 :func:`django.test.utils.override_settings` decorator_. It's used like this:: 1429 :func:`django.test.utils.override_settings` decorator (see :pep:`318`). It's 1430 used like this:: 1441 1431 1442 1432 from django.test import TestCase 1443 1433 from django.test.utils import override_settings … … 1483 1473 :data:`django.test.signals.setting_changed` signal to connect cleanup 1484 1474 and other state-resetting callbacks to. 1485 1475 1486 .. _`Python context manager`: http://www.python.org/dev/peps/pep-0343/1487 .. _`decorator`: http://www.python.org/dev/peps/pep-0318/1488 1489 1476 Emptying the test outbox 1490 1477 ~~~~~~~~~~~~~~~~~~~~~~~~ 1491 1478 -
docs/topics/logging.txt
11 11 ====================== 12 12 13 13 Django uses Python's builtin logging module to perform system logging. 14 The usage of the logging module is discussed in detail in `Python's15 own documentation `_. However, if you've never used Python's logging14 The usage of the logging module is discussed in detail in :mod:`Python's 15 own documentation <logging>`. However, if you've never used Python's logging 16 16 framework (or even if you have), here's a quick primer. 17 17 18 .. _Python's own documentation: http://docs.python.org/library/logging.html19 20 18 The cast of players 21 19 ------------------- 22 20 -
docs/topics/email.txt
5 5 .. module:: django.core.mail 6 6 :synopsis: Helpers to easily send email. 7 7 8 Although Python makes sending email relatively easy via the `smtplib9 library`_, Django provides a couple of light wrappers over it. These wrappers10 are provided to make sending email extra quick, to make it easy to test 11 email sending during development, and to provide support for platforms that 12 can't useSMTP.8 Although Python makes sending email relatively easy via the :mod:`smtplib module 9 <smtplib>`, Django provides a couple of light wrappers over it. These wrappers 10 are provided to make sending email extra quick, to make it easy to test email 11 sending during development, and to provide support for platforms that can't use 12 SMTP. 13 13 14 14 The code lives in the ``django.core.mail`` module. 15 15 16 .. _smtplib library: http://docs.python.org/library/smtplib.html17 18 16 Quick example 19 17 ============= 20 18 … … 54 52 member of ``recipient_list`` will see the other recipients in the "To:" 55 53 field of the email message. 56 54 * ``fail_silently``: A boolean. If it's ``False``, ``send_mail`` will raise 57 an ``smtplib.SMTPException``. See the `smtplib docs`_ for a list of 58 possible exceptions, all of which are subclasses of ``SMTPException``. 55 an ``smtplib.SMTPException``. See the :mod:`smtplib docs <smtplib>` for a 56 list of possible exceptions, all of which are subclasses of 57 ``SMTPException``. 59 58 * ``auth_user``: The optional username to use to authenticate to the SMTP 60 59 server. If this isn't provided, Django will use the value of the 61 60 :setting:`EMAIL_HOST_USER` setting. … … 67 66 See the documentation on :ref:`Email backends <topic-email-backends>` 68 67 for more details. 69 68 70 .. _smtplib docs: http://docs.python.org/library/smtplib.html71 72 69 send_mass_mail() 73 70 ================ 74 71 … … 608 605 :setting:`EMAIL_PORT` accordingly, and you are set. 609 606 610 607 For a more detailed discussion of testing and processing of emails locally, 611 see the Python documentation on the `SMTP Server`_.608 see the Python documentation on the :mod:`SMTP Server <smtpd>`. 612 609 613 .. _SMTP Server: http://docs.python.org/library/smtpd.html614 615 610 SMTPConnection 616 611 ============== 617 612 -
docs/releases/1.3.txt
664 664 665 665 Code taking advantage of any of the features below will raise a 666 666 ``PendingDeprecationWarning`` in Django 1.3. This warning will be 667 silent by default, but may be turned on using Python's `warnings668 module `_, or by running Python with a ``-Wd`` or `-Wall` flag.667 silent by default, but may be turned on using Python's :mod:`warnings 668 module <warnings>`, or by running Python with a ``-Wd`` or `-Wall` flag. 669 669 670 .. _warnings module: http://docs.python.org/library/warnings.html671 672 670 In Django 1.4, these warnings will become a ``DeprecationWarning``, 673 671 which is *not* silent. In Django 1.5 support for these features will 674 672 be removed entirely. -
docs/releases/1.3-alpha-1.txt
279 279 280 280 Code taking advantage of any of the features below will raise a 281 281 ``PendingDeprecationWarning`` in Django 1.3. This warning will be 282 silent by default, but may be turned on using Python's `warnings283 module `_, or by running Python with a ``-Wd`` or `-Wall` flag.282 silent by default, but may be turned on using Python's :mod:`warnings 283 module <warnings>`, or by running Python with a ``-Wd`` or `-Wall` flag. 284 284 285 .. _warnings module: http://docs.python.org/library/warnings.html286 287 285 In Django 1.4, these warnings will become a ``DeprecationWarning``, 288 286 which is *not* silent. In Django 1.5 support for these features will 289 287 be removed entirely. -
docs/releases/0.96.txt
216 216 ------------------ 217 217 218 218 Django now includes a test framework so you can start transmuting fear into 219 boredom (with apologies to Kent Beck). You can write tests based on doctest_220 or unittest_and test your views with a simple test client.219 boredom (with apologies to Kent Beck). You can write tests based on 220 :mod:`doctest` or :mod:`unittest` and test your views with a simple test client. 221 221 222 222 There is also new support for "fixtures" -- initial data, stored in any of the 223 223 supported `serialization formats`_, that will be loaded into your database at the … … 225 225 226 226 See `the testing documentation`_ for the full details. 227 227 228 .. _doctest: http://docs.python.org/library/doctest.html229 .. _unittest: http://docs.python.org/library/unittest.html230 228 .. _the testing documentation: http://www.djangoproject.com/documentation/0.96/testing/ 231 229 .. _serialization formats: http://www.djangoproject.com/documentation/0.96/serialization/ 232 230 -
docs/releases/1.2.txt
764 764 765 765 Code taking advantage of any of the features below will raise a 766 766 ``PendingDeprecationWarning`` in Django 1.2. This warning will be 767 silent by default, but may be turned on using Python's `warnings768 module `_, or by running Python with a ``-Wd`` or `-Wall` flag.767 silent by default, but may be turned on using Python's :mod:`warnings 768 module <warnings>`, or by running Python with a ``-Wd`` or `-Wall` flag. 769 769 770 .. _warnings module: http://docs.python.org/library/warnings.html771 772 770 In Django 1.3, these warnings will become a ``DeprecationWarning``, 773 771 which is *not* silent. In Django 1.4 support for these features will 774 772 be removed entirely. -
docs/faq/install.txt
22 22 23 23 For a development environment -- if you just want to experiment with Django -- 24 24 you don't need to have a separate Web server installed; Django comes with its 25 own lightweight development server. For a production environment, Django 26 follows the WSGI_ spec, which means it can run on a variety of server27 platforms. 28 popular alternatives. 25 own lightweight development server. For a production environment, Django follows 26 the WSGI spec, :pep:`3333`, which means it can run on a variety of server 27 platforms. See :doc:`Deploying Django </howto/deployment/index>` for some 28 popular alternatives. Also, the `server arrangements wiki page`_ contains 29 29 details for several deployment strategies. 30 30 31 31 If you want to use Django with a database, which is probably the case, you'll … … 33 33 PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported. 34 34 35 35 .. _Python: http://www.python.org/ 36 .. _WSGI: http://www.python.org/dev/peps/pep-0333/37 36 .. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements 38 37 .. _PostgreSQL: http://www.postgresql.org/ 39 38 .. _MySQL: http://www.mysql.com/ … … 48 47 Python are often faster, have more features, and are better supported. If you 49 48 use a newer version of Python you will also have access to some APIs that 50 49 aren't available under older versions of Python. For example, since Python 2.6, 51 you can use the advanced string formatting described in `PEP 3101`_.50 you can use the advanced string formatting described in :pep:`3101`. 52 51 53 52 Third-party applications for use with Django are, of course, free to set their 54 53 own version requirements. … … 63 62 will help ease the process of dropping support for older Python versions on 64 63 the road to Python 3. 65 64 66 .. _PEP 3101: http://www.python.org/dev/peps/pep-3101/67 68 65 Can I use Django with Python 2.4? 69 66 --------------------------------- 70 67 -
docs/ref/models/querysets.txt
81 81 Pickling QuerySets 82 82 ------------------ 83 83 84 If you pickle_a ``QuerySet``, this will force all the results to be loaded84 If you :mod:`pickle` a ``QuerySet``, this will force all the results to be loaded 85 85 into memory prior to pickling. Pickling is usually used as a precursor to 86 86 caching and when the cached queryset is reloaded, you want the results to 87 87 already be present and ready for use (reading from the database can take some … … 112 112 Django version N+1. Pickles should not be used as part of a long-term 113 113 archival strategy. 114 114 115 .. _pickle: http://docs.python.org/library/pickle.html116 117 115 .. _queryset-api: 118 116 119 117 QuerySet API … … 1190 1188 .. method:: iterator() 1191 1189 1192 1190 Evaluates the ``QuerySet`` (by performing the query) and returns an 1193 `iterator`_over the results. A ``QuerySet`` typically caches its1191 iterator (see :pep:`234`) over the results. A ``QuerySet`` typically caches its 1194 1192 results internally so that repeated evaluations do not result in 1195 1193 additional queries; ``iterator()`` will instead read results directly, 1196 1194 without doing any caching at the ``QuerySet`` level. For a … … 1200 1198 Note that using ``iterator()`` on a ``QuerySet`` which has already 1201 1199 been evaluated will force it to evaluate again, repeating the query. 1202 1200 1203 .. _iterator: http://www.python.org/dev/peps/pep-0234/1204 1205 1201 latest 1206 1202 ~~~~~~ 1207 1203 -
docs/ref/models/fields.txt
500 500 setting to determine the value of the :attr:`~django.core.files.File.url` 501 501 attribute. 502 502 503 This path may contain `strftime formatting`_, which will be replaced by the504 date/time of the file upload (so that uploaded files don't fill up the given505 d irectory).503 This path may contain :func:`strftime formatting <time.strftime>`, which 504 will be replaced by the date/time of the file upload (so that uploaded files 505 don't fill up the given directory). 506 506 507 507 This may also be a callable, such as a function, which will be called to 508 508 obtain the upload path, including the filename. This callable must be able … … 560 560 561 561 For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and 562 562 :attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` 563 part of :attr:`~FileField.upload_to` is `strftime formatting`_; ``'%Y'`` is the564 four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is the two-digit565 day. If you upload a file on Jan. 15, 2007, it will be saved in the directory 566 ``/home/media/photos/2007/01/15``.563 part of :attr:`~FileField.upload_to` is :func:`strftime formatting 564 <time.strftime>`; ``'%Y'`` is the four-digit year, ``'%m'`` is the two-digit 565 month and ``'%d'`` is the two-digit day. If you upload a file on Jan. 15, 2007, 566 it will be saved in the directory ``/home/media/photos/2007/01/15``. 567 567 568 568 If you wanted to retrieve the uploaded file's on-disk filename, or the file's 569 569 size, you could use the :attr:`~django.core.files.File.name` and … … 595 595 created as ``varchar(100)`` columns in your database. As with other fields, you 596 596 can change the maximum length using the :attr:`~CharField.max_length` argument. 597 597 598 .. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime599 600 598 FileField and FieldFile 601 599 ~~~~~~~~~~~~~~~~~~~~~~~ 602 600 … … 712 710 represent those numbers differently. ``FloatField`` uses Python's ``float`` 713 711 type internally, while ``DecimalField`` uses Python's ``Decimal`` type. For 714 712 information on the difference between the two, see Python's documentation on 715 `Decimal fixed point and floating point arithmetic`_.713 :mod:`Decimal fixed point and floating point arithmetic <decimal>`. 716 714 717 .. _Decimal fixed point and floating point arithmetic: http://docs.python.org/library/decimal.html718 719 720 715 ``ImageField`` 721 716 -------------- 722 717 -
docs/ref/generic-views.txt
346 346 347 347 **Optional arguments:** 348 348 349 * ``month_format``: A format string that regulates what format the 350 ``month`` parameter uses. This should be in the syntax accepted by351 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to352 ``"%b"`` by default, which is a three-letter month abbreviation. To353 change it to use numbers, use``"%m"``.349 * ``month_format``: A format string that regulates what format the ``month`` 350 parameter uses. This should be in the syntax accepted by Python's 351 :func:`time.strftime``. It's set to ``"%b"`` by default, which is a 352 three-letter month abbreviation. To change it to use numbers, use 353 ``"%m"``. 354 354 355 355 * ``template_name``: The full name of a template to use in rendering the 356 356 page. This lets you override the default template name (see below). … … 415 415 is ``'object'`` by default. If ``template_object_name`` is ``'foo'``, 416 416 this variable's name will be ``foo_list``. 417 417 418 .. _strftime docs: http://docs.python.org/library/time.html#time.strftime419 420 418 ``django.views.generic.date_based.archive_week`` 421 419 ------------------------------------------------ 422 420 … … 516 514 517 515 **Optional arguments:** 518 516 519 * ``month_format``: A format string that regulates what format the 520 ``month`` parameter uses. This should be in the syntax accepted by521 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to522 ``"%b"`` by default, which is a three-letter month abbreviation. To523 change it to use numbers, use``"%m"``.517 * ``month_format``: A format string that regulates what format the ``month`` 518 parameter uses. This should be in the syntax accepted by Python's 519 :func:`time.strftime`. It's set to ``"%b"`` by default, which is a 520 three-letter month abbreviation. To change it to use numbers, use 521 ``"%m"``. 524 522 525 523 * ``day_format``: Like ``month_format``, but for the ``day`` parameter. 526 524 It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). … … 624 622 625 623 **Optional arguments:** 626 624 627 * ``month_format``: A format string that regulates what format the 628 ``month`` parameter uses. This should be in the syntax accepted by629 Python's ``time.strftime``. (See the `strftime docs`_.) It's set to630 ``"%b"`` by default, which is a three-letter month abbreviation. To631 change it to use numbers, use``"%m"``.625 * ``month_format``: A format string that regulates what format the ``month`` 626 parameter uses. This should be in the syntax accepted by Python's 627 :func:`time.strftime`. It's set to ``"%b"`` by default, which is a 628 three-letter month abbreviation. To change it to use numbers, use 629 ``"%m"``. 632 630 633 631 * ``day_format``: Like ``month_format``, but for the ``day`` parameter. 634 632 It defaults to ``"%d"`` (day of the month as a decimal number, 01-31). -
docs/ref/class-based-views.txt
586 586 587 587 .. attribute:: year_format 588 588 589 The strftime_ format to use when parsing the year. By default, this is590 ``'%Y'``.589 The :func:`strftime<time.strftime>` format to use when parsing the year. 590 By default, this is ``'%Y'``. 591 591 592 .. _strftime: http://docs.python.org/library/time.html#time.strftime593 594 592 .. attribute:: year 595 593 596 594 **Optional** The value for the year (as a string). By default, set to … … 598 596 599 597 .. method:: get_year_format() 600 598 601 Returns the strftime_format to use when parsing the year. Returns599 Returns the :func:`strftime<time.strftime>` format to use when parsing the year. Returns 602 600 :attr:`YearMixin.year_format` by default. 603 601 604 602 .. method:: get_year() … … 621 619 622 620 .. attribute:: month_format 623 621 624 The strftime_format to use when parsing the month. By default, this is622 The :func:`strftime<time.strftime>` format to use when parsing the month. By default, this is 625 623 ``'%b'``. 626 624 627 625 .. attribute:: month … … 631 629 632 630 .. method:: get_month_format() 633 631 634 Returns the strftime_format to use when parsing the month. Returns632 Returns the :func:`strftime<time.strftime>` format to use when parsing the month. Returns 635 633 :attr:`MonthMixin.month_format` by default. 636 634 637 635 .. method:: get_month() … … 667 665 668 666 .. attribute:: day_format 669 667 670 The strftime_format to use when parsing the day. By default, this is668 The :func:`strftime<time.strftime>` format to use when parsing the day. By default, this is 671 669 ``'%d'``. 672 670 673 671 .. attribute:: day … … 677 675 678 676 .. method:: get_day_format() 679 677 680 Returns the strftime_format to use when parsing the day. Returns678 Returns the :func:`strftime<time.strftime>` format to use when parsing the day. Returns 681 679 :attr:`DayMixin.day_format` by default. 682 680 683 681 .. method:: get_day() … … 712 710 713 711 .. attribute:: week_format 714 712 715 The strftime_format to use when parsing the week. By default, this is713 The :func:`strftime<time.strftime>` format to use when parsing the week. By default, this is 716 714 ``'%U'``. 717 715 718 716 .. attribute:: week … … 722 720 723 721 .. method:: get_week_format() 724 722 725 Returns the strftime_format to use when parsing the week. Returns723 Returns the :func:`strftime<time.strftime>` format to use when parsing the week. Returns 726 724 :attr:`WeekMixin.week_format` by default. 727 725 728 726 .. method:: get_week() -
docs/ref/templates/builtins.txt
1254 1254 c ISO 8601 format. (Note: unlike others ``2008-01-02T10:30:00.000123+02:00``, 1255 1255 formatters, such as "Z", "O" or "r", or ``2008-01-02T10:30:00.000123`` if the datetime is naive 1256 1256 the "c" formatter will not add timezone 1257 offset if value is a `naive datetime`_.) 1257 offset if value is a :class:`naive 1258 datetime <datetime.tzinfo>`.) 1258 1259 d Day of the month, 2 digits with ``'01'`` to ``'31'`` 1259 1260 leading zeros. 1260 1261 D Day of the week, textual, 3 letters. ``'Fri'`` … … 1346 1347 .. versionchanged:: 1.2 1347 1348 Predefined formats can now be influenced by the current locale. 1348 1349 1349 .. _naive datetime: http://docs.python.org/library/datetime.html#datetime.tzinfo1350 1351 1350 .. templatefilter:: default 1352 1351 1353 1352 default … … 1815 1814 pprint 1816 1815 ^^^^^^ 1817 1816 1818 A wrapper around `pprint.pprint`__-- for debugging, really.1817 A wrapper around :func:`pprint.pprint` -- for debugging, really. 1819 1818 1820 __ http://docs.python.org/library/pprint.html1821 1822 1819 .. templatefilter:: random 1823 1820 1824 1821 random -
docs/ref/exceptions.txt
128 128 .. exception:: IntegrityError 129 129 130 130 The Django wrappers for database exceptions behave exactly the same as 131 the underlying database exceptions. See `PEP 249 -Python Database API132 Specification v2.0 `_for further information.131 the underlying database exceptions. See :pep:`249`, the Python Database API 132 Specification v2.0, for further information. 133 133 134 .. _`PEP 249 - Python Database API Specification v2.0`: http://www.python.org/dev/peps/pep-0249/135 136 134 .. currentmodule:: django.db.transaction 137 135 138 136 Transaction Exceptions … … 147 145 Python Exceptions 148 146 ================= 149 147 150 Django raises built-in Python exceptions when appropriate as well. See 151 the Python `documentation`_ for further information on the built-in 152 exceptions. 153 154 .. _`documentation`: http://docs.python.org/lib/module-exceptions.html 148 Django raises built-in Python exceptions when appropriate as well. See the 149 :mod:`Python documentation <exceptions>` for further information on the 150 built-in exceptions. -
docs/ref/contrib/gis/install.txt
1235 1235 postgres# CREATE DATABASE geodjango OWNER geodjango TEMPLATE template_postgis ENCODING 'utf8'; 1236 1236 1237 1237 .. rubric:: Footnotes 1238 .. [#] The datum shifting files are needed for converting data to and from certain projections. 1239 For example, the PROJ.4 string for the `Google projection (900913) <http://spatialreference.org/ref/epsg/900913/proj4>`_ 1240 requires the ``null`` grid file only included in the extra datum shifting files. 1241 It is easier to install the shifting files now, then to have debug a problem caused by their absence later. 1242 .. [#] Specifically, GeoDjango provides support for the `OGR <http://gdal.org/ogr>`_ library, a component of GDAL. 1238 .. [#] The datum shifting files are needed for converting data to and from 1239 certain projections. 1240 For example, the PROJ.4 string for the `Google projection (900913) 1241 <http://spatialreference.org/ref/epsg/900913/proj4>`_ requires the 1242 ``null`` grid file only included in the extra datum shifting files. 1243 It is easier to install the shifting files now, then to have debug a 1244 problem caused by their absence later. 1245 .. [#] Specifically, GeoDjango provides support for the `OGR 1246 <http://gdal.org/ogr>`_ library, a component of GDAL. 1243 1247 .. [#] See `GDAL ticket #2382 <http://trac.osgeo.org/gdal/ticket/2382>`_. 1244 .. [#] GeoDjango uses the `find_library <http://docs.python.org/library/ctypes.html#finding-shared-libraries>`_1245 routine from ``ctypes.util`` to locate shared libraries.1248 .. [#] GeoDjango uses the :func:`find_library <ctypes.util.find_library>` 1249 routine from :mod:`ctypes.util` to locate shared libraries. 1246 1250 .. [#] The ``psycopg2`` Windows installers are packaged and maintained by 1247 1251 `Jason Erickson <http://www.stickpeople.com/projects/python/win-psycopg/>`_. -
docs/ref/contrib/syndication.txt
852 852 853 853 All parameters, if given, should be Unicode objects, except: 854 854 855 * ``pubdate`` should be a `Python datetime object`_.855 * ``pubdate`` should be a :class:`Python datetime object<datetime.datetime>`. 856 856 * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``. 857 857 * ``categories`` should be a sequence of Unicode objects. 858 858 … … 884 884 </feed> 885 885 886 886 .. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py 887 .. _Python datetime object: http://docs.python.org/library/datetime.html#datetime-objects888 887 889 888 .. currentmodule:: django.contrib.syndication 890 889 … … 913 912 914 913 ``SyndicationFeed.add_root_elements(self, handler)`` 915 914 Callback to add elements inside the root feed element 916 (``feed``/``channel``). ``handler`` is an `XMLGenerator`_ from Python's917 built-in SAX library; you'll call methods on it to add to the XML918 document in process.915 (``feed``/``channel``). ``handler`` is an :class:`XMLGenerator 916 <xml.sax.saxutils.XMLGenerator>` from Python's built-in SAX library; you'll 917 call methods on it to add to the XML document in process. 919 918 920 919 ``SyndicationFeed.item_attributes(self, item)`` 921 920 Return a ``dict`` of attributes to add to each item (``item``/``entry``) … … 945 944 946 945 Obviously there's a lot more work to be done for a complete custom feed class, 947 946 but the above example should demonstrate the basic idea. 948 949 .. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator -
docs/ref/request-response.txt
196 196 Returns the originating host of the request using information from the 197 197 ``HTTP_X_FORWARDED_HOST`` and ``HTTP_HOST`` headers (in that order). If 198 198 they don't provide a value, the method uses a combination of 199 ``SERVER_NAME`` and ``SERVER_PORT`` as detailed in `PEP 333`_.199 ``SERVER_NAME`` and ``SERVER_PORT`` as detailed in :pep:`3333`. 200 200 201 .. _PEP 333: http://www.python.org/dev/peps/pep-0333/202 203 201 Example: ``"127.0.0.1:8000"`` 204 202 205 203 .. note:: The :meth:`~HttpRequest.get_host()` method fails when the host is … … 645 643 ``expires``, and the auto-calculation of ``max_age`` in such case 646 644 was added. The ``httponly`` argument was also added. 647 645 648 Sets a cookie. The parameters are the same as in the `cookie Morsel`_649 object in the Python standard library.646 Sets a cookie. The parameters are the same as in the :class:`cookie Morsel 647 <Cookie.Morsel>` object in the Python standard library. 650 648 651 649 * ``max_age`` should be a number of seconds, or ``None`` (default) if 652 650 the cookie should last only as long as the client's browser session. … … 670 668 risk of client side script accessing the protected cookie 671 669 data. 672 670 673 .. _`cookie Morsel`: http://docs.python.org/library/cookie.html#Cookie.Morsel674 671 .. _HTTPOnly: http://www.owasp.org/index.php/HTTPOnly 675 672 676 673 .. method:: HttpResponse.set_signed_cookie(key, value='', salt='', max_age=None, expires=None, path='/', domain=None, secure=None, httponly=False) -
docs/ref/django-admin.txt
455 455 .. django-admin-option:: --ignore 456 456 457 457 Use the ``--ignore`` or ``-i`` option to ignore files or directories matching 458 the given `glob-style pattern`_. Use multiple times to ignore more.458 the given :mod:`glob-style pattern <glob>`. Use multiple times to ignore more. 459 459 460 460 These patterns are used by default: ``'CVS'``, ``'.*'``, ``'*~'`` 461 461 … … 463 463 464 464 django-admin.py makemessages --locale=en_US --ignore=apps/* --ignore=secret/*.html 465 465 466 .. _`glob-style pattern`: http://docs.python.org/library/glob.html467 468 466 .. django-admin-option:: --no-default-ignore 469 467 470 468 Use the ``--no-default-ignore`` option to disable the default values of -
docs/ref/settings.txt
950 950 Default: ``None`` 951 951 952 952 The numeric mode (i.e. ``0644``) to set newly uploaded files to. For 953 more information about what these modes mean, see the `documentation for954 os.chmod`_ 953 more information about what these modes mean, see the documentation for 954 :func:`os.chmod`. 955 955 956 956 If this isn't given or is ``None``, you'll get operating-system 957 957 dependent behavior. On most platforms, temporary files will have a mode … … 968 968 get totally incorrect behavior. 969 969 970 970 971 .. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod972 973 971 .. setting:: FILE_UPLOAD_TEMP_DIR 974 972 975 973 FILE_UPLOAD_TEMP_DIR -
docs/conf.py
26 26 27 27 # Add any Sphinx extension module names here, as strings. They can be extensions 28 28 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. 29 extensions = ["djangodocs" ]29 extensions = ["djangodocs", "sphinx.ext.intersphinx"] 30 30 31 31 # Add any paths that contain templates here, relative to this directory. 32 32 # templates_path = [] … … 92 92 # Note: exclude_dirnames is new in Sphinx 0.5 93 93 exclude_dirnames = ['.svn'] 94 94 95 # Links to Python's docs should reference the most recent version of the 2.x 96 # branch, which is located at this URL. 97 intersphinx_mapping = { 98 'python': ('http://docs.python.org/2.7', None), 99 'sphinx': ('http://sphinx.pocoo.org/', None), 100 } 101 102 # Python's docs don't change every week. 103 intersphinx_cache_limit = 90 # days 104 95 105 # -- Options for HTML output --------------------------------------------------- 96 106 97 107 # The theme to use for HTML and HTML Help pages. See the documentation for