From fc779fe55aec84994e7e761c743716ba03484bcc Mon Sep 17 00:00:00 2001 From: Jeremy Dunck Date: Mon, 25 Jun 2007 19:33:37 +0000 Subject: gis: Merged revisions 5491-5539 via svnmerge from http://code.djangoproject.com/svn/django/trunk git-svn-id: http://code.djangoproject.com/svn/django/branches/gis@5540 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/authentication.txt | 2 +- docs/faq.txt | 5 ++-- docs/generic_views.txt | 4 +-- docs/install.txt | 31 ++++++++++++---------- docs/model-api.txt | 22 ++++++++++++++-- docs/newforms.txt | 2 +- docs/settings.txt | 6 ++--- docs/templates.txt | 3 ++- docs/templates_python.txt | 65 ++++++++--------------------------------------- docs/tutorial01.txt | 2 +- 10 files changed, 61 insertions(+), 81 deletions(-) (limited to 'docs') diff --git a/docs/authentication.txt b/docs/authentication.txt index 972ca42073..5e5ecdf908 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -325,7 +325,7 @@ Manually checking a user's password If you'd like to manually authenticate a user by comparing a plain-text password to the hashed password in the database, use the -convenience function `django.contrib.auth.models.check_password`. It +convenience function ``django.contrib.auth.models.check_password``. It takes two arguments: the plain-text password to check, and the full value of a user's ``password`` field in the database to check against, and returns ``True`` if they match, ``False`` otherwise. diff --git a/docs/faq.txt b/docs/faq.txt index bdd8c5360e..67ed8a49a5 100644 --- a/docs/faq.txt +++ b/docs/faq.txt @@ -104,7 +104,7 @@ Lawrence, Kansas, USA. `Wilson Miner`_ Wilson's design-fu makes us all look like rock stars. By day, he's an - interactive designer for `Apple`. Don't ask him what he's working on, or + interactive designer for `Apple`_. Don't ask him what he's working on, or he'll have to kill you. He lives in San Francisco. On IRC, Wilson goes by ``wilsonian``. @@ -301,7 +301,7 @@ means it can run on a variety of server platforms. If you want to use Django with a database, which is probably the case, you'll also need a database engine. PostgreSQL_ is recommended, because we're -PostgreSQL fans, and MySQL_ and `SQLite 3`_ are also supported. +PostgreSQL fans, and MySQL_, `SQLite 3`_, and Oracle_ are also supported. .. _Python: http://www.python.org/ .. _Apache 2: http://httpd.apache.org/ @@ -310,6 +310,7 @@ PostgreSQL fans, and MySQL_ and `SQLite 3`_ are also supported. .. _PostgreSQL: http://www.postgresql.org/ .. _MySQL: http://www.mysql.com/ .. _`SQLite 3`: http://www.sqlite.org/ +.. _Oracle: http://www.oracle.com/ Do I lose anything by using Python 2.3 versus newer Python versions, such as Python 2.5? ---------------------------------------------------------------------------------------- diff --git a/docs/generic_views.txt b/docs/generic_views.txt index 359a82506a..2b80348903 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -754,10 +754,10 @@ If the results are paginated, the context will contain these extra variables: * ``previous``: The previous page number, as an integer. This is 1-based. - * `last_on_page`: The number of the + * ``last_on_page``: The number of the last result on the current page. This is 1-based. - * `first_on_page`: The number of the + * ``first_on_page``: The number of the first result on the current page. This is 1-based. * ``pages``: The total number of pages, as an integer. diff --git a/docs/install.txt b/docs/install.txt index 4f5a4bbe31..99aad4e52d 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -17,8 +17,10 @@ probably already have it installed. Install Apache and mod_python ============================= -If you just want to experiment with Django, skip this step. Django comes with -its own Web server for development purposes. +If you just want to experiment with Django, skip ahead to the next +section; Django includes a lightweight web server you can use for +testing, so you won't need to set up Apache until you're ready to +deploy Django in production. If you want to use Django on a production site, use Apache with `mod_python`_. mod_python is similar to mod_perl -- it embeds Python within Apache and loads @@ -62,6 +64,8 @@ installed. * If you're using SQLite, you'll need pysqlite_. Use version 2.0.3 or higher. +* If you're using Oracle, you'll need cx_Oracle_, version 4.3.1 or higher. + .. _PostgreSQL: http://www.postgresql.org/ .. _MySQL: http://www.mysql.com/ .. _Django's ticket system: http://code.djangoproject.com/report/1 @@ -71,6 +75,7 @@ installed. .. _SQLite: http://www.sqlite.org/ .. _pysqlite: http://initd.org/tracker/pysqlite .. _MySQL backend: ../databases/ +.. _cx_Oracle: http://www.python.net/crew/atuining/cx_Oracle/ Remove any old versions of Django ================================= @@ -83,23 +88,20 @@ If you installed Django using ``setup.py install``, uninstalling is as simple as deleting the ``django`` directory from your Python ``site-packages``. -If you installed Django from a Python Egg, remove the Django ``.egg`` file, +If you installed Django from a Python egg, remove the Django ``.egg`` file, and remove the reference to the egg in the file named ``easy-install.pth``. This file should also be located in your ``site-packages`` directory. .. admonition:: Where are my ``site-packages`` stored? The location of the ``site-packages`` directory depends on the operating - system, and the location in which Python was installed. However, the - following locations are common: - - * If you're using Linux: ``/usr/lib/python2.X/site-packages`` + system, and the location in which Python was installed. To find out your + system's ``site-packages`` location, execute the following:: - * If you're using Windows: ``C:\Python2.X\lib\site-packages`` + python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()" - * If you're using MacOSX: ``/Library/Python2.X/site-packages`` or - ``/Library/Frameworks/Python.framework/Versions/2.X/lib/python2.X/site-packages/`` - (in later releases). + (Note that this should be run from a shell prompt, not a Python interactive + prompt.) Install the Django code ======================= @@ -138,12 +140,15 @@ latest bug fixes and improvements, follow these instructions: 1. Make sure you have Subversion_ installed. 2. Check out the Django code into your Python ``site-packages`` directory. + On Linux / Mac OSX / Unix, do this:: svn co http://code.djangoproject.com/svn/django/trunk/ django_src - ln -s `pwd`/django_src/django /usr/lib/python2.3/site-packages/django + ln -s `pwd`/django_src/django SITE-PACKAGES-DIR/django - (In the above line, change ``python2.3`` to match your current Python version.) + (In the above line, change ``SITE-PACKAGES-DIR`` to match the location of + your system's ``site-packages`` directory, as explained in the + "Where are my ``site-packages`` stored?" section above.) On Windows, do this:: diff --git a/docs/model-api.txt b/docs/model-api.txt index 09440f2b56..f7b56110d6 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -492,6 +492,11 @@ has ``null=True``, that means it has two possible values for "no data": possible values for "no data;" Django convention is to use the empty string, not ``NULL``. +.. note:: + Due to database limitations, when using the Oracle backend the + ``null=True`` option will be coerced for string-based fields that can + blank, and the value ``NULL`` will be stored to denote the empty string. + ``blank`` ~~~~~~~~~ @@ -586,6 +591,13 @@ scenes. If ``True``, ``django-admin.py sqlindexes`` will output a ``CREATE INDEX`` statement for this field. +``db_tablespace`` +~~~~~~~~~~~~~~~~~ + +If this field is indexed, the name of the database tablespace to use for the +index. The default is the ``db_tablespace`` of the model, if any. If the +backend doesn't support tablespaces, this option is ignored. + ``default`` ~~~~~~~~~~~ @@ -996,6 +1008,12 @@ If your database table name is an SQL reserved word, or contains characters that aren't allowed in Python variable names -- notably, the hyphen -- that's OK. Django quotes column and table names behind the scenes. +``db_tablespace`` +----------------- + +The name of the database tablespace to use for the model. If the backend +doesn't support tablespaces, this option is ignored. + ``get_latest_by`` ----------------- @@ -1876,11 +1894,11 @@ used by the SQLite Python bindings. This is for the sake of consistency and sanity.) A final note: If all you want to do is a custom ``WHERE`` clause, you can just -just the ``where``, ``tables`` and ``params`` arguments to the standard lookup +use the ``where``, ``tables`` and ``params`` arguments to the standard lookup API. See `Other lookup options`_. .. _Python DB-API: http://www.python.org/peps/pep-0249.html -.. _Other lookup options: ../db-api/#extra-params-select-where-tables +.. _Other lookup options: ../db-api/#extra-select-none-where-none-params-none-tables-none .. _transaction handling: ../transactions/ Overriding default model methods diff --git a/docs/newforms.txt b/docs/newforms.txt index 1511791a7d..41db04a7dd 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -110,7 +110,7 @@ shortly. Creating ``Form`` instances --------------------------- -A ``Form`` instance is either **bound** or **unbound** to a set of data. +A ``Form`` instance is either **bound** to a set of data, or **unbound**. * If it's **bound** to a set of data, it's capable of validating that data and rendering the form as HTML with the data displayed in the HTML. diff --git a/docs/settings.txt b/docs/settings.txt index 12e6dab4bc..897cdc8099 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -244,9 +244,9 @@ DATABASE_ENGINE Default: ``''`` (Empty string) -Which database backend to use. Either ``'postgresql_psycopg2'``, -``'postgresql'``, ``'mysql'``, ``'mysql_old'``, ``'sqlite3'`` or -``'ado_mssql'``. +The database backend to use. Either ``'postgresql_psycopg2'``, +``'postgresql'``, ``'mysql'``, ``'mysql_old'``, ``'sqlite3'``, +``'oracle'``, or ``'ado_mssql'``. DATABASE_HOST ------------- diff --git a/docs/templates.txt b/docs/templates.txt index cb8e238f43..c32b1af1dd 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -1266,7 +1266,8 @@ Converts URLs in plain text into clickable links. urlizetrunc ~~~~~~~~~~~ -Converts URLs into clickable links, truncating URLs to the given character limit. +Converts URLs into clickable links, truncating URLs longer than the given +character limit. **Argument:** Length to truncate URLs to diff --git a/docs/templates_python.txt b/docs/templates_python.txt index c967df1a49..7171f32612 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -219,13 +219,13 @@ be replaced with the name of the invalid variable. While ``TEMPLATE_STRING_IF_INVALID`` can be a useful debugging tool, it is a bad idea to turn it on as a 'development default'. - + Many templates, including those in the Admin site, rely upon the silence of the template system when a non-existent variable is encountered. If you assign a value other than ``''`` to ``TEMPLATE_STRING_IF_INVALID``, you will experience rendering problems with these templates and sites. - + Generally, ``TEMPLATE_STRING_IF_INVALID`` should only be enabled in order to debug a specific template problem, then cleared once debugging is complete. @@ -342,7 +342,7 @@ If ``TEMPLATE_CONTEXT_PROCESSORS`` contains this processor, every * ``user`` -- An ``auth.User`` instance representing the currently logged-in user (or an ``AnonymousUser`` instance, if the client isn't - logged in). See the `user authentication docs`. + logged in). See the `user authentication docs`_. * ``messages`` -- A list of messages (as strings) for the currently logged-in user. Behind the scenes, this calls @@ -693,15 +693,14 @@ how the compilation works and how the rendering works. When Django compiles a template, it splits the raw template text into ''nodes''. Each node is an instance of ``django.template.Node`` and has -either a ``render()`` or ``iter_render()`` method. A compiled template is, -simply, a list of ``Node`` objects. When you call ``render()`` on a compiled -template object, the template calls ``render()`` on each ``Node`` in its node -list, with the given context. The results are all concatenated together to -form the output of the template. +a ``render()`` method. A compiled template is, simply, a list of ``Node`` +objects. When you call ``render()`` on a compiled template object, the template +calls ``render()`` on each ``Node`` in its node list, with the given context. +The results are all concatenated together to form the output of the template. Thus, to define a custom template tag, you specify how the raw template tag is converted into a ``Node`` (the compilation function), and what the node's -``render()`` or ``iter_render()`` method does. +``render()`` method does. Writing the compilation function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -771,8 +770,7 @@ Writing the renderer ~~~~~~~~~~~~~~~~~~~~ The second step in writing custom tags is to define a ``Node`` subclass that -has a ``render()`` method (we will discuss the ``iter_render()`` alternative -in `Improving rendering speed`_, below). +has a ``render()`` method. Continuing the above example, we need to define ``CurrentTimeNode``:: @@ -876,7 +874,7 @@ current context, available in the ``render`` method:: def __init__(self, date_to_be_formatted, format_string): self.date_to_be_formatted = date_to_be_formatted self.format_string = format_string - + def render(self, context): try: actual_date = resolve_variable(self.date_to_be_formatted, context) @@ -1177,48 +1175,6 @@ For more examples of complex rendering, see the source code for ``{% if %}``, .. _configuration: -Improving rendering speed -~~~~~~~~~~~~~~~~~~~~~~~~~ - -For most practical purposes, the ``render()`` method on a ``Node`` will be -sufficient and the simplest way to implement a new tag. However, if your -template tag is expected to produce large strings via ``render()``, you can -speed up the rendering process (and reduce memory usage) using iterative -rendering via the ``iter_render()`` method. - -The ``iter_render()`` method should either be an iterator that yields string -chunks, one at a time, or a method that returns a sequence of string chunks. -The template renderer will join the successive chunks together when creating -the final output. The improvement over the ``render()`` method here is that -you do not need to create one large string containing all the output of the -``Node``, instead you can produce the output in smaller chunks. - -By way of example, here's a trivial ``Node`` subclass that simply returns the -contents of a file it is given:: - - class FileNode(Node): - def __init__(self, filename): - self.filename = filename - - def iter_render(self): - for line in file(self.filename): - yield line - -For very large files, the full file contents will never be read entirely into -memory when this tag is used, which is a useful optimisation. - -If you define an ``iter_render()`` method on your ``Node`` subclass, you do -not need to define a ``render()`` method. The reverse is true as well: the -default ``Node.iter_render()`` method will call your ``render()`` method if -necessary. A useful side-effect of this is that you can develop a new tag -using ``render()`` and producing all the output at once, which is easy to -debug. Then you can rewrite the method as an iterator, rename it to -``iter_render()`` and everything will still work. - -It is compulsory, however, to define *either* ``render()`` or ``iter_render()`` -in your subclass. If you omit them both, a ``TypeError`` will be raised when -the code is imported. - Configuring the template system in standalone mode ================================================== @@ -1250,4 +1206,3 @@ is of obvious interest. .. _settings file: ../settings/#using-settings-without-the-django-settings-module-environment-variable .. _settings documentation: ../settings/ - diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt index c40b051b19..d26f654f87 100644 --- a/docs/tutorial01.txt +++ b/docs/tutorial01.txt @@ -10,7 +10,7 @@ poll application. It'll consist of two parts: * A public site that lets people view polls and vote in them. - * An admin site that lets you add, change and delete poll. + * An admin site that lets you add, change and delete polls. We'll assume you have `Django installed`_ already. You can tell Django is installed by running the Python interactive interpreter and typing -- cgit v1.3