← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal-security

« back to all changes in this revision

Viewing changes to docs/ref/models/fields.txt

  • Committer: Bazaar Package Importer
  • Author(s): Chris Lamb
  • Date: 2010-05-21 07:52:55 UTC
  • mfrom: (1.3.6 upstream)
  • mto: This revision was merged to the branch mainline in revision 28.
  • Revision ID: james.westby@ubuntu.com-20100521075255-ii78v1dyfmyu3uzx
Tags: upstream-1.2
Import upstream version 1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/ref/models/fields.txt
196
196
If ``False``, the field will not be editable in the admin or via forms
197
197
automatically generated from the model class. Default is ``True``.
198
198
 
 
199
``error_messages``
 
200
------------------
 
201
 
 
202
.. versionadded:: 1.2
 
203
 
 
204
.. attribute:: Field.error_messages
 
205
 
 
206
The ``error_messages`` argument lets you override the default messages that the
 
207
field will raise. Pass in a dictionary with keys matching the error messages you
 
208
want to override.
 
209
 
199
210
``help_text``
200
211
-------------
201
212
 
284
295
 
285
296
.. _model-field-types:
286
297
 
 
298
``validators``
 
299
-------------------
 
300
 
 
301
.. versionadded:: 1.2
 
302
 
 
303
.. attribute:: Field.validators
 
304
 
 
305
A list of validators to run for this field.See the :ref:`validators
 
306
documentation <ref-validators>` for more information.
 
307
 
 
308
 
287
309
Field types
288
310
===========
289
311
 
299
321
primary key field will automatically be added to your model if you don't specify
300
322
otherwise. See :ref:`automatic-primary-key-fields`.
301
323
 
 
324
``BigIntegerField``
 
325
-------------------
 
326
 
 
327
.. versionadded:: 1.2
 
328
 
 
329
.. class:: BigIntegerField([**options])
 
330
 
 
331
A 64 bit integer, much like an :class:`IntegerField` except that it is
 
332
guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The
 
333
admin represents this as an ``<input type="text">`` (a single-line input).
 
334
 
 
335
 
302
336
``BooleanField``
303
337
----------------
304
338
 
308
342
 
309
343
The admin represents this as a checkbox.
310
344
 
311
 
.. admonition:: MySQL users..
 
345
.. versionchanged:: 1.2
312
346
 
313
 
    A boolean field in MySQL is stored as a ``TINYINT`` column with a value of
314
 
    either 0 or 1 (most databases have a proper ``BOOLEAN`` type instead). So,
315
 
    for MySQL, only, when a ``BooleanField`` is retrieved from the database
316
 
    and stored on a model attribute, it will have the values 1 or 0, rather
317
 
    than ``True`` or ``False``. Normally, this shouldn't be a problem, since
318
 
    Python guarantees that ``1 == True`` and ``0 == False`` are both true.
319
 
    Just be careful if you're writing something like ``obj is True`` when
320
 
    ``obj`` is a value from a boolean attribute on a model. If that model was
321
 
    constructed using the ``mysql`` backend, the "``is``" test will fail.
322
 
    Prefer an equality test (using "``==``") in cases like this.
 
347
    In previous versions of Django when running under MySQL ``BooleanFields``
 
348
    would return their data as ``ints``, instead of true ``bools``.  See the
 
349
    release notes for a complete description of the change.
323
350
 
324
351
``CharField``
325
352
-------------
543
570
created as ``varchar(100)`` columns in your database. As with other fields, you
544
571
can change the maximum length using the :attr:`~CharField.max_length` argument.
545
572
 
546
 
.. _`strftime formatting`: http://docs.python.org/lib/module-time.html#l2h-1941
 
573
.. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime
 
574
 
 
575
FileField and FieldFile
 
576
~~~~~~~~~~~~~~~~~~~~~~~
 
577
 
 
578
When you access a :class:`FileField` on a model, you are given an instance
 
579
of :class:`FieldFile` as a proxy for accessing the underlying file. This
 
580
class has several methods that can be used to interact with file data:
 
581
 
 
582
.. method:: FieldFile.open(mode='rb')
 
583
 
 
584
Behaves like the standard Python ``open()`` method and opens the file
 
585
associated with this instance in the mode specified by ``mode``.
 
586
 
 
587
.. method:: FieldFile.close()
 
588
 
 
589
Behaves like the standard Python ``file.close()`` method and closes the file
 
590
associated with this instance.
 
591
 
 
592
.. method:: FieldFile.save(name, content, save=True)
 
593
 
 
594
This method takes a filename and file contents and passes them to the storage
 
595
class for the field, then associates the stored file with the model field.
 
596
If you want to manually associate file data with :class:`FileField`
 
597
instances on your model, the ``save()`` method is used to persist that file
 
598
data.
 
599
 
 
600
Takes two required arguments: ``name`` which is the name of the file, and
 
601
``content`` which is a file-like object containing the file's contents. The
 
602
optional ``save`` argument controls whether or not the instance is saved after
 
603
the file has been altered. Defaults to ``True``.
 
604
 
 
605
.. method:: FieldFile.delete(save=True)
 
606
 
 
607
Deletes the file associated with this instance and clears all attributes on
 
