diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/apache_auth.txt | 2 | ||||
| -rw-r--r-- | docs/authentication.txt | 32 | ||||
| -rw-r--r-- | docs/contributing.txt | 6 | ||||
| -rw-r--r-- | docs/db-api.txt | 10 | ||||
| -rw-r--r-- | docs/django-admin.txt | 8 | ||||
| -rw-r--r-- | docs/forms.txt | 19 | ||||
| -rw-r--r-- | docs/model-api.txt | 2 | ||||
| -rw-r--r-- | docs/serialization.txt | 22 | ||||
| -rw-r--r-- | docs/settings.txt | 7 |
9 files changed, 64 insertions, 44 deletions
diff --git a/docs/apache_auth.txt b/docs/apache_auth.txt index 72e0841305..b85057924b 100644 --- a/docs/apache_auth.txt +++ b/docs/apache_auth.txt @@ -6,7 +6,7 @@ Since keeping multiple authentication databases in sync is a common problem when dealing with Apache, you can configuring Apache to authenticate against Django's `authentication system`_ directly. For example, you could: - * Serve media files directly from Apache only to authenticated users. + * Serve static/media files directly from Apache only to authenticated users. * Authenticate access to a Subversion_ repository against Django users with a certain permission. diff --git a/docs/authentication.txt b/docs/authentication.txt index 31a894512a..6d345adaec 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -456,9 +456,9 @@ As a shortcut, you can use the convenient ``user_passes_test`` decorator:: # ... my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view) -We are using this particular test as a relatively simple example, however be -aware that if you just want to test if a permission is available to a user, -you can use the ``permission_required()`` decorator described below. +We're using this particular test as a relatively simple example. However, if +you just want to test whether a permission is available to a user, you can use +the ``permission_required()`` decorator, described later in this document. Here's the same thing, using Python 2.4's decorator syntax:: @@ -495,20 +495,30 @@ Example in Python 2.4 syntax:: The permission_required decorator ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Since checking whether a user has a particular permission available to them is a -relatively common operation, Django provides a shortcut for that particular -case: the ``permission_required()`` decorator. Using this decorator, the -earlier example can be written as:: +**New in Django development version** + +It's a relatively common task to check whether a user has a particular +permission. For that reason, Django provides a shortcut for that case: the +``permission_required()`` decorator. Using this decorator, the earlier example +can be written as:: from django.contrib.auth.decorators import permission_required - + def my_view(request): # ... - my_view = permission_required('polls.can_vote')(my_view) Note that ``permission_required()`` also takes an optional ``login_url`` -parameter. +parameter. Example:: + + from django.contrib.auth.decorators import permission_required + + def my_view(request): + # ... + my_view = permission_required('polls.can_vote', login_url='/loginpage/')(my_view) + +As in the ``login_required`` decorator, ``login_url`` defaults to +``'/accounts/login/'``. Limiting access to generic views -------------------------------- @@ -633,7 +643,7 @@ The currently logged-in user, either a ``User`` instance or an``AnonymousUser`` instance, is stored in the template variable ``{{ user }}``:: {% if user.is_authenticated %} - <p>Welcome, {{ user.username }}. Thanks for logging in.</p> + <p>Welcome, {{ user.username }}. Thanks for logging in.</p> {% else %} <p>Welcome, new user. Please log in.</p> {% endif %} diff --git a/docs/contributing.txt b/docs/contributing.txt index 7ecda7425c..6ff0b038a3 100644 --- a/docs/contributing.txt +++ b/docs/contributing.txt @@ -259,10 +259,10 @@ The tests cover: We appreciate any and all contributions to the test suite! The Django tests all use the testing infrastructure that ships with Django for -testing applications. See `Testing Django Applications`_ for an explanation of +testing applications. See `Testing Django applications`_ for an explanation of how to write new tests. -.. _Testing Django Applications: http://www.djangoproject.com/documentation/testing/ +.. _Testing Django applications: http://www.djangoproject.com/documentation/testing/ Running the unit tests ---------------------- @@ -273,7 +273,7 @@ To run the tests, ``cd`` to the ``tests/`` directory and type:: Yes, the unit tests need a settings module, but only for database connection info -- the ``DATABASE_ENGINE``, ``DATABASE_USER`` and ``DATABASE_PASSWORD``. -You will also need a ``ROOT_URLCONF`` setting (it's value is ignored; it just +You will also need a ``ROOT_URLCONF`` setting (its value is ignored; it just needs to be present) and a ``SITE_ID`` setting (any integer value will do) in order for all the tests to pass. diff --git a/docs/db-api.txt b/docs/db-api.txt index 7800ff324a..0d1f049601 100644 --- a/docs/db-api.txt +++ b/docs/db-api.txt @@ -1140,7 +1140,7 @@ The pk lookup shortcut ---------------------- For convenience, Django provides a ``pk`` lookup type, which stands for -"primary_key". This is shorthand for "an exact lookup on the primary-key." +"primary_key". In the example ``Blog`` model, the primary key is the ``id`` field, so these three statements are equivalent:: @@ -1149,6 +1149,14 @@ three statements are equivalent:: Blog.objects.get(id=14) # __exact is implied Blog.objects.get(pk=14) # pk implies id__exact +The use of ``pk`` isn't limited to ``__exact`` queries -- any query term +can be combined with ``pk`` to perform a query on the primary key of a model:: + + # Get blogs entries with id 1, 4 and 7 + Blog.objects.filter(pk__in=[1,4,7]) + # Get all blog entries with id > 14 + Blog.objects.filter(pk__gt=14) + ``pk`` lookups also work across joins. For example, these three statements are equivalent:: diff --git a/docs/django-admin.txt b/docs/django-admin.txt index ed162f0520..7f9682b443 100644 --- a/docs/django-admin.txt +++ b/docs/django-admin.txt @@ -392,10 +392,10 @@ and `2` is verbose output. Example usage:: django-admin.py manage.py --adminmedia=/tmp/new-admin-style/ -Tell Django where to find the various stylesheets and Javascript files for the -admin interface when running the development server. Normally these files are -served out of the Django source tree, but since some designers change these -files for their site, this option allows you to test against custom versions. +Tells Django where to find the various CSS and JavaScript files for the admin +interface when running the development server. Normally these files are served +out of the Django source tree, but because some designers customize these files +for their site, this option allows you to test against custom versions. Extra niceties ============== diff --git a/docs/forms.txt b/docs/forms.txt index 0ffb0bdcb7..2b00cb67d6 100644 --- a/docs/forms.txt +++ b/docs/forms.txt @@ -337,8 +337,8 @@ The only real differences are: object being edited. * We set ``new_data`` based upon ``flatten_data()`` from the manipulator. - ``flatten_data()`` takes the data from the original object under - manipulation, and converts it into a data dictionary that can be used + ``flatten_data()`` takes the data from the original object under + manipulation, and converts it into a data dictionary that can be used to populate form elements with the existing values for the object. * The above example uses a different template, so create and edit can be @@ -404,7 +404,7 @@ Here's a simple function that might drive the above form:: errors = new_data = {} form = forms.FormWrapper(manipulator, new_data, errors) return render_to_response('contact_form.html', {'form': form}) - + ``FileField`` and ``ImageField`` special cases ============================================== @@ -481,13 +481,13 @@ the data being validated. Also, because consistency in user interfaces is important, we strongly urge you to put punctuation at the end of your validation messages. -When Are Validators Called? +When are validators called? --------------------------- After a form has been submitted, Django first checks to see that all the required fields are present and non-empty. For each field that passes that test *and if the form submission contained data* for that field, all the -validators for that field are called in turn. The emphasised portion in the +validators for that field are called in turn. The emphasized portion in the last sentence is important: if a form field is not submitted (because it contains no data -- which is normal HTML behaviour), the validators are not run against the field. @@ -497,18 +497,17 @@ This feature is particularly important for models using ``forms.CheckBoxField``. If the checkbox is not selected, it will not contribute to the form submission. -If you would like your validator to *always* run, regardless of whether the -field it is attached to contains any data, set the ``always_test`` attribute -on the validator function. For example:: +If you would like your validator to run *always*, regardless of whether its +attached field contains any data, set the ``always_test`` attribute on the +validator function. For example:: def my_custom_validator(field_data, all_data): # ... - my_custom_validator.always_test = True This validator will always be executed for any field it is attached to. -Ready-made Validators +Ready-made validators --------------------- Writing your own validator is not difficult, but there are some situations diff --git a/docs/model-api.txt b/docs/model-api.txt index c6c4200239..5524c76654 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -545,7 +545,7 @@ The default value for the field. If ``False``, the field will not be editable in the admin or via form processing using the object's ``AddManipulator`` or ``ChangeManipulator`` -classes. Default is ``True``. +classes. Default is ``True``. ``help_text`` ~~~~~~~~~~~~~ diff --git a/docs/serialization.txt b/docs/serialization.txt index 694e2d25db..aee1b9a3bb 100644 --- a/docs/serialization.txt +++ b/docs/serialization.txt @@ -3,12 +3,12 @@ Serializing Django objects ========================== .. note:: - + This API is currently under heavy development and may change -- perhaps drastically -- in the future. - + You have been warned. - + Django's serialization framework provides a mechanism for "translating" Django objects into other formats. Usually these other formats will be text-based and used for sending Django objects over a wire, but it's possible for a @@ -21,7 +21,7 @@ At the highest level, serializing data is a very simple operation:: from django.core import serializers data = serializers.serialize("xml", SomeModel.objects.all()) - + The arguments to the ``serialize`` function are the format to serialize the data to (see `Serialization formats`_) and a QuerySet_ to serialize. (Actually, the second argument can be any iterator that yields Django objects, @@ -34,7 +34,7 @@ You can also use a serializer object directly:: xml_serializer = serializers.get_serializer("xml") xml_serializer.serialize(queryset) data = xml_serializer.getvalue() - + This is useful if you want to serialize data directly to a file-like object (which includes a HTTPResponse_):: @@ -50,7 +50,7 @@ Deserializing data is also a fairly simple operation:: for obj in serializers.deserialize("xml", data): do_something_with(obj) - + As you can see, the ``deserialize`` function takes the same format argument as ``serialize``, a string or stream of data, and returns an iterator. @@ -69,7 +69,7 @@ something like:: for deserialized_object in serializers.deserialize("xml", data): if object_should_be_saved(deserialized_object): obj.save() - + In other words, the usual use is to examine the deserialized objects to make sure that they are "appropriate" for saving before doing so. Of course, if you trust your data source you could just save the object and move on. @@ -89,22 +89,22 @@ Django "ships" with a few included serializers: bundled with Django). ``python`` Translates to and from "simple" Python objects (lists, dicts, - strings, etc.). Not really all that useful on its own, but + strings, etc.). Not really all that useful on its own, but used as a base for other serializers. ========== ============================================================== .. _json: http://json.org/ .. _simplejson: http://undefined.org/python/#simplejson -Notes For Specific Serialization Formats +Notes for specific serialization formats ---------------------------------------- json ~~~~ -If you are using UTF-8 (or any other non-ASCII encoding) data with the JSON +If you're using UTF-8 (or any other non-ASCII encoding) data with the JSON serializer, you must pass ``ensure_ascii=False`` as a parameter to the -``serialize()`` call. Otherwise the output will not be encoded correctly. +``serialize()`` call. Otherwise, the output won't be encoded correctly. For example:: diff --git a/docs/settings.txt b/docs/settings.txt index 6764f01513..57483cbef3 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -606,8 +606,11 @@ See also ``APPEND_SLASH``. PROFANITIES_LIST ---------------- -A list of profanities that will trigger a validation error when the -``hasNoProfanities`` validator is called. +A tuple of profanities, as strings, that will trigger a validation error when +the ``hasNoProfanities`` validator is called. + +We don't list the default values here, because that would be profane. To see +the default values, see the file ``django/conf/global_settings.py``. ROOT_URLCONF ------------ |