From 609eaf130d2d9eac109aefa59bfced32b67b9eb1 Mon Sep 17 00:00:00 2001 From: Joseph Kocherhans Date: Tue, 25 Sep 2007 00:08:38 +0000 Subject: newforms-admin: Merged to [6416] git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@6417 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/authentication.txt | 37 +++++++++++++++++++++++++++++++++++++ docs/db-api.txt | 2 +- docs/django-admin.txt | 29 +++++++++++++++++++++++++++++ docs/email.txt | 20 +++++++++++--------- docs/generic_views.txt | 7 ++++++- docs/model-api.txt | 13 +++++++++++++ docs/newforms.txt | 21 ++++++++++++++++----- docs/request_response.txt | 2 +- docs/sessions.txt | 4 ++-- docs/settings.txt | 2 +- docs/templates_python.txt | 34 ++++++++++++++++++++++++++++++---- 11 files changed, 147 insertions(+), 24 deletions(-) (limited to 'docs') 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/db-api.txt b/docs/db-api.txt index 08b5391e3c..adca8b4d5c 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -952,7 +952,7 @@ Example:: If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary. ``iterator()`` -~~~~~~~~~~~~ +~~~~~~~~~~~~~~ Evaluates the ``QuerySet`` (by performing the query) and returns an `iterator`_ over the results. A ``QuerySet`` typically reads all of diff --git a/docs/django-admin.txt b/docs/django-admin.txt index 0f99987bad..f098dfa988 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -735,3 +735,32 @@ distribution. It enables tab-completion of ``django-admin.py`` and * Press [TAB] to see all available options. * Type ``sql``, then [TAB], to see all available options whose names start with ``sql``. + +Customized actions +================== + +**New in Django development version** + +If you want to add an action of your own to ``manage.py``, you can. +Simply add a ``management/commands`` directory to your application. +Each python module in that directory will be discovered and registered as +a command that can be executed as an action when you run ``manage.py``:: + + /fancy_blog + __init__.py + models.py + /management + __init__.py + /commands + __init__.py + explode.py + views.py + +In this example, ``explode`` command will be made available to any project +that includes the ``fancy_blog`` application in ``settings.INSTALLED_APPS``. + +The ``explode.py`` module has only one requirement -- it must define a class +called ``Command`` that extends ``django.core.management.base.BaseCommand``. + +For more details on how to define your own commands, look at the code for the +existing ``django-admin.py`` commands, in ``/django/core/management/commands``. diff --git a/docs/email.txt b/docs/email.txt index 17c2b2115a..2bad79ce33 100644 --- a/docs/email.txt +++ b/docs/email.txt @@ -100,31 +100,31 @@ mail_admins() ============= ``django.core.mail.mail_admins()`` is a shortcut for sending an e-mail to the -site admins, as defined in the `ADMINS setting`_. Here's the definition:: +site admins, as defined in the `ADMINS`_ setting. Here's the definition:: mail_admins(subject, message, fail_silently=False) ``mail_admins()`` prefixes the subject with the value of the -`EMAIL_SUBJECT_PREFIX setting`_, which is ``"[Django] "`` by default. +`EMAIL_SUBJECT_PREFIX`_ setting, which is ``"[Django] "`` by default. -The "From:" header of the e-mail will be the value of the `SERVER_EMAIL setting`_. +The "From:" header of the e-mail will be the value of the `SERVER_EMAIL`_ setting. This method exists for convenience and readability. -.. _ADMINS setting: ../settings/#admins -.. _EMAIL_SUBJECT_PREFIX setting: ../settings/#email-subject-prefix -.. _SERVER_EMAIL setting: ../settings/#server-email +.. _ADMINS: ../settings/#admins +.. _EMAIL_SUBJECT_PREFIX: ../settings/#email-subject-prefix +.. _SERVER_EMAIL: ../settings/#server-email mail_managers() function ======================== ``django.core.mail.mail_managers()`` is just like ``mail_admins()``, except it -sends an e-mail to the site managers, as defined in the `MANAGERS setting`_. +sends an e-mail to the site managers, as defined in the `MANAGERS`_ setting. Here's the definition:: mail_managers(subject, message, fail_silently=False) -.. _MANAGERS setting: ../settings/#managers +.. _MANAGERS: ../settings/#managers Examples ======== @@ -225,7 +225,7 @@ optional and can be set at any time prior to calling the ``send()`` method. * ``from_email``: The sender's address. Both ``fred@example.com`` and ``Fred `` forms are legal. If omitted, the - ``DEFAULT_FROM_EMAIL`` setting is used. + `DEFAULT_FROM_EMAIL`_ setting is used. * ``to``: A list or tuple of recipient addresses. @@ -297,6 +297,8 @@ The class has the following methods: message.attach_file('/images/weather_map.png') +.. _DEFAULT_FROM_EMAIL: ../settings/#default-from-email + Sending alternative content types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/generic_views.txt b/docs/generic_views.txt index 87b82f7adf..08ff01c372 100644 --- a/docs/generic_views.txt +++ b/docs/generic_views.txt @@ -800,9 +800,14 @@ specify the page number in the URL in one of two ways: variable. You can iterate over the list provided by ``page_range`` to create a link to every page of results. -These values and lists are is 1-based, not 0-based, so the first page would be +These values and lists are 1-based, not 0-based, so the first page would be represented as page ``1``. +An example of the use of pagination can be found in the `object pagination`_ +example model. + +.. _`object pagination`: ../models/pagination/ + **New in Django development version:** As a special case, you are also permitted to use diff --git a/docs/model-api.txt b/docs/model-api.txt index adb9cfceb1..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`` ~~~~~~~~~~~~~~~~ diff --git a/docs/newforms.txt b/docs/newforms.txt index 6ff96e3b98..54bd6306c7 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -1926,11 +1926,22 @@ of the model fields: .. note:: If you specify ``fields`` when creating a form with ``form_for_model()``, - make sure that the fields that are *not* specified can provide default - values, or are allowed to have a value of ``None``. If a field isn't - specified on a form, the object created from the form can't provide - a value for that attribute, which will prevent the new instance from - being saved. + then the fields that are *not* specified will not be set by the form's + ``save()`` method. Django will prevent any attempt to save an incomplete + model, so if the model does not allow the missing fields to be empty, and + does not provide a default value for the missing fields, any attempt to + ``save()`` a ``form_for_model`` with missing fields will fail. To avoid + this failure, you must use ``save(commit=False)`` and manually set any + extra required fields:: + + instance = form.save(commit=False) + instance.required_field = 'new value' + instance.save() + + See the `section on saving forms`_ for more details on using + ``save(commit=False)``. + +.. _section on saving forms: `The save() method`_ Overriding the default field types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/request_response.txt b/docs/request_response.txt index bf914fb5ff..7806886841 100644 --- a/docs/request_response.txt +++ b/docs/request_response.txt @@ -190,7 +190,7 @@ necessary because some HTML form elements, notably That means you can't change attributes of ``request.POST`` and ``request.GET`` directly. -``QueryDict`` implements the all standard dictionary methods, because it's a +``QueryDict`` implements all the standard dictionary methods, because it's a subclass of dictionary. Exceptions are outlined here: * ``__getitem__(key)`` -- Returns the value for the given key. If the key diff --git a/docs/sessions.txt b/docs/sessions.txt index ab7ea56aaa..96e8d36854 100644 --- a/docs/sessions.txt +++ b/docs/sessions.txt @@ -198,14 +198,14 @@ Using sessions out of views An API is available to manipulate session data outside of a view:: - >>> from django.contrib.sessions.engines.db import SessionStore + >>> 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() -If you're using the ``django.contrib.sessions.engine.db`` backend, each +If you're using the ``django.contrib.sessions.backends.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:: diff --git a/docs/settings.txt b/docs/settings.txt index e40374a822..7ad1f6441d 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -363,7 +363,7 @@ regular expression which will hide from the DEBUG view anything that contains be able to give backtraces without seeing sensitive (or offensive) settings. Still, note that there are always going to be sections of your debug output that -are inapporpriate for public consumption. File paths, configuration options, and +are inappropriate for public consumption. File paths, configuration options, and the like all give attackers extra information about your server. Never deploy a site with ``DEBUG`` turned on. diff --git a/docs/templates_python.txt b/docs/templates_python.txt index 232f54061f..b6173ad39a 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -928,10 +928,36 @@ current context, available in the ``render`` method:: ``resolve_variable`` will try to resolve ``blog_entry.date_updated`` and then format it accordingly. -.. note:: - The ``resolve_variable()`` function will throw a ``VariableDoesNotExist`` - exception if it cannot resolve the string passed to it in the current - context of the page. +.. admonition:: New in development version: + + Variable resolution has changed in the development version of Django. + ``template.resolve_variable()`` is still available, but has been deprecated + in favor of a new ``template.Variable`` class. Using this class will usually + be more efficient than calling ``template.resolve_variable`` + + To use the ``Variable`` class, simply instantiate it with the name of the + variable to be resolved, and then call ``variable.resolve(context)``. So, + in the development version, the above example would be more correctly + written as: + + .. parsed-literal:: + + class FormatTimeNode(template.Node): + def __init__(self, date_to_be_formatted, format_string): + self.date_to_be_formatted = **Variable(date_to_be_formatted)** + self.format_string = format_string + + def render(self, context): + try: + actual_date = **self.date_to_be_formatted.resolve(context)** + return actual_date.strftime(self.format_string) + except template.VariableDoesNotExist: + return '' + + Changes are highlighted in bold. + +Variable resolution will throw a ``VariableDoesNotExist`` exception if it cannot +resolve the string passed to it in the current context of the page. Shortcut for simple tags ~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.3