diff options
Diffstat (limited to 'docs/ref/models')
| -rw-r--r-- | docs/ref/models/fields.txt | 23 | ||||
| -rw-r--r-- | docs/ref/models/index.txt | 4 | ||||
| -rw-r--r-- | docs/ref/models/instances.txt | 32 | ||||
| -rw-r--r-- | docs/ref/models/options.txt | 2 | ||||
| -rw-r--r-- | docs/ref/models/querysets.txt | 46 | ||||
| -rw-r--r-- | docs/ref/models/relations.txt | 2 |
6 files changed, 43 insertions, 66 deletions
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 3a0066987f..68208b3bfe 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -1,5 +1,3 @@ -.. _ref-models-fields: - ===================== Model field reference ===================== @@ -14,8 +12,8 @@ This document contains all the gory details about all the `field options`_ and .. seealso:: - If the built-in fields don't do the trick, you can easily :ref:`write your - own custom model fields <howto-custom-model-fields>`. + If the built-in fields don't do the trick, you can easily :doc:`write your + own custom model fields </howto/custom-model-fields>`. .. note:: @@ -293,8 +291,6 @@ A human-readable name for the field. If the verbose name isn't given, Django will automatically create it using the field's attribute name, converting underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`. -.. _model-field-types: - ``validators`` ------------------- @@ -302,9 +298,10 @@ underscores to spaces. See :ref:`Verbose field names <verbose-field-names>`. .. attribute:: Field.validators -A list of validators to run for this field.See the :ref:`validators -documentation <ref-validators>` for more information. +A list of validators to run for this field.See the :doc:`validators +documentation </ref/validators>` for more information. +.. _model-field-types: Field types =========== @@ -370,8 +367,8 @@ The admin represents this as an ``<input type="text">`` (a single-line input). If you are writing an application that must be portable to multiple database backends, you should be aware that there are restrictions on - ``max_length`` for some backends. Refer to the :ref:`database backend - notes <ref-databases>` for details. + ``max_length`` for some backends. Refer to the :doc:`database backend + notes </ref/databases>` for details. .. admonition:: MySQL users @@ -518,7 +515,7 @@ Also has one optional argument: .. versionadded:: 1.0 Optional. A storage object, which handles the storage and retrieval of your - files. See :ref:`topics-files` for details on how to provide this object. + files. See :doc:`/topics/files` for details on how to provide this object. The admin represents this field as an ``<input type="file">`` (a file-upload widget). @@ -553,7 +550,7 @@ day. If you upload a file on Jan. 15, 2007, it will be saved in the directory If you want to retrieve the upload file's on-disk filename, or a URL that refers to that file, or the file's size, you can use the :attr:`~django.core.files.File.name`, :attr:`~django.core.files.File.url` -and :attr:`~django.core.files.File.size` attributes; see :ref:`topics-files`. +and :attr:`~django.core.files.File.size` attributes; see :doc:`/topics/files`. Note that whenever you deal with uploaded files, you should pay close attention to where you're uploading them and what type of files they are, to avoid @@ -903,7 +900,7 @@ define the details of how the relation works. .. attribute:: ForeignKey.limit_choices_to - A dictionary of lookup arguments and values (see :ref:`topics-db-queries`) + A dictionary of lookup arguments and values (see :doc:`/topics/db/queries`) that limit the available admin choices for this object. Use this with functions from the Python ``datetime`` module to limit choices of objects by date. For example:: diff --git a/docs/ref/models/index.txt b/docs/ref/models/index.txt index 64b47b26cc..b5896c35ed 100644 --- a/docs/ref/models/index.txt +++ b/docs/ref/models/index.txt @@ -1,10 +1,8 @@ -.. _ref-models-index: - ====== Models ====== -Model API reference. For introductory material, see :ref:`topics-db-models`. +Model API reference. For introductory material, see :doc:`/topics/db/models`. .. toctree:: :maxdepth: 1 diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 7e6cdeb5c7..dfe4c747e8 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -1,5 +1,3 @@ -.. _ref-models-instances: - ======================== Model instance reference ======================== @@ -7,13 +5,13 @@ Model instance reference .. currentmodule:: django.db.models This document describes the details of the ``Model`` API. It builds on the -material presented in the :ref:`model <topics-db-models>` and :ref:`database -query <topics-db-queries>` guides, so you'll probably want to read and +material presented in the :doc:`model </topics/db/models>` and :doc:`database +query </topics/db/queries>` guides, so you'll probably want to read and understand those documents before reading this one. Throughout this reference we'll use the :ref:`example weblog models -<queryset-model-example>` presented in the :ref:`database query guide -<topics-db-queries>`. +<queryset-model-example>` presented in the :doc:`database query guide +</topics/db/queries>`. Creating objects ================ @@ -45,8 +43,8 @@ All three steps are performed when you call by a model's When you use a ``ModelForm``, the call to ``is_valid()`` will perform these validation steps for all the fields that are included on the -form. (See the :ref:`ModelForm documentation -<topics-forms-modelforms>` for more information.) You should only need +form. (See the :doc:`ModelForm documentation +</topics/forms/modelforms>` for more information.) You should only need to call a model's ``full_clean()`` method if you plan to handle validation errors yourself, or if you have excluded fields from the ModelForm that require validation. @@ -107,9 +105,9 @@ special key that is used for errors that are tied to the entire model instead of to a specific field. You can access these errors with ``NON_FIELD_ERRORS``:: - from django.core.validators import ValidationError, NON_FIELD_ERRORS + from django.core.exceptions import ValidationError, NON_FIELD_ERRORS try: - article.full_clean(): + article.full_clean() except ValidationError, e: non_field_errors = e.message_dict[NON_FIELD_ERRORS] @@ -215,7 +213,7 @@ What happens when you save? When you save an object, Django performs the following steps: - 1. **Emit a pre-save signal.** The :ref:`signal <ref-signals>` + 1. **Emit a pre-save signal.** The :doc:`signal </ref/signals>` :attr:`django.db.models.signals.pre_save` is sent, allowing any functions listening for that signal to take some customized action. @@ -426,8 +424,8 @@ Django uses this in its admin interface. If an object defines link that will jump you directly to the object's public view, according to ``get_absolute_url()``. -Also, a couple of other bits of Django, such as the :ref:`syndication feed -framework <ref-contrib-syndication>`, use ``get_absolute_url()`` as a +Also, a couple of other bits of Django, such as the :doc:`syndication feed +framework </ref/contrib/syndication>`, use ``get_absolute_url()`` as a convenience to reward people who've defined the method. It's good practice to use ``get_absolute_url()`` in templates, instead of @@ -517,14 +515,14 @@ the ``url`` function):: ...and then using that name to perform the reverse URL resolution instead of the view name:: - from django.db.models import permalink + from django.db import models @models.permalink def get_absolute_url(self): return ('people_view', [str(self.id)]) -More details on named URL patterns are in the :ref:`URL dispatch documentation -<topics-http-urls>`. +More details on named URL patterns are in the :doc:`URL dispatch documentation +</topics/http/urls>`. Extra instance methods ====================== @@ -570,3 +568,5 @@ described in :ref:`Field lookups <field-lookups>`. Note that in the case of identical date values, these methods will use the ID as a fallback check. This guarantees that no records are skipped or duplicated. + +That also means you cannot use those methods on unsaved objects. diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index f3e7363e36..3dfcdfffbc 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -1,5 +1,3 @@ -.. _ref-models-options: - ====================== Model ``Meta`` options ====================== diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 56ff6444e4..87680d3e4d 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1,5 +1,3 @@ -.. _ref-models-querysets: - ====================== QuerySet API reference ====================== @@ -7,13 +5,13 @@ QuerySet API reference .. currentmodule:: django.db.models.QuerySet This document describes the details of the ``QuerySet`` API. It builds on the -material presented in the :ref:`model <topics-db-models>` and :ref:`database -query <topics-db-queries>` guides, so you'll probably want to read and +material presented in the :doc:`model </topics/db/models>` and :doc:`database +query </topics/db/queries>` guides, so you'll probably want to read and understand those documents before reading this one. Throughout this reference we'll use the :ref:`example weblog models -<queryset-model-example>` presented in the :ref:`database query guide -<topics-db-queries>`. +<queryset-model-example>` presented in the :doc:`database query guide +</topics/db/queries>`. .. _when-querysets-are-evaluated: @@ -223,8 +221,8 @@ control the name of the annotation:: >>> q[0].number_of_entries 42 -For an in-depth discussion of aggregation, see :ref:`the topic guide on -Aggregation <topics-db-aggregation>`. +For an in-depth discussion of aggregation, see :doc:`the topic guide on +Aggregation </topics/db/aggregation>`. ``order_by(*fields)`` ~~~~~~~~~~~~~~~~~~~~~ @@ -332,8 +330,6 @@ a model which defines a default ordering, or when using ordering was undefined prior to calling ``reverse()``, and will remain undefined afterward). -.. _queryset-distinct: - ``distinct()`` ~~~~~~~~~~~~~~ @@ -367,9 +363,6 @@ query spans multiple tables, it's possible to get duplicate results when a ``values()`` together, be careful when ordering by fields not in the ``values()`` call. - -.. _queryset-values: - ``values(*fields)`` ~~~~~~~~~~~~~~~~~~~ @@ -679,8 +672,6 @@ related object. ``OneToOneFields`` will not be traversed in the reverse direction if you are performing a depth-based ``select_related``. -.. _queryset-extra: - ``extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -712,9 +703,10 @@ of the arguments is required, but you should use at least one of them. greater than Jan. 1, 2006. Django inserts the given SQL snippet directly into the ``SELECT`` - statement, so the resulting SQL of the above example would be:: + statement, so the resulting SQL of the above example would be something + like:: - SELECT blog_entry.*, (pub_date > '2006-01-01') + SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent FROM blog_entry; @@ -843,8 +835,6 @@ of the arguments is required, but you should use at least one of them. Entry.objects.extra(where=['headline=%s'], params=['Lennon']) -.. _queryset-defer: - ``defer(*fields)`` ~~~~~~~~~~~~~~~~~~ @@ -870,7 +860,7 @@ deferred field will be retrieved from the database if you access that field You can make multiple calls to ``defer()``. Each call adds new fields to the deferred set:: - # Defers both the body and lede fields. + # Defers both the body and headline fields. Entry.objects.defer("body").filter(rating=5).defer("headline") The order in which fields are added to the deferred set does not matter. Calling ``defer()`` with a field name that has already been deferred is harmless (the field will still be deferred). @@ -930,7 +920,7 @@ immediately; the remainder are deferred. Thus, successive calls to ``only()`` result in only the final fields being considered:: # This will defer all fields except the headline. - Entry.objects.only("body", "lede").only("headline") + Entry.objects.only("body", "rating").only("headline") Since ``defer()`` acts incrementally (adding fields to the deferred list), you can combine calls to ``only()`` and ``defer()`` and things will behave @@ -973,8 +963,6 @@ something *other than* a ``QuerySet``. These methods do not use a cache (see :ref:`caching-and-querysets`). Rather, they query the database each time they're called. -.. _get-kwargs: - ``get(**kwargs)`` ~~~~~~~~~~~~~~~~~ @@ -1143,8 +1131,6 @@ Example:: If you pass ``in_bulk()`` an empty list, you'll get an empty dictionary. -.. _queryset-iterator: - ``iterator()`` ~~~~~~~~~~~~~~ @@ -1216,8 +1202,8 @@ control the name of the aggregation value that is returned:: >>> q = Blog.objects.aggregate(number_of_entries=Count('entry')) {'number_of_entries': 16} -For an in-depth discussion of aggregation, see :ref:`the topic guide on -Aggregation <topics-db-aggregation>`. +For an in-depth discussion of aggregation, see :doc:`the topic guide on +Aggregation </topics/db/aggregation>`. ``exists()`` ~~~~~~~~~~~~ @@ -1277,7 +1263,7 @@ SQL equivalents:: a Django setting. It's possible to configure your MySQL tables to use case-sensitive comparisons, but some trade-offs are involved. For more information about this, see the :ref:`collation section <mysql-collation>` - in the :ref:`databases <ref-databases>` documentation. + in the :doc:`databases </ref/databases>` documentation. .. fieldlookup:: iexact @@ -1570,7 +1556,7 @@ Example:: SQL equivalent:: - SELECT ... WHERE EXTRACT('year' FROM pub_date) = '2005'; + SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31 23:59:59.999999'; (The exact SQL syntax varies for each database engine.) @@ -1736,7 +1722,7 @@ Aggregation Functions Django provides the following aggregation functions in the ``django.db.models`` module. For details on how to use these aggregate functions, see -:ref:`the topic guide on aggregation <topics-db-aggregation>`. +:doc:`the topic guide on aggregation </topics/db/aggregation>`. ``Avg`` ~~~~~~~ diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt index f58cfe7301..0481644d7a 100644 --- a/docs/ref/models/relations.txt +++ b/docs/ref/models/relations.txt @@ -1,5 +1,3 @@ -.. _ref-models-relations: - ========================= Related objects reference ========================= |