From b03203c8cb991c16ac8a3d74c8c4078182d0bb48 Mon Sep 17 00:00:00 2001 From: Nishanth Amuluru Date: Tue, 11 Jan 2011 22:41:51 +0530 Subject: removed all the buildout files --- parts/django/docs/ref/models/fields.txt | 1063 ---------------- parts/django/docs/ref/models/index.txt | 14 - parts/django/docs/ref/models/instances.txt | 570 --------- parts/django/docs/ref/models/options.txt | 269 ---- parts/django/docs/ref/models/querysets.txt | 1888 ---------------------------- parts/django/docs/ref/models/relations.txt | 105 -- 6 files changed, 3909 deletions(-) delete mode 100644 parts/django/docs/ref/models/fields.txt delete mode 100644 parts/django/docs/ref/models/index.txt delete mode 100644 parts/django/docs/ref/models/instances.txt delete mode 100644 parts/django/docs/ref/models/options.txt delete mode 100644 parts/django/docs/ref/models/querysets.txt delete mode 100644 parts/django/docs/ref/models/relations.txt (limited to 'parts/django/docs/ref/models') diff --git a/parts/django/docs/ref/models/fields.txt b/parts/django/docs/ref/models/fields.txt deleted file mode 100644 index 146ca43..0000000 --- a/parts/django/docs/ref/models/fields.txt +++ /dev/null @@ -1,1063 +0,0 @@ -===================== -Model field reference -===================== - -.. module:: django.db.models.fields - :synopsis: Built-in field types. - -.. currentmodule:: django.db.models - -This document contains all the gory details about all the `field options`_ and -`field types`_ Django's got to offer. - -.. seealso:: - - If the built-in fields don't do the trick, you can easily :doc:`write your - own custom model fields `. - -.. note:: - - Technically, these models are defined in :mod:`django.db.models.fields`, but - for convenience they're imported into :mod:`django.db.models`; the standard - convention is to use ``from django.db import models`` and refer to fields as - ``models.Field``. - -.. _common-model-field-options: - -Field options -============= - -The following arguments are available to all field types. All are optional. - -``null`` --------- - -.. attribute:: Field.null - -If ``True``, Django will store empty values as ``NULL`` in the database. Default -is ``False``. - -Note that empty string values will always get stored as empty strings, not as -``NULL``. Only use ``null=True`` for non-string fields such as integers, -booleans and dates. For both types of fields, you will also need to set -``blank=True`` if you wish to permit empty values in forms, as the -:attr:`~Field.null` parameter only affects database storage (see -:attr:`~Field.blank`). - -Avoid using :attr:`~Field.null` on string-based fields such as -:class:`CharField` and :class:`TextField` unless you have an excellent reason. -If a string-based field has ``null=True``, that means it has two possible values -for "no data": ``NULL``, and the empty string. In most cases, it's redundant to -have two possible values for "no data;" Django convention is to use the empty -string, not ``NULL``. - -.. note:: - - When using the Oracle database backend, the ``null=True`` option will be - coerced for string-based fields that have the empty string as a possible - value, and the value ``NULL`` will be stored to denote the empty string. - -``blank`` ---------- - -.. attribute:: Field.blank - -If ``True``, the field is allowed to be blank. Default is ``False``. - -Note that this is different than :attr:`~Field.null`. :attr:`~Field.null` is -purely database-related, whereas :attr:`~Field.blank` is validation-related. If -a field has ``blank=True``, validation on Django's admin site will allow entry -of an empty value. If a field has ``blank=False``, the field will be required. - -.. _field-choices: - -``choices`` ------------ - -.. attribute:: Field.choices - -An iterable (e.g., a list or tuple) of 2-tuples to use as choices for this -field. - -If this is given, Django's admin will use a select box instead of the standard -text field and will limit choices to the choices given. - -A choices list looks like this:: - - YEAR_IN_SCHOOL_CHOICES = ( - ('FR', 'Freshman'), - ('SO', 'Sophomore'), - ('JR', 'Junior'), - ('SR', 'Senior'), - ('GR', 'Graduate'), - ) - -The first element in each tuple is the actual value to be stored. The second -element is the human-readable name for the option. - -The choices list can be defined either as part of your model class:: - - class Foo(models.Model): - GENDER_CHOICES = ( - ('M', 'Male'), - ('F', 'Female'), - ) - gender = models.CharField(max_length=1, choices=GENDER_CHOICES) - -or outside your model class altogether:: - - GENDER_CHOICES = ( - ('M', 'Male'), - ('F', 'Female'), - ) - class Foo(models.Model): - gender = models.CharField(max_length=1, choices=GENDER_CHOICES) - -You can also collect your available choices into named groups that can -be used for organizational purposes:: - - MEDIA_CHOICES = ( - ('Audio', ( - ('vinyl', 'Vinyl'), - ('cd', 'CD'), - ) - ), - ('Video', ( - ('vhs', 'VHS Tape'), - ('dvd', 'DVD'), - ) - ), - ('unknown', 'Unknown'), - ) - -The first element in each tuple is the name to apply to the group. The -second element is an iterable of 2-tuples, with each 2-tuple containing -a value and a human-readable name for an option. Grouped options may be -combined with ungrouped options within a single list (such as the -`unknown` option in this example). - -For each model field that has :attr:`~Field.choices` set, Django will add a -method to retrieve the human-readable name for the field's current value. See -:meth:`~django.db.models.Model.get_FOO_display` in the database API -documentation. - -Finally, note that choices can be any iterable object -- not necessarily a list -or tuple. This lets you construct choices dynamically. But if you find yourself -hacking :attr:`~Field.choices` to be dynamic, you're probably better off using a -proper database table with a :class:`ForeignKey`. :attr:`~Field.choices` is -meant for static data that doesn't change much, if ever. - -``db_column`` -------------- - -.. attribute:: Field.db_column - -The name of the database column to use for this field. If this isn't given, -Django will use the field's name. - -If your database column name is an SQL reserved word, or contains -characters that aren't allowed in Python variable names -- notably, the -hyphen -- that's OK. Django quotes column and table names behind the -scenes. - -``db_index`` ------------- - -.. attribute:: Field.db_index - -If ``True``, djadmin:`django-admin.py sqlindexes ` will output a -``CREATE INDEX`` statement for this field. - -``db_tablespace`` ------------------ - -.. attribute:: Field.db_tablespace - -.. versionadded:: 1.0 - -The name of the database tablespace to use for this field's index, if this field -is indexed. The default is the project's :setting:`DEFAULT_INDEX_TABLESPACE` -setting, if set, or the :attr:`~Field.db_tablespace` of the model, if any. If -the backend doesn't support tablespaces, this option is ignored. - -``default`` ------------ - -.. attribute:: Field.default - -The default value for the field. This can be a value or a callable object. If -callable it will be called every time a new object is created. - -``editable`` ------------- - -.. attribute:: Field.editable - -If ``False``, the field will not be editable in the admin or via forms -automatically generated from the model class. Default is ``True``. - -``error_messages`` ------------------- - -.. versionadded:: 1.2 - -.. attribute:: Field.error_messages - -The ``error_messages`` argument lets you override the default messages that the -field will raise. Pass in a dictionary with keys matching the error messages you -want to override. - -``help_text`` -------------- - -.. attribute:: Field.help_text - -Extra "help" text to be displayed under the field on the object's admin form. -It's useful for documentation even if your object doesn't have an admin form. - -Note that this value is *not* HTML-escaped when it's displayed in the admin -interface. This lets you include HTML in :attr:`~Field.help_text` if you so -desire. For example:: - - help_text="Please use the following format: YYYY-MM-DD." - -Alternatively you can use plain text and -``django.utils.html.escape()`` to escape any HTML special characters. - -``primary_key`` ---------------- - -.. attribute:: Field.primary_key - -If ``True``, this field is the primary key for the model. - -If you don't specify ``primary_key=True`` for any fields in your model, Django -will automatically add an :class:`IntegerField` to hold the primary key, so you -don't need to set ``primary_key=True`` on any of your fields unless you want to -override the default primary-key behavior. For more, see -:ref:`automatic-primary-key-fields`. - -``primary_key=True`` implies :attr:`null=False ` and :attr:`unique=True `. -Only one primary key is allowed on an object. - -``unique`` ----------- - -.. attribute:: Field.unique - -If ``True``, this field must be unique throughout the table. - -This is enforced at the database level and at the Django admin-form level. If -you try to save a model with a duplicate value in a :attr:`~Field.unique` -field, a :exc:`django.db.IntegrityError` will be raised by the model's -:meth:`~django.db.models.Model.save` method. - -This option is valid on all field types except :class:`ManyToManyField` and -:class:`FileField`. - -``unique_for_date`` -------------------- - -.. attribute:: Field.unique_for_date - -Set this to the name of a :class:`DateField` or :class:`DateTimeField` to -require that this field be unique for the value of the date field. - -For example, if you have a field ``title`` that has -``unique_for_date="pub_date"``, then Django wouldn't allow the entry of two -records with the same ``title`` and ``pub_date``. - -This is enforced at the Django admin-form level but not at the database level. - -``unique_for_month`` --------------------- - -.. attribute:: Field.unique_for_month - -Like :attr:`~Field.unique_for_date`, but requires the field to be unique with -respect to the month. - -``unique_for_year`` -------------------- - -.. attribute:: Field.unique_for_year - -Like :attr:`~Field.unique_for_date` and :attr:`~Field.unique_for_month`. - -``verbose_name`` -------------------- - -.. attribute:: Field.verbose_name - -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 `. - -``validators`` -------------------- - -.. versionadded:: 1.2 - -.. attribute:: Field.validators - -A list of validators to run for this field.See the :doc:`validators -documentation ` for more information. - -.. _model-field-types: - -Field types -=========== - -.. currentmodule:: django.db.models - -``AutoField`` -------------- - -.. class:: AutoField(**options) - -An :class:`IntegerField` that automatically increments -according to available IDs. You usually won't need to use this directly; a -primary key field will automatically be added to your model if you don't specify -otherwise. See :ref:`automatic-primary-key-fields`. - -``BigIntegerField`` -------------------- - -.. versionadded:: 1.2 - -.. class:: BigIntegerField([**options]) - -A 64 bit integer, much like an :class:`IntegerField` except that it is -guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The -admin represents this as an ```` (a single-line input). - - -``BooleanField`` ----------------- - -.. class:: BooleanField(**options) - -A true/false field. - -The admin represents this as a checkbox. - -.. versionchanged:: 1.2 - - In previous versions of Django when running under MySQL ``BooleanFields`` - would return their data as ``ints``, instead of true ``bools``. See the - release notes for a complete description of the change. - -``CharField`` -------------- - -.. class:: CharField(max_length=None, [**options]) - -A string field, for small- to large-sized strings. - -For large amounts of text, use :class:`~django.db.models.TextField`. - -The admin represents this as an ```` (a single-line input). - -:class:`CharField` has one extra required argument: - -.. attribute:: CharField.max_length - - The maximum length (in characters) of the field. The max_length is enforced - at the database level and in Django's validation. - -.. note:: - - 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 :doc:`database backend - notes ` for details. - -.. admonition:: MySQL users - - If you are using this field with MySQLdb 1.2.2 and the ``utf8_bin`` - collation (which is *not* the default), there are some issues to be aware - of. Refer to the :ref:`MySQL database notes ` for - details. - - -``CommaSeparatedIntegerField`` ------------------------------- - -.. class:: CommaSeparatedIntegerField(max_length=None, [**options]) - -A field of integers separated by commas. As in :class:`CharField`, the -:attr:`~CharField.max_length` argument is required and the note about database -portability mentioned there should be heeded. - -``DateField`` -------------- - -.. class:: DateField([auto_now=False, auto_now_add=False, **options]) - -A date, represented in Python by a ``datetime.date`` instance. Has a few extra, -optional arguments: - -.. attribute:: DateField.auto_now - - Automatically set the field to now every time the object is saved. Useful - for "last-modified" timestamps. Note that the current date is *always* - used; it's not just a default value that you can override. - -.. attribute:: DateField.auto_now_add - - Automatically set the field to now when the object is first created. Useful - for creation of timestamps. Note that the current date is *always* used; - it's not just a default value that you can override. - -The admin represents this as an ```` with a JavaScript -calendar, and a shortcut for "Today". The JavaScript calendar will always -start the week on a Sunday. - -.. note:: - As currently implemented, setting ``auto_now`` or ``auto_add_now`` to - ``True`` will cause the field to have ``editable=False`` and ``blank=True`` - set. - -``DateTimeField`` ------------------ - -.. class:: DateTimeField([auto_now=False, auto_now_add=False, **options]) - -A date and time, represented in Python by a ``datetime.datetime`` instance. -Takes the same extra arguments as :class:`DateField`. - -The admin represents this as two ```` fields, with -JavaScript shortcuts. - -``DecimalField`` ----------------- - -.. versionadded:: 1.0 - -.. class:: DecimalField(max_digits=None, decimal_places=None, [**options]) - -A fixed-precision decimal number, represented in Python by a -:class:`~decimal.Decimal` instance. Has two **required** arguments: - -.. attribute:: DecimalField.max_digits - - The maximum number of digits allowed in the number - -.. attribute:: DecimalField.decimal_places - - The number of decimal places to store with the number - -For example, to store numbers up to 999 with a resolution of 2 decimal places, -you'd use:: - - models.DecimalField(..., max_digits=5, decimal_places=2) - -And to store numbers up to approximately one billion with a resolution of 10 -decimal places:: - - models.DecimalField(..., max_digits=19, decimal_places=10) - -The admin represents this as an ```` (a single-line input). - -``EmailField`` --------------- - -.. class:: EmailField([max_length=75, **options]) - -A :class:`CharField` that checks that the value is a valid e-mail address. - -``FileField`` -------------- - -.. class:: FileField(upload_to=None, [max_length=100, **options]) - -A file-upload field. - -.. note:: - The ``primary_key`` and ``unique`` arguments are not supported, and will - raise a ``TypeError`` if used. - -Has one **required** argument: - -.. attribute:: FileField.upload_to - - A local filesystem path that will be appended to your :setting:`MEDIA_ROOT` - setting to determine the value of the :attr:`~django.core.files.File.url` - attribute. - - This path may contain `strftime formatting`_, which will be replaced by the - date/time of the file upload (so that uploaded files don't fill up the given - directory). - - .. versionchanged:: 1.0 - - This may also be a callable, such as a function, which will be called to - obtain the upload path, including the filename. This callable must be able - to accept two arguments, and return a Unix-style path (with forward slashes) - to be passed along to the storage system. The two arguments that will be - passed are: - - ====================== =============================================== - Argument Description - ====================== =============================================== - ``instance`` An instance of the model where the - ``FileField`` is defined. More specifically, - this is the particular instance where the - current file is being attached. - - In most cases, this object will not have been - saved to the database yet, so if it uses the - default ``AutoField``, *it might not yet have a - value for its primary key field*. - - ``filename`` The filename that was originally given to the - file. This may or may not be taken into account - when determining the final destination path. - ====================== =============================================== - -Also has one optional argument: - -.. attribute:: FileField.storage - - .. versionadded:: 1.0 - - Optional. A storage object, which handles the storage and retrieval of your - files. See :doc:`/topics/files` for details on how to provide this object. - -The admin represents this field as an ```` (a file-upload -widget). - -Using a :class:`FileField` or an :class:`ImageField` (see below) in a model -takes a few steps: - - 1. In your settings file, you'll need to define :setting:`MEDIA_ROOT` as the - full path to a directory where you'd like Django to store uploaded files. - (For performance, these files are not stored in the database.) Define - :setting:`MEDIA_URL` as the base public URL of that directory. Make sure - that this directory is writable by the Web server's user account. - - 2. Add the :class:`FileField` or :class:`ImageField` to your model, making - sure to define the :attr:`~FileField.upload_to` option to tell Django - to which subdirectory of :setting:`MEDIA_ROOT` it should upload files. - - 3. All that will be stored in your database is a path to the file - (relative to :setting:`MEDIA_ROOT`). You'll most likely want to use the - convenience :attr:`~django.core.files.File.url` function provided by - Django. For example, if your :class:`ImageField` is called ``mug_shot``, - you can get the absolute path to your image in a template with - ``{{ object.mug_shot.url }}``. - -For example, say your :setting:`MEDIA_ROOT` is set to ``'/home/media'``, and -:attr:`~FileField.upload_to` is set to ``'photos/%Y/%m/%d'``. The ``'%Y/%m/%d'`` -part of :attr:`~FileField.upload_to` is `strftime formatting`_; ``'%Y'`` is the -four-digit year, ``'%m'`` is the two-digit month and ``'%d'`` is the two-digit -day. If you upload a file on Jan. 15, 2007, it will be saved in the directory -``/home/media/photos/2007/01/15``. - -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 :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 -security holes. *Validate all uploaded files* so that you're sure the files are -what you think they are. For example, if you blindly let somebody upload files, -without validation, to a directory that's within your Web server's document -root, then somebody could upload a CGI or PHP script and execute that script by -visiting its URL on your site. Don't allow that. - -.. versionadded:: 1.0 - The ``max_length`` argument was added in this version. - -By default, :class:`FileField` instances are -created as ``varchar(100)`` columns in your database. As with other fields, you -can change the maximum length using the :attr:`~CharField.max_length` argument. - -.. _`strftime formatting`: http://docs.python.org/library/time.html#time.strftime - -FileField and FieldFile -~~~~~~~~~~~~~~~~~~~~~~~ - -When you access a :class:`FileField` on a model, you are given an instance -of :class:`FieldFile` as a proxy for accessing the underlying file. This -class has several methods that can be used to interact with file data: - -.. method:: FieldFile.open(mode='rb') - -Behaves like the standard Python ``open()`` method and opens the file -associated with this instance in the mode specified by ``mode``. - -.. method:: FieldFile.close() - -Behaves like the standard Python ``file.close()`` method and closes the file -associated with this instance. - -.. method:: FieldFile.save(name, content, save=True) - -This method takes a filename and file contents and passes them to the storage -class for the field, then associates the stored file with the model field. -If you want to manually associate file data with :class:`FileField` -instances on your model, the ``save()`` method is used to persist that file -data. - -Takes two required arguments: ``name`` which is the name of the file, and -``content`` which is a file-like object containing the file's contents. The -optional ``save`` argument controls whether or not the instance is saved after -the file has been altered. Defaults to ``True``. - -.. method:: FieldFile.delete(save=True) - -Deletes the file associated with this instance and clears all attributes on -the field. Note: This method will close the file if it happens to be open when -``delete()`` is called. - -The optional ``save`` argument controls whether or not the instance is saved -after the file has been deleted. Defaults to ``True``. - -``FilePathField`` ------------------ - -.. class:: FilePathField(path=None, [match=None, recursive=False, max_length=100, **options]) - -A :class:`CharField` whose choices are limited to the filenames in a certain -directory on the filesystem. Has three special arguments, of which the first is -**required**: - -.. attribute:: FilePathField.path - - Required. The absolute filesystem path to a directory from which this - :class:`FilePathField` should get its choices. Example: ``"/home/images"``. - -.. attribute:: FilePathField.match - - Optional. A regular expression, as a string, that :class:`FilePathField` - will use to filter filenames. Note that the regex will be applied to the - base filename, not the full path. Example: ``"foo.*\.txt$"``, which will - match a file called ``foo23.txt`` but not ``bar.txt`` or ``foo23.gif``. - -.. attribute:: FilePathField.recursive - - Optional. Either ``True`` or ``False``. Default is ``False``. Specifies - whether all subdirectories of :attr:`~FilePathField.path` should be included - -Of course, these arguments can be used together. - -The one potential gotcha is that :attr:`~FilePathField.match` applies to the -base filename, not the full path. So, this example:: - - FilePathField(path="/home/images", match="foo.*", recursive=True) - -...will match ``/home/images/foo.gif`` but not ``/home/images/foo/bar.gif`` -because the :attr:`~FilePathField.match` applies to the base filename -(``foo.gif`` and ``bar.gif``). - -.. versionadded:: 1.0 - The ``max_length`` argument was added in this version. - -By default, :class:`FilePathField` instances are -created as ``varchar(100)`` columns in your database. As with other fields, you -can change the maximum length using the :attr:`~CharField.max_length` argument. - -``FloatField`` --------------- - -.. class:: FloatField([**options]) - -.. versionchanged:: 1.0 - -A floating-point number represented in Python by a ``float`` instance. - -The admin represents this as an ```` (a single-line input). - -``ImageField`` --------------- - -.. class:: ImageField(upload_to=None, [height_field=None, width_field=None, max_length=100, **options]) - -Inherits all attributes and methods from :class:`FileField`, but also -validates that the uploaded object is a valid image. - -In addition to the special attributes that are available for :class:`FileField`, -an :class:`ImageField` also has :attr:`~django.core.files.File.height` and -:attr:`~django.core.files.File.width` attributes. - -To facilitate querying on those attributes, :class:`ImageField` has two extra -optional arguments: - -.. attribute:: ImageField.height_field - - Name of a model field which will be auto-populated with the height of the - image each time the model instance is saved. - -.. attribute:: ImageField.width_field - - Name of a model field which will be auto-populated with the width of the - image each time the model instance is saved. - -Requires the `Python Imaging Library`_. - -.. _Python Imaging Library: http://www.pythonware.com/products/pil/ - -.. versionadded:: 1.0 - The ``max_length`` argument was added in this version. - -By default, :class:`ImageField` instances are created as ``varchar(100)`` -columns in your database. As with other fields, you can change the maximum -length using the :attr:`~CharField.max_length` argument. - -``IntegerField`` ----------------- - -.. class:: IntegerField([**options]) - -An integer. The admin represents this as an ```` (a -single-line input). - -``IPAddressField`` ------------------- - -.. class:: IPAddressField([**options]) - -An IP address, in string format (e.g. "192.0.2.30"). The admin represents this -as an ```` (a single-line input). - -``NullBooleanField`` --------------------- - -.. class:: NullBooleanField([**options]) - -Like a :class:`BooleanField`, but allows ``NULL`` as one of the options. Use -this instead of a :class:`BooleanField` with ``null=True``. The admin represents -this as a ``