diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/apache_auth.txt | 4 | ||||
| -rw-r--r-- | docs/authentication.txt | 37 | ||||
| -rw-r--r-- | docs/django-admin.txt | 6 | ||||
| -rw-r--r-- | docs/email.txt | 2 | ||||
| -rw-r--r-- | docs/i18n.txt | 9 | ||||
| -rw-r--r-- | docs/install.txt | 2 | ||||
| -rw-r--r-- | docs/model-api.txt | 24 | ||||
| -rw-r--r-- | docs/newforms.txt | 31 | ||||
| -rw-r--r-- | docs/sessions.txt | 35 | ||||
| -rw-r--r-- | docs/settings.txt | 7 | ||||
| -rw-r--r-- | docs/templates.txt | 10 |
11 files changed, 134 insertions, 33 deletions
diff --git a/docs/apache_auth.txt b/docs/apache_auth.txt index 9beb1ba43a..cab57fe6d5 100644 --- a/docs/apache_auth.txt +++ b/docs/apache_auth.txt @@ -34,12 +34,12 @@ with the standard ``Auth*`` and ``Require`` directives:: If you're using Apache 2.2, you'll need to take a couple extra steps. You'll need to ensure that ``mod_auth_basic`` and ``mod_authz_user`` - are loaded. These might be compiled staticly into Apache, or you might + are loaded. These might be compiled statically into Apache, or you might need to use ``LoadModule`` to load them dynamically (as shown in the example at the bottom of this note). You'll also need to insert configuration directives that prevent Apache - from trying to use other authentication modules. Depnding on which other + from trying to use other authentication modules. Depending on which other authentication modules you have loaded, you might need one or more of the following directives:: diff --git a/docs/authentication.txt b/docs/authentication.txt index 713e86c140..aee9c5224a 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -1062,3 +1062,40 @@ object the first time a user authenticates:: return User.objects.get(pk=user_id) except User.DoesNotExist: return None + +Handling authorization in custom backends +----------------------------------------- + +Custom auth backends can provide their own permissions. + +The user model will delegate permission lookup functions +(``get_group_permissions()``, ``get_all_permissions()``, ``has_perm()``, and +``has_module_perms()``) to any authentication backend that implements these +functions. + +The permissions given to the user will be the superset of all permissions +returned by all backends. That is, Django grants a permission to a user that any +one backend grants. + +The simple backend above could implement permissions for the magic admin fairly +simply:: + + class SettingsBackend: + + # ... + + def has_perm(self, user_obj, perm): + if user_obj.username == settings.ADMIN_LOGIN: + return True + else: + return False + +This gives full permissions to the user granted access in the above example. Notice +that the backend auth functions all take the user object as an argument, and +they also accept the same arguments given to the associated ``User`` functions. + +A full authorization implementation can be found in +``django/contrib/auth/backends.py`` _, which is the default backend and queries +the ``auth_permission`` table most of the time. + +.. _django/contrib/auth/backends.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/backends.py diff --git a/docs/django-admin.txt b/docs/django-admin.txt index 68fcad24fe..0f99987bad 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -645,11 +645,11 @@ Examples: To run the test server on port 7000 with ``fixture1`` and ``fixture2``:: django-admin.py testserver --addrport 7000 fixture1 fixture2 - django-admin.py testserver fixture1 fixture2 --addrport 8080 + django-admin.py testserver fixture1 fixture2 --addrport 7000 (The above statements are equivalent. We include both of them to demonstrate -that it doesn't matter whether the options come before or after the -``testserver`` command.) +that it doesn't matter whether the options come before or after the fixture +arguments.) To run on 1.2.3.4:7000 with a `test` fixture:: diff --git a/docs/email.txt b/docs/email.txt index 97bdec0037..17c2b2115a 100644 --- a/docs/email.txt +++ b/docs/email.txt @@ -328,7 +328,7 @@ attribute on the ``EmailMessage`` class to change the main content type. The major type will always be ``"text"``, but you can change it to the subtype. For example:: - msg = EmailMessage(subject, html_content, from_email, to) + msg = EmailMessage(subject, html_content, from_email, [to]) msg.content_subtype = "html" # Main content is now text/html msg.send() diff --git a/docs/i18n.txt b/docs/i18n.txt index 25191e9402..bf73c88008 100644 --- a/docs/i18n.txt +++ b/docs/i18n.txt @@ -669,8 +669,11 @@ To create message files, you use the same ``make-messages.py`` tool as with the Django message files. You only need to be in the right place -- in the directory where either the ``conf/locale`` (in case of the source tree) or the ``locale/`` (in case of app messages or project messages) directory are located. And you -use the same ``compile-messages.py`` to produce the binary ``django.mo`` files that -are used by ``gettext``. +use the same ``compile-messages.py`` to produce the binary ``django.mo`` files +that are used by ``gettext``. + +You can also run ``compile-message.py --settings=path.to.settings`` to make +the compiler process all the directories in your ``LOCALE_PATHS`` setting. Application message files are a bit complicated to discover -- they need the ``LocaleMiddleware``. If you don't use the middleware, only the Django message @@ -710,7 +713,7 @@ language choice in a ``django_language`` cookie. After setting the language choice, Django redirects the user, following this algorithm: - * Django looks for a ``next`` parameter in ``POST`` request. + * Django looks for a ``next`` parameter in the ``POST`` data. * If that doesn't exist, or is empty, Django tries the URL in the ``Referrer`` header. * If that's empty -- say, if a user's browser suppresses that header -- diff --git a/docs/install.txt b/docs/install.txt index 173f4941ee..2de8529d24 100644 --- a/docs/install.txt +++ b/docs/install.txt @@ -86,7 +86,7 @@ to create a temporary test database. .. _SQLite: http://www.sqlite.org/ .. _pysqlite: http://initd.org/tracker/pysqlite .. _MySQL backend: ../databases/ -.. _cx_Oracle: http://www.python.net/crew/atuining/cx_Oracle/ +.. _cx_Oracle: http://cx-oracle.sourceforge.net/ .. _Oracle: http://www.oracle.com/ .. _testing framework: ../testing/ diff --git a/docs/model-api.txt b/docs/model-api.txt index 1f0bb60285..a0844ea961 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -293,6 +293,10 @@ visiting its URL on your site. Don't allow that. .. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941 +**New in development version:** By default, ``FileField`` instances are +created as ``varchar(100)`` columns in your database. As with other fields, you +can change the maximum length using the ``max_length`` argument. + ``FilePathField`` ~~~~~~~~~~~~~~~~~ @@ -330,6 +334,10 @@ not the full path. So, this example:: because the ``match`` applies to the base filename (``foo.gif`` and ``bar.gif``). +**New in development version:** By default, ``FilePathField`` instances are +created as ``varchar(100)`` columns in your database. As with other fields, you +can change the maximum length using the ``max_length`` argument. + ``FloatField`` ~~~~~~~~~~~~~~ @@ -361,6 +369,11 @@ Requires the `Python Imaging Library`_. .. _Python Imaging Library: http://www.pythonware.com/products/pil/ .. _elsewhere: ../db-api/#get-foo-height-and-get-foo-width +**New in development version:** By default, ``ImageField`` instances are +created as ``varchar(100)`` columns in your database. As with other fields, you +can change the maximum length using the ``max_length`` argument. + + ``IntegerField`` ~~~~~~~~~~~~~~~~ @@ -1284,6 +1297,17 @@ won't add the automatic ``id`` column. Each model requires exactly one field to have ``primary_key=True``. +The ``pk`` property +------------------- +**New in Django development version** + +Regardless of whether you define a primary key field yourself, or let Django +supply one for you, each model will have a property called ``pk``. It behaves +like a normal attribute on the model, but is actually an alias for whichever +attribute is the primary key field for the model. You can read and set this +value, just as you would for any other attribute, and it will update the +correct field in the model. + Admin options ============= diff --git a/docs/newforms.txt b/docs/newforms.txt index 19c5fc247f..2c8f67ce32 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -513,6 +513,26 @@ include ``%s`` -- then the library will act as if ``auto_id`` is ``True``. By default, ``auto_id`` is set to the string ``'id_%s'``. +Normally, a colon (``:``) will be appended after any label name when a form is +rendered. It's possible to change the colon to another character, or omit it +entirely, using the ``label_suffix`` parameter:: + + >>> f = ContactForm(auto_id='id_for_%s', label_suffix='') + >>> print f.as_ul() + <li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li> + <li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" /></li> + <li><label for="id_for_sender">Sender</label> <input type="text" name="sender" id="id_for_sender" /></li> + <li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li> + >>> f = ContactForm(auto_id='id_for_%s', label_suffix=' ->') + >>> print f.as_ul() + <li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li> + <li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" /></li> + <li><label for="id_for_sender">Sender -></label> <input type="text" name="sender" id="id_for_sender" /></li> + <li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li> + +Note that the label suffix is added only if the last character of the +label isn't a punctuation character (``.``, ``!``, ``?`` or ``:``) + Notes on field ordering ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1264,6 +1284,15 @@ When you use a ``FileField`` on a form, you must also remember to Takes two optional arguments for validation, ``max_value`` and ``min_value``. These control the range of values permitted in the field. +``IPAddressField`` +~~~~~~~~~~~~~~~~~~ + + * Default widget: ``TextInput`` + * Empty value: ``''`` (an empty string) + * Normalizes to: A Unicode object. + * Validates that the given value is a valid IPv4 address, using a regular + expression. + ``MultipleChoiceField`` ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1690,7 +1719,7 @@ the full list of conversions: ``ForeignKey`` ``ModelChoiceField`` (see below) ``ImageField`` ``ImageField`` ``IntegerField`` ``IntegerField`` - ``IPAddressField`` ``CharField`` + ``IPAddressField`` ``IPAddressField`` ``ManyToManyField`` ``ModelMultipleChoiceField`` (see below) ``NullBooleanField`` ``CharField`` diff --git a/docs/sessions.txt b/docs/sessions.txt index 023285f704..7fc607bb13 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -18,13 +18,13 @@ To enable session functionality, do the following: ``MIDDLEWARE_CLASSES`` contains ``'django.contrib.sessions.middleware.SessionMiddleware'``. The default ``settings.py`` created by ``django-admin.py startproject`` has ``SessionMiddleware`` activated. - + * Add ``'django.contrib.sessions'`` to your ``INSTALLED_APPS`` setting, and run ``manage.py syncdb`` to install the single database table that stores session data. - + **New in development version**: this step is optional if you're not using - the database session backend; see `configuring the session engine`_. + the database session backend; see `configuring the session engine`_. If you don't want to use sessions, you might as well remove the ``SessionMiddleware`` line from ``MIDDLEWARE_CLASSES`` and ``'django.contrib.sessions'`` @@ -50,7 +50,7 @@ To use file-based sessions, set the ``SESSION_ENGINE`` setting to You might also want to set the ``SESSION_FILE_PATH`` setting (which defaults to ``/tmp``) to control where Django stores session files. Be -sure to check that your web server has permissions to read and write to +sure to check that your Web server has permissions to read and write to this location. Using cache-based sessions @@ -64,8 +64,8 @@ you've configured your cache; see the `cache documentation`_ for details. .. note:: - You probably don't want to use cache-based sessions if you're not using - the memcached cache backend. The local memory and simple cache backends + You should probably only use cache-based sessions if you're using the + memcached cache backend. The local memory and simple cache backends don't retain data long enough to be good choices, and it'll be faster to use file or database sessions directly instead of sending everything through the file or database cache backends. @@ -194,25 +194,26 @@ Here's a typical usage example:: Using sessions out of views =========================== -The ``SessionStore`` which implements the session storage method can be imported -and a API is available to manipulate the session data outside of a view:: +**New in Django development version** - >>> from django.contrib.sessions.engines.db import SessionStore +An API is available to manipulate session data outside of a view:: + + >>> from django.contrib.sessions.backends.db import SessionStore >>> s = SessionStore(session_key='2b1189a188b44ad18c35e113ac6ceead') >>> s['last_login'] = datetime.datetime(2005, 8, 20, 13, 35, 10) >>> s['last_login'] datetime.datetime(2005, 8, 20, 13, 35, 0) >>> s.save() -Or if you are using the ``django.contrib.sessions.engine.db`` each -session is just a normal Django model. The ``Session`` model -is defined in ``django/contrib/sessions/models.py``. Because it's a normal -model, you can access sessions using the normal Django database API:: +If you're using the ``django.contrib.sessions.engine.db`` backend, each +session is just a normal Django model. The ``Session`` model is defined in +``django/contrib/sessions/models.py``. Because it's a normal model, you can +access sessions using the normal Django database API:: >>> from django.contrib.sessions.models import Session >>> s = Session.objects.get(pk='2b1189a188b44ad18c35e113ac6ceead') >>> s.expire_date - datetime.datetime(2005, 8, 20, 13, 35, 12) + datetime.datetime(2005, 8, 20, 13, 35, 12) Note that you'll need to call ``get_decoded()`` to get the session dictionary. This is necessary because the dictionary is stored in an encoded format:: @@ -306,10 +307,10 @@ Default: ``django.contrib.sessions.backends.db`` Controls where Django stores session data. Valid values are: - * ``'django.contrib.sessions.backends.db'`` - * ``'django.contrib.sessions.backends.file'`` + * ``'django.contrib.sessions.backends.db'`` + * ``'django.contrib.sessions.backends.file'`` * ``'django.contrib.sessions.backends.cache'`` - + See `configuring the session engine`_ for more details. SESSION_FILE_PATH diff --git a/docs/settings.txt b/docs/settings.txt index 46fdd70258..e40374a822 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -257,10 +257,11 @@ The database backend to use. The build-in database backends are ``'postgresql_psycopg2'``, ``'postgresql'``, ``'mysql'``, ``'mysql_old'``, ``'sqlite3'``, ``'oracle'``, or ``'ado_mssql'``. -You can also use a database backend that doesn't ship with Django by -setting ``DATABASE_ENGINE`` to a fully-qualified path (i.e. +In the Django development version, you can use a database backend that doesn't +ship with Django by setting ``DATABASE_ENGINE`` to a fully-qualified path (i.e. ``mypackage.backends.whatever``). Writing a whole new database backend from -scratch is left as an exercise to the reader. +scratch is left as an exercise to the reader; see the other backends for +examples. DATABASE_HOST ------------- diff --git a/docs/templates.txt b/docs/templates.txt index 9adf15731b..cd436a987d 100644 --- a/docs/templates.txt +++ b/docs/templates.txt @@ -1275,17 +1275,23 @@ For example, if ``blog_date`` is a date instance representing midnight on 1 June 2006, and ``comment_date`` is a date instance for 08:00 on 1 June 2006, then ``{{ comment_date|timesince:blog_date }}`` would return "8 hours". +Minutes is the smallest unit used, and "0 minutes" will be returned for any +date that is in the future relative to the comparison point. + timeuntil ~~~~~~~~~ Similar to ``timesince``, except that it measures the time from now until the given date or datetime. For example, if today is 1 June 2006 and ``conference_date`` is a date instance holding 29 June 2006, then -``{{ conference_date|timeuntil }}`` will return "28 days". +``{{ conference_date|timeuntil }}`` will return "4 weeks". Takes an optional argument that is a variable containing the date to use as the comparison point (instead of *now*). If ``from_date`` contains 22 June -2006, then ``{{ conference_date|timeuntil:from_date }}`` will return "7 days". +2006, then ``{{ conference_date|timeuntil:from_date }}`` will return "1 week". + +Minutes is the smallest unit used, and "0 minutes" will be returned for any +date that is in the past relative to the comparison point. title ~~~~~ |