608
the field. Note: This method will close the file if it happens to be open when
 
609
``delete()`` is called.
 
610
 
 
611
The optional ``save`` argument controls whether or not the instance is saved
 
612
after the file has been deleted. Defaults to ``True``.
547
613
 
548
614
``FilePathField``
549
615
-----------------
605
671
 
606
672
.. class:: ImageField(upload_to=None, [height_field=None, width_field=None, max_length=100, **options])
607
673
 
608
 
Like :class:`FileField`, but validates that the uploaded object is a valid
609
 
image. Has two extra optional arguments:
 
674
Inherits all attributes and methods from :class:`FileField`, but also
 
675
validates that the uploaded object is a valid image.
 
676
 
 
677
In addition to the special attributes that are available for :class:`FileField`,
 
678
an :class:`ImageField` also has :attr:`~django.core.files.File.height` and
 
679
:attr:`~django.core.files.File.width` attributes.
 
680
 
 
681
To facilitate querying on those attributes, :class:`ImageField` has two extra
 
682
optional arguments:
610
683
 
611
684
.. attribute:: ImageField.height_field
612
685
 
618
691
    Name of a model field which will be auto-populated with the width of the
619
692
    image each time the model instance is saved.
620
693
 
621
 
In addition to the special attributes that are available for :class:`FileField`,
622
 
an :class:`ImageField` also has ``File.height`` and ``File.width`` attributes.
623
 
See :ref:`topics-files`.
624
 
 
625
694
Requires the `Python Imaging Library`_.
626
695
 
627
696
.. _Python Imaging Library: http://www.pythonware.com/products/pil/
629
698
.. versionadded:: 1.0
630
699
   The ``max_length`` argument was added in this version.
631
700
 
632
 
By default, :class:`ImageField` instances are
633
 
created as ``varchar(100)`` columns in your database. As with other fields, you
634
 
can change the maximum length using the :attr:`~CharField.max_length` argument.
 
701
By default, :class:`ImageField` instances are created as ``varchar(100)``
 
702
columns in your database. As with other fields, you can change the maximum
 
703
length using the :attr:`~CharField.max_length` argument.
635
704
 
636
705
``IntegerField``
637
706
----------------
737
806
.. attribute:: URLField.verify_exists
738
807
 
739
808
    If ``True`` (the default), the URL given will be checked for existence
740
 
    (i.e., the URL actually loads and doesn't give a 404 response). It should
741
 
    be noted that when using the single-threaded development server, validating
742
 
    a url being serverd by the same server will hang.
743
 
    This should not be a problem for multithreaded servers.
 
809
    (i.e., the URL actually loads and doesn't give a 404 response).
 
810
 
 
811
    Note that when you're using the single-threaded development server,
 
812
    validating a URL being served by the same server will hang. This should not
 
813
    be a problem for multithreaded servers.
744
814
 
745
815
The admin represents this as an ``<input type="text">`` (a single-line input).
746
816
 
844
914
    current date/time to be chosen.
845
915
 
846
916
    Instead of a dictionary this can also be a :class:`~django.db.models.Q`
847
 
    object for more :ref:`complex queries <complex-lookups-with-q>`.
848
 
 
849
 
    ``limit_choices_to`` has no effect on the inline FormSets that are created
850
 
    to display related objects in the admin.
 
917
    object for more :ref:`complex queries <complex-lookups-with-q>`. However,
 
918
    if ``limit_choices_to`` is a :class:`~django.db.models.Q` object then it
 
919
    will only have an effect on the choices available in the admin when the
 
920
    field is not listed in ``raw_id_fields`` in the ``ModelAdmin`` for the model.
851
921
 
852
922
.. attribute:: ForeignKey.related_name
853
923
 
878
948
Database Representation
879
949
~~~~~~~~~~~~~~~~~~~~~~~
880
950
 
881
 
Behind the scenes, Django creates an intermediary join table to represent the
882
 
many-to-many relationship. By default, this table name is generated using the
883
 
names of the two tables being joined. Since some databases don't support table
884
 
names above a certain length, these table names will be automatically
885
 
truncated to 64 characters and a uniqueness hash will be used. This means you
886
 
might see table names like ``author_books_9cdf4``; this is perfectly normal.
 
951
Behind the scenes, Django creates an intermediary join table to
 
952
represent the many-to-many relationship. By default, this table name
 
953
is generated using the name of the many-to-many field and the model
 
954
that contains it. Since some databases don't support table names above
 
955
a certain length, these table names will be automatically truncated to
 
956
64 characters and a uniqueness hash will be used. This means you might
 
957
see table names like ``author_books_9cdf4``; this is perfectly normal.
887
958
You can manually provide the name of the join table using the
888
959
:attr:`~ManyToManyField.db_table` option.
889
960
 
905
976
 
906
977
    ``limit_choices_to`` has no effect when used on a ``ManyToManyField`` with a
907
978
    custom intermediate table specified using the
908
 
    :attr:`~ManyToManyField.through` paramter.
 
979
    :attr:`~ManyToManyField.through` parameter.
909
980
 
910
981
.. attribute:: ManyToManyField.symmetrical
911
982