Ticket #16586: 16586.3.patch
| File 16586.3.patch, 78.4 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/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/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 documentation of the :mod:`re` module. Also, the O'Reilly book "Mastering 126 Regular 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/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 :ref:`reStructuredText 47 Primer <sphinx:rst-primer>`. After that, you'll want to read about the 48 :ref:`Sphinx-specific markup <sphinx:sphinxmarkup>` that's used to manage 49 metadata, indexing, and cross-references. 49 50 50 __ http://sphinx.pocoo.org/rest.html51 __ http://sphinx.pocoo.org/markup/52 53 51 Commonly used terms 54 52 ------------------- 55 53 … … 113 111 greatly helps readers. There's basically no limit to the amount of 114 112 useful markup you can add. 115 113 114 * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx' 115 documentation. 116 116 117 Django-specific markup 117 118 ---------------------- 118 119 … … 220 221 You can find both in the :doc:`settings reference document 221 222 </ref/settings>`. 222 223 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.224 We use the Sphinx :rst:role:`doc` cross reference element when we want to 225 link to another document as a whole and the :rst:role:`ref` element when 226 we want to link to an arbitrary location in a document. 226 227 227 .. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc228 .. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref229 230 228 * Next, notice how the settings are annotated: 231 229 232 230 .. 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 the re are no files, directories or symlinks named ``django`` in your151 ``site-packages`` directory. Then create a text file named ``django.pth`` and 152 save it to your ``site-packages`` directory. That file should contain a path to 153 your copy of Django on a single line and optional comments. Here is an example 154 that points to multiple branches. Just uncomment the line for the branch you 155 want to use ('Trunk' in this example) and make sure all other lines are 156 commented::149 A third option is to use a path file (``<something>.pth``). This is a feature of 150 the :mod:`site` module. First, make sure there are no files, directories or 151 symlinks named ``django`` in your ``site-packages`` directory. Then create a 152 text file named ``django.pth`` and save it to your ``site-packages`` directory. 153 That file should contain a path to your copy of Django on a single line and 154 optional comments. Here is an example that points to multiple branches. Just 155 uncomment the line for the branch you want to use ('trunk' in this example) and 156 make sure all other lines are commented:: 157 157 158 158 # Trunk is a svn checkout of: 159 159 # http://code.djangoproject.com/svn/django/trunk/ … … 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 … … 34 32 The code and comments should be self-explanatory, but a few things deserve a 35 33 mention: 36 34 37 * The response gets a special MIME type, ``text/csv``. This tells35 * The response gets a special MIME type, :mimetype:`text/csv`. This tells 38 36 browsers that the document is a CSV file, rather than an HTML file. If 39 37 you leave this off, browsers will probably interpret the output as HTML, 40 38 which will result in ugly, scary gobbledygook in the browser window. … … 59 57 Handling Unicode 60 58 ~~~~~~~~~~~~~~~~ 61 59 62 Python's ``csv`` module does not support Unicode input. Since Django uses60 Python's :mod:`csv` module does not support Unicode input. Since Django uses 63 61 Unicode internally this means strings read from sources such as 64 62 :class:`~django.http.HttpRequest` are potentially problematic. There are a few 65 63 options for handling this: … … 70 68 section`_. 71 69 72 70 * Use the `python-unicodecsv module`_, which aims to be a drop-in 73 replacement for ``csv`` that gracefully handles Unicode.71 replacement for :mod:`csv` that gracefully handles Unicode. 74 72 75 For more information, see the Python `CSV File Reading and Writing`_ 76 documentation. 73 For more information, see the Python documentation of the :mod:`csv` module. 77 74 78 75 .. _`csv module's examples section`: http://docs.python.org/library/csv.html#examples 79 76 .. _`python-unicodecsv module`: https://github.com/jdunck/python-unicodecsv 80 .. _`CSV File Reading and Writing`: http://docs.python.org/library/csv.html81 77 82 78 Using the template system 83 79 ========================= 84 80 85 81 Alternatively, you can use the :doc:`Django template system </topics/templates>` 86 to generate CSV. This is lower-level than using the convenient Python ``csv``82 to generate CSV. This is lower-level than using the convenient Python :mod:`csv` 87 83 module, but the solution is presented here for completeness. 88 84 89 85 The idea here is to pass a list of items to your template, and have the -
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:`~time.strftime` syntax. It's a good idea to decide the tag syntax before 339 anything else. In our case, let's say the tag should be used like this: 340 340 341 341 .. code-block:: html+django 342 342 343 343 <p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p> 344 344 345 .. _`strftime syntax`: http://docs.python.org/library/time.html#time.strftime346 347 345 The parser for this function should grab the parameter and create a ``Node`` 348 346 object:: 349 347 -
docs/howto/outputting-pdf.txt
63 63 The code and comments should be self-explanatory, but a few things deserve a 64 64 mention: 65 65 66 * The response gets a special MIME type, ``application/pdf``. This tells 67 browsers that the document is a PDF file, rather than an HTML file. If 68 you leave this off, browsers will probably interpret the output as HTML, 69 which would result in ugly, scary gobbledygook in the browser window. 66 * The response gets a special MIME type, :mimetype:`application/pdf`. This 67 tells browsers that the document is a PDF file, rather than an HTML file. 68 If you leave this off, browsers will probably interpret the output as 69 HTML, which would result in ugly, scary gobbledygook in the browser 70 window. 70 71 71 72 * The response gets an additional ``Content-Disposition`` header, which 72 73 contains the name of the PDF file. This filename is arbitrary: Call it … … 97 98 ============ 98 99 99 100 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 :mod:`cStringIO` library as a temporary holding place for your PDF file. This 101 102 library provides a file-like object interface that is particularly efficient. 102 Here's the above "Hello World" example rewritten to use ``cStringIO``::103 Here's the above "Hello World" example rewritten to use :mod:`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 … … 189 187 190 188 .. attribute:: UploadedFile.content_type 191 189 192 The content-type header uploaded with the file (e.g. ``text/plain`` or193 ``application/pdf``). Like any data supplied by the user, you shouldn't194 trust that the uploaded file is actually this type. You'll still need to195 validate that the file contains the content that the content-type header196 claims -- "trust but verify."190 The content-type header uploaded with the file (e.g. :mimetype:`text/plain` 191 or :mimetype:`application/pdf`). Like any data supplied by the user, you 192 shouldn't trust that the uploaded file is actually this type. You'll still 193 need to validate that the file contains the content that the content-type 194 header claims -- "trust but verify." 197 195 198 196 .. attribute:: UploadedFile.charset 199 197 200 For ``text/*`` content-types, the character set (i.e. ``utf8``) supplied201 by the browser. Again, "trust but verify" is the best policy here.198 For :mimetype:`text/*` content-types, the character set (i.e. ``utf8``) 199 supplied by the browser. Again, "trust but verify" is the best policy here. 202 200 203 201 .. attribute:: UploadedFile.temporary_file_path() 204 202 -
docs/topics/http/sessions.txt
495 495 session cookie. 496 496 497 497 HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It 498 is not part of the RFC2109standard for cookies, and it isn't honored498 is not part of the :rfc:`2109` standard for cookies, and it isn't honored 499 499 consistently by all browsers. However, when it is honored, it can be a 500 500 useful way to mitigate the risk of client side script accessing the 501 501 protected cookie data. … … 553 553 ================= 554 554 555 555 * The session dictionary should accept any pickleable Python object. See 556 `the pickle module`_for more information.556 the :mod:`pickle` module 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/http/views.txt
211 211 212 212 This view loads and renders the template ``403.html`` in your root template 213 213 directory, or if this file does not exist, instead serves the text 214 "403 Forbidden", as per RFC 2616(the HTTP 1.1 Specification).214 "403 Forbidden", as per :rfc:`2616` (the HTTP 1.1 Specification). 215 215 216 216 It is possible to override ``django.views.defaults.permission_denied`` in the 217 217 same way you can for the 404 and 500 views by specifying a ``handler403`` in -
docs/topics/http/shortcuts.txt
64 64 ------- 65 65 66 66 The following example renders the template ``myapp/index.html`` with the 67 MIME type ``application/xhtml+xml``::67 MIME type :mimetype:`application/xhtml+xml`:: 68 68 69 69 from django.shortcuts import render 70 70 … … 131 131 ------- 132 132 133 133 The following example renders the template ``myapp/index.html`` with the 134 MIME type ``application/xhtml+xml``::134 MIME type :mimetype:`application/xhtml+xml`:: 135 135 136 136 from django.shortcuts import render_to_response 137 137 -
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
36 36 frameworks are: 37 37 38 38 * **Unit tests** -- tests that are expressed as methods on a Python class 39 that subclasses ``unittest.TestCase`` or Django's customized39 that subclasses :class:`unittest.TestCase` or Django's customized 40 40 :class:`TestCase`. For example:: 41 41 42 42 import unittest … … 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 … … 82 82 backported for Python 2.5 compatibility. 83 83 84 84 To access this library, Django provides the 85 ``django.utils.unittest`` module alias. If you are using Python85 :mod:`django.utils.unittest` module alias. If you are using Python 86 86 2.7, or you have installed unittest2 locally, Django will map the 87 87 alias to the installed version of the unittest library. Otherwise, 88 88 Django will use it's own bundled version of unittest2. … … 104 104 places: 105 105 106 106 * The ``models.py`` file. The test runner looks for any subclass of 107 ``unittest.TestCase`` in this module.107 :class:`unittest.TestCase` in this module. 108 108 109 109 * A file called ``tests.py`` in the application directory -- i.e., the 110 110 directory that holds ``models.py``. Again, the test runner looks for any 111 subclass of ``unittest.TestCase`` in this module.111 subclass of :class:`unittest.TestCase` in this module. 112 112 113 Here is an example ``unittest.TestCase`` subclass::113 Here is an example :class:`unittest.TestCase` subclass:: 114 114 115 115 from django.utils import unittest 116 116 from myapp.models import Animal … … 124 124 self.assertEqual(self.lion.speak(), 'The lion says "roar"') 125 125 self.assertEqual(self.cat.speak(), 'The cat says "meow"') 126 126 127 When you :ref:`run your tests <running-tests>`, the default behavior of the 128 testutility is to find all the test cases (that is, subclasses of129 ``unittest.TestCase``) in ``models.py`` and ``tests.py``, automatically build a 130 test suite out of those test cases, and run that suite.127 When you :ref:`run your tests <running-tests>`, the default behavior of the test 128 utility is to find all the test cases (that is, subclasses of 129 :class:`unittest.TestCase`) in ``models.py`` and ``tests.py``, automatically 130 build a test suite out of those test cases, and run that suite. 131 131 132 132 There is a second way to define the test suite for a module: if you define a 133 133 function called ``suite()`` in either ``models.py`` or ``tests.py``, the … … 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 unittest 140 documentation`_. 139 For more details about :mod:`unittest`, see the Python documentation. 141 140 142 .. _unittest: http://docs.python.org/library/unittest.html143 .. _standard library unittest documentation: unittest_144 141 .. _suggested organization: http://docs.python.org/library/unittest.html#organizing-tests 145 142 146 143 Writing doctests 147 144 ---------------- 148 145 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.146 Doctests use Python's standard :mod:`doctest` module, which searches your 147 docstrings for statements that resemble a session of the Python interactive 148 interpreter. A full explanation of how :mod:`doctest` works is out of the scope 149 of this document; read Python's official documentation for the details. 153 150 154 151 .. admonition:: What's a **docstring**? 155 152 … … 221 218 on this.) Note that to use this feature, the database user Django is connecting 222 219 as must have ``CREATE DATABASE`` rights. 223 220 224 For more details about how doctest works, see the `standard library 225 documentation for doctest`_. 221 For more details about :mod:`doctest`, see the Python documentation. 226 222 227 .. _doctest: http://docs.python.org/library/doctest.html228 .. _standard library documentation for doctest: doctest_229 230 231 223 Which should I use? 232 224 ------------------- 233 225 … … 239 231 then, are a few key differences to help you decide which approach is right for 240 232 you: 241 233 242 * If you've been using Python for a while, ``doctest`` will probably feel234 * If you've been using Python for a while, :mod:`doctest` will probably feel 243 235 more "pythonic". It's designed to make writing tests as easy as possible, 244 236 so it requires no overhead of writing classes or methods. You simply put 245 237 tests in docstrings. This has the added advantage of serving as … … 250 242 as it can be unclear exactly why the test failed. Thus, doctests should 251 243 generally be avoided and used primarily for documentation examples only. 252 244 253 * The ``unittest`` framework will probably feel very familiar to developers254 coming from Java. ``unittest`` is inspired by Java's JUnit, so you'll255 feel at home with this method if you've used JUnit or any test framework256 inspired by JUnit.245 * The :mod:`unittest` framework will probably feel very familiar to 246 developers coming from Java. :mod:`unittest` is inspired by Java's JUnit, 247 so you'll feel at home with this method if you've used JUnit or any test 248 framework inspired by JUnit. 257 249 258 250 * If you need to write a bunch of tests that share similar code, then 259 you'll appreciate the ``unittest`` framework's organization around251 you'll appreciate the :mod:`unittest` framework's organization around 260 252 classes and methods. This makes it easy to abstract common tasks into 261 253 common methods. The framework also supports explicit setup and/or cleanup 262 254 routines, which give you a high level of control over the environment 263 255 in which your test cases are run. 264 256 265 * If you're writing tests for Django itself, you should use ``unittest``.257 * If you're writing tests for Django itself, you should use :mod:`unittest`. 266 258 267 259 .. _running-tests: 268 260 … … 553 545 554 546 A full explanation of this error output is beyond the scope of this document, 555 547 but it's pretty intuitive. You can consult the documentation of Python's 556 ``unittest`` library for details.548 :mod:`unittest` library for details. 557 549 558 550 Note that the return code for the test-runner script is 1 for any number of 559 551 failed and erroneous tests. If all the tests pass, the return code is 0. This … … 639 631 640 632 The test client is not capable of retrieving Web pages that are not 641 633 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_. 634 use a Python standard library module such as :mod:`urllib` or 635 :mod:`urllib2`. 643 636 644 637 * To resolve URLs, the test client uses whatever URLconf is pointed-to by 645 638 your :setting:`ROOT_URLCONF` setting. … … 668 661 >>> from django.test import Client 669 662 >>> csrf_client = Client(enforce_csrf_checks=True) 670 663 671 672 .. _urllib: http://docs.python.org/library/urllib.html673 .. _urllib2: http://docs.python.org/library/urllib2.html674 675 664 Making requests 676 665 ~~~~~~~~~~~~~~~ 677 666 … … 759 748 760 749 name=fred&passwd=secret 761 750 762 If you provide ``content_type`` (e.g. , ``text/xml`` for an XML751 If you provide ``content_type`` (e.g. :mimetype:`text/xml` for an XML 763 752 payload), the contents of ``data`` will be sent as-is in the POST 764 753 request, using ``content_type`` in the HTTP ``Content-Type`` header. 765 754 766 755 If you don't provide a value for ``content_type``, the values in 767 756 ``data`` will be transmitted with a content type of 768 ``multipart/form-data``. In this case, the key-value pairs in ``data``769 will be encoded as a multipart message and used to create the POST data770 payload.757 :mimetype:`multipart/form-data`. In this case, the key-value pairs in 758 ``data`` will be encoded as a multipart message and used to create the 759 POST data payload. 771 760 772 761 To submit multiple values for a given key -- for example, to specify 773 762 the selections for a ``<select multiple>`` -- provide the values as a … … 955 944 956 945 .. attribute:: status_code 957 946 958 The HTTP status of the response, as an integer. See RFC2616_ for a full959 list of HTTP status codes.947 The HTTP status of the response, as an integer. See 948 :rfc:`2616#section-10` for a full list of HTTP status codes. 960 949 961 950 .. versionadded:: 1.3 962 951 … … 972 961 of any settings in the HTTP headers. For example, you could determine the 973 962 content type of a response using ``response['Content-Type']``. 974 963 975 .. _RFC2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html976 977 964 Exceptions 978 965 ~~~~~~~~~~ 979 966 980 967 If you point the test client at a view that raises an exception, that exception 981 will be visible in the test case. You can then use a standard ``try ...except``982 block or ``unittest.TestCase.assertRaises()`` to test for exceptions.968 will be visible in the test case. You can then use a standard ``try ... except`` 969 block or :meth:`~unittest.TestCase.assertRaises` to test for exceptions. 983 970 984 971 The only exceptions that are not visible to the test client are ``Http404``, 985 972 ``PermissionDenied`` and ``SystemExit``. Django catches these exceptions … … 1002 989 1003 990 .. attribute:: Client.cookies 1004 991 1005 A Python ``SimpleCookie`` object, containing the current values of all the 1006 client cookies. See the `Cookie module documentation`_ for more. 992 A Python :class:`~Cookie.SimpleCookie` object, containing the current values 993 of all the client cookies. See the documentation of the :mod:`Cookie` module 994 for more. 1007 995 1008 996 .. attribute:: Client.session 1009 997 … … 1019 1007 session['somekey'] = 'test' 1020 1008 session.save() 1021 1009 1022 .. _Cookie module documentation: http://docs.python.org/library/cookie.html1023 1024 1010 Example 1025 1011 ~~~~~~~ 1026 1012 … … 1100 1086 1101 1087 .. currentmodule:: django.test 1102 1088 1103 Normal Python unit test classes extend a base class of ``unittest.TestCase``.1104 Django provides a few extensions of this base class:1089 Normal Python unit test classes extend a base class of 1090 :class:`unittest.TestCase`. Django provides a few extensions of this base class: 1105 1091 1106 1092 .. class:: TestCase() 1107 1093 1108 1094 This class provides some additional capabilities that can be useful for testing 1109 1095 Web sites. 1110 1096 1111 Converting a normal ``unittest.TestCase`` to a Django ``TestCase`` is easy:1112 just change the base class of your test from ``unittest.TestCase`` to1113 ``django.test.TestCase``. All of the standard Python unit test functionality 1114 will continue to be available, but it will be augmented with some useful 1115 additions, including:1097 Converting a normal :class:`unittest.TestCase` to a Django :class:`TestCase` is 1098 easy: just change the base class of your test from :class:`unittest.TestCase` to 1099 :class:`django.test.TestCase`. All of the standard Python unit test 1100 functionality will continue to be available, but it will be augmented with some 1101 useful additions, including: 1116 1102 1117 1103 * Automatic loading of fixtures. 1118 1104 … … 1409 1395 1410 1396 .. versionadded:: 1.4 1411 1397 1412 For testing purposes it's often useful to change a setting temporarily 1413 and revert to the original value after running the testing code. For 1414 this use case Django provides a standard `Python context manager`_ 1398 For testing purposes it's often useful to change a setting temporarily and 1399 revert to the original value after running the testing code. For this use case 1400 Django provides a standard Python context manager (see :pep:`343`) 1415 1401 :meth:`~django.test.TestCase.settings`, which can be used like this:: 1416 1402 1417 1403 from django.test import TestCase … … 1437 1423 .. function:: override_settings 1438 1424 1439 1425 In case you want to override a setting for just one test method or even the 1440 whole TestCase class, Django provides the 1441 :func:`django.test.utils.override_settings` decorator_. It's used like this:: 1426 whole :class:`TestCase` class, Django provides the 1427 :func:`~django.test.utils.override_settings` decorator (see :pep:`318`). It's 1428 used like this:: 1442 1429 1443 1430 from django.test import TestCase 1444 1431 from django.test.utils import override_settings … … 1484 1471 :data:`django.test.signals.setting_changed` signal to connect cleanup 1485 1472 and other state-resetting callbacks to. 1486 1473 1487 .. _`Python context manager`: http://www.python.org/dev/peps/pep-0343/1488 .. _`decorator`: http://www.python.org/dev/peps/pep-0318/1489 1490 1474 Emptying the test outbox 1491 1475 ~~~~~~~~~~~~~~~~~~~~~~~~ 1492 1476 … … 1505 1489 .. versionchanged:: 1.2 1506 1490 Addded ``msg_prefix`` argument. 1507 1491 1508 As Python's normal ``unittest.TestCase`` class implements assertion methods 1509 such as ``assertTrue`` and ``assertEqual``, Django's custom ``TestCase`` class 1492 As Python's normal :class:`unittest.TestCase` class implements assertion methods 1493 such as :meth:`~unittest.TestCase.assertTrue` and 1494 :meth:`~unittest.TestCase.assertEqual`, Django's custom :class:`TestCase` class 1510 1495 provides a number of custom assertion methods that are useful for testing Web 1511 1496 applications: 1512 1497 … … 1521 1506 Asserts that execution of callable ``callable_obj`` raised the 1522 1507 ``expected_exception`` exception and that such exception has an 1523 1508 ``expected_message`` representation. Any other outcome is reported as a 1524 failure. Similar to unittest's ``assertRaisesRegexp`` with the difference1525 that ``expected_message`` isn't a regular expression.1509 failure. Similar to unittest's :meth:`~unittest.TestCase.assertRaisesRegexp` 1510 with the difference that ``expected_message`` isn't a regular expression. 1526 1511 1527 1512 .. method:: assertFieldOutput(self, fieldclass, valid, invalid, field_args=None, field_kwargs=None, empty_value=u'') 1528 1513 … … 1706 1691 1707 1692 .. versionadded:: 1.3 1708 1693 1709 The unittest library provides the ``@skipIf`` and ``@skipUnless`` 1710 decorators to allow you to skip tests if you know ahead of time that 1711 those tests are going to fail under certain conditions. 1694 The unittest library provides the :func:`@skipIf <unittest.skipIf>` and 1695 :func:`@skipUnless <unittest.skipUnless>` decorators to allow you to skip tests 1696 if you know ahead of time that those tests are going to fail under certain 1697 conditions. 1712 1698 1713 For example, if your test requires a particular optional library in 1714 order to succeed, you could decorate the test case with ``@skipIf``. 1715 Then, the test runner will report that the test wasn't executed and 1716 why, instead of failing the test or omitting the test altogether.1699 For example, if your test requires a particular optional library in order to 1700 succeed, you could decorate the test case with :func:`@skipIf 1701 <unittest.skipIf>`. Then, the test runner will report that the test wasn't 1702 executed and why, instead of failing the test or omitting the test altogether. 1717 1703 1718 1704 To supplement these test skipping behaviors, Django provides two 1719 1705 additional skip decorators. Instead of testing a generic boolean, … … 1757 1743 Using different testing frameworks 1758 1744 ================================== 1759 1745 1760 Clearly, ``doctest`` and ``unittest`` are not the only Python testing1746 Clearly, :mod:`doctest` and :mod:`unittest` are not the only Python testing 1761 1747 frameworks. While Django doesn't provide explicit support for alternative 1762 1748 frameworks, it does provide a way to invoke tests constructed for an 1763 1749 alternative framework as if they were normal Django tests. -
docs/topics/logging.txt
10 10 A quick logging primer 11 11 ====================== 12 12 13 Django uses Python's builtin loggingmodule to perform system logging.14 The usage of th e logging module is discussed in detail in `Python's15 own documentation`_. However, if you've never used Python's logging 16 framework (or even if you have),here's a quick primer.13 Django uses Python's builtin :mod:`logging` module to perform system logging. 14 The usage of this module is discussed in detail in Python's own documentation. 15 However, if you've never used Python's logging framework (or even if you have), 16 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 wrappers 10 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` 9 module, Django provides a couple of light wrappers over it. These wrappers are 10 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 :exc:`smtplib.SMTPException`. See the :mod:`smtplib` docs for a list of 56 possible exceptions, all of which are subclasses of 57 :exc:`~smtplib.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 … … 125 122 .. versionchanged:: 1.3 126 123 127 124 If ``html_message`` is provided, the resulting email will be a 128 multipart/alternative email with ``message`` as the "text/plain" 129 content type and ``html_message`` as the "text/html" content type. 125 :mimetype:`multipart/alternative` email with ``message`` as the 126 :mimetype:`text/plain` content type and ``html_message`` as the 127 :mimetype:`text/html` content type. 130 128 131 129 mail_managers() 132 130 =============== … … 608 606 :setting:`EMAIL_PORT` accordingly, and you are set. 609 607 610 608 For a more detailed discussion of testing and processing of emails locally, 611 see the Python documentation on the `SMTP Server`_.609 see the Python documentation for the :mod:`smtpd` module. 612 610 613 .. _SMTP Server: http://docs.python.org/library/smtpd.html614 615 611 SMTPConnection 616 612 ============== 617 613 -
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, 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/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, 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.4.txt
462 462 Previously, Django's :doc:`CSRF protection </ref/contrib/csrf/>` provided 463 463 protection against only POST requests. Since use of PUT and DELETE methods in 464 464 AJAX applications is becoming more common, we now protect all methods not 465 defined as safe by RFC 2616i.e. we exempt GET, HEAD, OPTIONS and TRACE, and465 defined as safe by :rfc:`2616` i.e. we exempt GET, HEAD, OPTIONS and TRACE, and 466 466 enforce protection on everything else. 467 467 468 468 If you using PUT or DELETE methods in AJAX applications, please see the -
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, 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/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 … … 1206 1204 .. method:: iterator() 1207 1205 1208 1206 Evaluates the ``QuerySet`` (by performing the query) and returns an 1209 `iterator`_over the results. A ``QuerySet`` typically caches its1207 iterator (see :pep:`234`) over the results. A ``QuerySet`` typically caches its 1210 1208 results internally so that repeated evaluations do not result in 1211 1209 additional queries; ``iterator()`` will instead read results directly, 1212 1210 without doing any caching at the ``QuerySet`` level. For a … … 1216 1214 Note that using ``iterator()`` on a ``QuerySet`` which has already 1217 1215 been evaluated will force it to evaluate again, repeating the query. 1218 1216 1219 .. _iterator: http://www.python.org/dev/peps/pep-0234/1220 1221 1217 latest 1222 1218 ~~~~~~ 1223 1219 -
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 directory).503 This path may contain :func:`~time.strftime` formatting, which will be 504 replaced by the date/time of the file upload (so that uploaded files don't 505 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-digit 565 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:`~time.strftime` formatting; 564 ``'%Y'`` is the four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is 565 the two-digit day. If you upload a file on Jan. 15, 2007, it will be saved in 566 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 … … 711 709 :class:`DecimalField` class. Although they both represent real numbers, they 712 710 represent those numbers differently. ``FloatField`` uses Python's ``float`` 713 711 type internally, while ``DecimalField`` uses Python's ``Decimal`` type. For 714 information on the difference between the two, see Python's documentation on715 `Decimal fixed point and floating point arithmetic`_.712 information on the difference between the two, see Python's documentation 713 for the :mod:`decimal` module. 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 … … 777 772 ``2a02:42fe::4``). The admin represents this as an ``<input type="text">`` 778 773 (a single-line input). 779 774 780 The IPv6 address normalization follows `RFC4291 section 2.2`_, including using781 the IPv4 format suggested in paragraph 3 of that section, like775 The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2, 776 including using the IPv4 format suggested in paragraph 3 of that section, like 782 777 ``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to 783 ``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All 784 charactersare converted to lowercase.778 ``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters 779 are converted to lowercase. 785 780 786 .. _RFC4291 section 2.2: http://tools.ietf.org/html/rfc4291#section-2.2787 788 781 .. attribute:: GenericIPAddressField.protocol 789 782 790 783 Limits valid inputs to the specified protocol. -
docs/ref/models/instances.txt
432 432 433 433 .. note:: 434 434 The string you return from ``get_absolute_url()`` must contain only ASCII 435 characters (required by the URI spec, `RFC 2396`_) that have been435 characters (required by the URI spec, :rfc:`2396`) that have been 436 436 URL-encoded, if necessary. Code and templates using ``get_absolute_url()`` 437 437 should be able to use the result directly without needing to do any 438 438 further processing. You may wish to use the 439 439 ``django.utils.encoding.iri_to_uri()`` function to help with this if you 440 440 are using unicode strings a lot. 441 441 442 .. _RFC 2396: http://www.ietf.org/rfc/rfc2396.txt443 444 442 The ``permalink`` decorator 445 443 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 446 444 -
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/forms/fields.txt
639 639 * Validates that the given value is a valid IP address. 640 640 * Error message keys: ``required``, ``invalid`` 641 641 642 The IPv6 address normalization follows `RFC4291 section 2.2`_, including using643 the IPv4 format suggested in paragraph 3 of that section, like642 The IPv6 address normalization follows :rfc:`4291#section-2.2` section 2.2, 643 including using the IPv4 format suggested in paragraph 3 of that section, like 644 644 ``::ffff:192.0.2.0``. For example, ``2001:0::0:01`` would be normalized to 645 ``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All 646 charactersare converted to lowercase.645 ``2001::1``, and ``::ffff:0a0a:0a0a`` to ``::ffff:10.10.10.10``. All characters 646 are converted to lowercase. 647 647 648 .. _RFC4291 section 2.2: http://tools.ietf.org/html/rfc4291#section-2.2649 650 648 Takes two optional arguments: 651 649 652 650 .. attribute:: GenericIPAddressField.protocol -
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:`~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:`~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:`~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:`~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:`~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:`~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:`~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:`~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 naive datetime 1258 (see :class:`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'`` … … 1288 1289 if they're zero and the special-case 1289 1290 strings 'midnight' and 'noon' if 1290 1291 appropriate. Proprietary extension. 1291 r RFC 2822 formatted date.``'Thu, 21 Dec 2000 16:01:07 +0200'``1292 r :rfc:`2822` formatted date. ``'Thu, 21 Dec 2000 16:01:07 +0200'`` 1292 1293 s Seconds, 2 digits with leading zeros. ``'00'`` to ``'59'`` 1293 1294 S English ordinal suffix for day of the ``'st'``, ``'nd'``, ``'rd'`` or ``'th'`` 1294 1295 month, 2 characters. … … 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 Python documentation for further information on the 150 built-in :mod:`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:`~ctypes.util.find_library` routine from 1249 :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`_. 856 * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``. 855 * ``pubdate`` should be a Python :class:`~datetime.datetime` object. 856 * ``enclosure`` should be an instance of 857 :class:`django.utils.feedgenerator.Enclosure`. 857 858 * ``categories`` should be a sequence of Unicode objects. 858 859 859 860 :meth:`.SyndicationFeed.write` … … 884 885 </feed> 885 886 886 887 .. _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 888 889 889 .. currentmodule:: django.contrib.syndication 890 890 … … 913 913 914 914 ``SyndicationFeed.add_root_elements(self, handler)`` 915 915 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.916 (``feed``/``channel``). ``handler`` is an 917 :class:`~xml.sax.saxutils.XMLGenerator` from Python's built-in SAX library; 918 you'll call methods on it to add to the XML document in process. 919 919 920 920 ``SyndicationFeed.item_attributes(self, item)`` 921 921 Return a ``dict`` of attributes to add to each item (``item``/``entry``) … … 945 945 946 946 Obviously there's a lot more work to be done for a complete custom feed class, 947 947 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/contrib/csrf.txt
14 14 a site with someone else's credentials, is also covered. 15 15 16 16 The first defense against CSRF attacks is to ensure that GET requests (and other 17 'safe' methods, as defined by `9.1.1 Safe Methods, HTTP 1.1, RFC 2616`_) are 18 side-effect free. Requests via 'unsafe' methods, such as POST, PUT and DELETE, 19 can then be protected by following the steps below. 17 'safe' methods, as defined by 9.1.1 Safe Methods, HTTP 1.1, 18 :rfc:`2616#section-9.1.1`) are side-effect free. Requests via 'unsafe' methods, 19 such as POST, PUT and DELETE, can then be protected by following the steps 20 below. 20 21 21 22 .. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF 22 .. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html23 23 24 24 .. _using-csrf: 25 25 … … 228 228 to POST data back. 229 229 230 230 It deliberately ignores GET requests (and other requests that are defined as 231 'safe' by RFC 2616). These requests ought never to have any potentially231 'safe' by :rfc:`2616`). These requests ought never to have any potentially 232 232 dangerous side effects , and so a CSRF attack with a GET request ought to be 233 harmless. RFC 2616defines POST, PUT and DELETE as 'unsafe', and all other233 harmless. :rfc:`2616` defines POST, PUT and DELETE as 'unsafe', and all other 234 234 methods are assumed to be unsafe, for maximum protection. 235 235 236 236 Caching -
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`_646 Sets a cookie. The parameters are the same as in the :class:`Cookie.Morsel` 649 647 object in the Python standard library. 650 648 651 649 * ``max_age`` should be a number of seconds, or ``None`` (default) if … … 664 662 JavaScript from having access to the cookie. 665 663 666 664 HTTPOnly_ is a flag included in a Set-Cookie HTTP response 667 header. It is not part of the RFC2109standard for cookies,665 header. It is not part of the :rfc:`2109` standard for cookies, 668 666 and it isn't honored consistently by all browsers. However, 669 667 when it is honored, it can be a useful way to mitigate the 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/unicode.txt
148 148 Web frameworks have to deal with URLs (which are a type of IRI_). One 149 149 requirement of URLs is that they are encoded using only ASCII characters. 150 150 However, in an international environment, you might need to construct a 151 URL from an IRI_ -- very loosely speaking, a URI that can contain Unicode151 URL from an IRI_ -- very loosely speaking, a URI_ that can contain Unicode 152 152 characters. Quoting and converting an IRI to URI can be a little tricky, so 153 153 Django provides some assistance. 154 154 155 155 * The function ``django.utils.encoding.iri_to_uri()`` implements the 156 conversion from IRI to URI as required by the specification (`RFC 157 3987`_). 156 conversion from IRI to URI as required by the specification (:rfc:`3987`). 158 157 159 158 * The functions ``django.utils.http.urlquote()`` and 160 159 ``django.utils.http.urlquote_plus()`` are versions of Python's standard … … 203 202 204 203 .. _URI: http://www.ietf.org/rfc/rfc2396.txt 205 204 .. _IRI: http://www.ietf.org/rfc/rfc3987.txt 206 .. _RFC 3987: IRI_207 205 208 206 Models 209 207 ====== -
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. 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
1010 1010 Default: ``None`` 1011 1011 1012 1012 The numeric mode (i.e. ``0644``) to set newly uploaded files to. For 1013 more information about what these modes mean, see the `documentation for1014 os.chmod`_ 1013 more information about what these modes mean, see the documentation for 1014 :func:`os.chmod`. 1015 1015 1016 1016 If this isn't given or is ``None``, you'll get operating-system 1017 1017 dependent behavior. On most platforms, temporary files will have a mode … … 1028 1028 get totally incorrect behavior. 1029 1029 1030 1030 1031 .. _documentation for os.chmod: http://docs.python.org/library/os.html#os.chmod1032 1033 1031 .. setting:: FILE_UPLOAD_TEMP_DIR 1034 1032 1035 1033 FILE_UPLOAD_TEMP_DIR … … 1586 1584 session cookie. 1587 1585 1588 1586 HTTPOnly_ is a flag included in a Set-Cookie HTTP response header. It 1589 is not part of the RFC2109standard for cookies, and it isn't honored1587 is not part of the :rfc:`2109` standard for cookies, and it isn't honored 1590 1588 consistently by all browsers. However, when it is honored, it can be a 1591 1589 useful way to mitigate the risk of client side script accessing the 1592 1590 protected cookie data. -
docs/ref/utils.txt
21 21 header of response objects directly and decorators that change functions to do 22 22 that header-patching themselves. 23 23 24 For information on the ``Vary`` header, see `RFC 2616 section 14.44`_. 24 For information on the ``Vary`` header, see :rfc:`2616#section-14.44` section 25 14.44. 25 26 26 .. _RFC 2616 section 14.44: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4427 28 27 Essentially, the ``Vary`` HTTP header defines which headers a cache should take 29 28 into account when building its cache key. Requests with the same path but 30 29 different header content for headers named in ``Vary`` need to get different … … 179 178 Convert an Internationalized Resource Identifier (IRI) portion to a URI 180 179 portion that is suitable for inclusion in a URL. 181 180 182 This is the algorithm from section 3.1 of `RFC 3987`_. However, since we183 are assuming input is either UTF-8 or unicode already, we can simplify184 things a little from the full method.181 This is the algorithm from section 3.1 of :rfc:`3987#section-3.1`. However, 182 since we are assuming input is either UTF-8 or unicode already, we can 183 simplify things a little from the full method. 185 184 186 .. _RFC 3987: http://www.ietf.org/rfc/rfc3987.txt187 188 185 Returns an ASCII string containing the encoded result. 189 186 190 187 ``django.utils.feedgenerator`` … … 397 394 398 395 .. function:: http_date(epoch_seconds=None) 399 396 400 Formats the time to match the RFC 1123date format as specified by HTTP401 `RFC 2616`_section 3.3.1.397 Formats the time to match the :rfc:`1123` date format as specified by HTTP 398 :rfc:`2616#section-3.3.1` section 3.3.1. 402 399 403 .. _RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616.txt404 405 400 Accepts a floating point number expressed in seconds since the epoch in 406 401 UTC--such as that outputted by ``time.time()``. If set to ``None``, 407 402 defaults to the current time. -
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