Changeset 5725

Timestamp:

07/20/07 01:28:56 (1 year ago)

Author:

adrian

Message:

Added a db_type() method to the database Field class. This is a hook for calculating the database column type for a given Field. Also converted all management.py CREATE TABLE statements to use db_type(), which made that code cleaner. The Field.get_internal_type() hook still exists, but we should consider removing it at some point, because db_type() is more general. Also added docs -- the beginnings of docs on how to create custom database Field classes. This is backwards-compatible.

Files:

• django/trunk/django/core/management.py (modified) (12 diffs)
• django/trunk/django/db/backends/ado_mssql/creation.py (modified) (1 diff)
• django/trunk/django/db/backends/mysql/creation.py (modified) (1 diff)
• django/trunk/django/db/backends/mysql_old/creation.py (modified) (1 diff)
• django/trunk/django/db/backends/oracle/creation.py (modified) (1 diff)
• django/trunk/django/db/backends/postgresql/creation.py (modified) (1 diff)
• django/trunk/django/db/backends/sqlite3/creation.py (modified) (1 diff)
• django/trunk/django/db/models/fields/__init__.py (modified) (2 diffs)
• django/trunk/django/db/models/fields/related.py (modified) (4 diffs)
• django/trunk/docs/model-api.txt (modified) (1 diff)

django/trunk/django/core/management.py

@@ -96 +96 @@
-    return sequence_list
-
-# If the foreign key points to an AutoField, a PositiveIntegerField or a
-# PositiveSmallIntegerField, the foreign key should be an IntegerField, not the
-# referred field type. Otherwise, the foreign key should be the same type of
-# field as the field to which it points.
-get_rel_data_type = lambda f: (f.get_internal_type() in ('AutoField', 'PositiveIntegerField', 'PositiveSmallIntegerField')) and 'IntegerField' or f.get_internal_type()
-
-def get_sql_create(app):
-    "Returns a list of the CREATE TABLE SQL statements for the given app."
-
-
-
-
-
+
+
+
+
-        # This must be the "dummy" database backend, which means the user
-        # hasn't set DATABASE_ENGINE.
@@ -160 +153 @@
-    Returns list_of_sql, pending_references_dict
-    """
-
-
+
-
-    opts = model._meta
@@ -168 +160 @@
-    pending_references = {}
-    for f in opts.fields:
-
-
-
-
-
-
-
-
-
+
-        tablespace = f.db_tablespace or opts.db_tablespace
-        if col_type is not None:
-            # Make the definition (e.g. 'foo VARCHAR(30)') for this field.
-            field_output = [style.SQL_FIELD(backend.quote_name(f.column)),
- % rel_field.__dict__
+
-            field_output.append(style.SQL_KEYWORD('%sNULL' % (not f.null and 'NOT ' or '')))
-            if f.unique and (not f.primary_key or backend.allows_unique_and_pk):
@@ -205 +189 @@
-    if opts.order_with_respect_to:
-        table_output.append(style.SQL_FIELD(backend.quote_name('_order')) + ' ' + \
-data_types['IntegerField']
+models.IntegerField().db_type()
-            style.SQL_KEYWORD('NULL'))
-    for field_constraints in opts.unique_together:
@@ -233 +217 @@
-    Get any ALTER TABLE statements to add constraints after the fact.
-    """
-, get_creation_module
+
-    from django.db.backends.util import truncate_name
-    data_types = get_creation_module().DATA_TYPES
-
-    final_output = []
@@ -258 +241 @@
-
-def _get_many_to_many_sql_for_model(model):
-get_creation_module
+models
-    from django.contrib.contenttypes import generic
-
-    data_types = get_creation_module().DATA_TYPES
-
-    opts = model._meta
@@ -276 +257 @@
-            table_output.append('    %s %s %s%s,' % \
-                (style.SQL_FIELD(backend.quote_name('id')),
-data_types['AutoField']
+models.AutoField(primary_key=True).db_type()
-                style.SQL_KEYWORD('NOT NULL PRIMARY KEY'),
-                tablespace_sql))
-            table_output.append('    %s %s %s %s (%s)%s,' % \
-                (style.SQL_FIELD(backend.quote_name(f.m2m_column_name())),
-data_types[get_rel_data_type(opts.pk)] % opts.pk.__dict__
+models.ForeignKey(model).db_type()
-                style.SQL_KEYWORD('NOT NULL REFERENCES'),
-                style.SQL_TABLE(backend.quote_name(opts.db_table)),
@@ -288 +269 @@
-            table_output.append('    %s %s %s %s (%s)%s,' % \
-                (style.SQL_FIELD(backend.quote_name(f.m2m_reverse_name())),
-data_types[get_rel_data_type(f.rel.to._meta.pk)] % f.rel.to._meta.pk.__dict__
+models.ForeignKey(f.rel.to).db_type()
-                style.SQL_KEYWORD('NOT NULL REFERENCES'),
-                style.SQL_TABLE(backend.quote_name(f.rel.to._meta.db_table)),
@@ -518 +499 @@
-def syncdb(verbosity=1, interactive=True):
-    "Creates the database tables for all apps in INSTALLED_APPS whose tables haven't already been created."
-, get_creation_module
+
-    from django.conf import settings
-
@@ -533 +514 @@
-        except ImportError:
-            pass
-
-    data_types = get_creation_module().DATA_TYPES
-
-    cursor = connection.cursor()
@@ -1267 +1246 @@
-def createcachetable(tablename):
-    "Creates the table needed to use the SQL cache backend"
-
-
+
-    fields = (
-        # "key" is a reserved word in MySQL, so use "cache_key" instead.
@@ -1278 +1256 @@
-    index_output = []
-    for f in fields:
-data_types[f.get_internal_type()] % f.__dict__
+f.db_type()
-        field_output.append("%sNULL" % (not f.null and "NOT " or ""))
-        if f.unique:

django/trunk/django/db/backends/ado_mssql/creation.py

@@ -13 +13 @@
-    'IntegerField':      'int',
-    'IPAddressField':    'char(15)',
-    'ManyToManyField':   None,
-    'NullBooleanField':  'bit',
-    'OneToOneField':     'int',

django/trunk/django/db/backends/mysql/creation.py

@@ -17 +17 @@
-    'IntegerField':      'integer',
-    'IPAddressField':    'char(15)',
-    'ManyToManyField':   None,
-    'NullBooleanField':  'bool',
-    'OneToOneField':     'integer',

django/trunk/django/db/backends/mysql_old/creation.py

@@ -17 +17 @@
-    'IntegerField':      'integer',
-    'IPAddressField':    'char(15)',
-    'ManyToManyField':   None,
-    'NullBooleanField':  'bool',
-    'OneToOneField':     'integer',

django/trunk/django/db/backends/oracle/creation.py

@@ -20 +20 @@
-    'IntegerField':                 'NUMBER(11)',
-    'IPAddressField':               'VARCHAR2(15)',
-    'ManyToManyField':              None,
-    'NullBooleanField':             'NUMBER(1) CHECK ((%(column)s IN (0,1)) OR (%(column)s IS NULL))',
-    'OneToOneField':                'NUMBER(11)',

django/trunk/django/db/backends/postgresql/creation.py

@@ -17 +17 @@
-    'IntegerField':      'integer',
-    'IPAddressField':    'inet',
-    'ManyToManyField':   None,
-    'NullBooleanField':  'boolean',
-    'OneToOneField':     'integer',

django/trunk/django/db/backends/sqlite3/creation.py

@@ -16 +16 @@
-    'IntegerField':                 'integer',
-    'IPAddressField':               'char(15)',
-    'ManyToManyField':              None,
-    'NullBooleanField':             'bool',
-    'OneToOneField':                'integer',

django/trunk/django/db/models/fields/__init__.py

@@ +1 @@
+from django.db import get_creation_module
-from django.db.models import signals
-from django.dispatch import dispatcher
@@ -118 +119 @@
-        return value
-
+    def db_type(self):
+        """
+        Returns the database column data type for this field, taking into
+        account the DATABASE_ENGINE setting.
+        """
+        # The default implementation of this method looks at the
+        # backend-specific DATA_TYPES dictionary, looking up the field by its
+        # "internal type".
+        #
+        # A Field class can implement the get_internal_type() method to specify
+        # which *preexisting* Django Field class it's most similar to -- i.e.,
+        # an XMLField is represented by a TEXT column type, which is the same
+        # as the TextField Django field type, which means XMLField's
+        # get_internal_type() returns 'TextField'.
+        #
+        # But the limitation of the get_internal_type() / DATA_TYPES approach
+        # is that it cannot handle database column types that aren't already
+        # mapped to one of the built-in Django field types. In this case, you
+        # can implement db_type() instead of get_internal_type() to specify
+        # exactly which wacky database column type you want to use.
+        data_types = get_creation_module().DATA_TYPES
+        internal_type = self.get_internal_type()
+        return data_types[internal_type] % self.__dict__
+
-    def validate_full(self, field_data, all_data):
-        """

django/trunk/django/db/models/fields/related.py

@@ -1 +1 @@
-from django.db import backend, transaction
-from django.db.models import signals, get_model
-
+PositiveIntegerField, PositiveSmallIntegerField, 
-from django.db.models.related import RelatedObject
-from django.utils.text import capfirst
@@ -557 +557 @@
-        return super(ForeignKey, self).formfield(**defaults)
-
+    def db_type(self):
+        # The database column type of a ForeignKey is the column type
+        # of the field to which it points. An exception is if the ForeignKey
+        # points to an AutoField/PositiveIntegerField/PositiveSmallIntegerField,
+        # in which case the column type is simply that of an IntegerField.
+        rel_field = self.rel.get_related_field()
+        if isinstance(rel_field, (AutoField, PositiveIntegerField, PositiveSmallIntegerField)):
+            return IntegerField().db_type()
+        return rel_field.db_type()
+
-class OneToOneField(RelatedField, IntegerField):
-    def __init__(self, to, to_field=None, **kwargs):
@@ -622 +632 @@
-        defaults.update(kwargs)
-        return super(OneToOneField, self).formfield(**defaults)
+
+    def db_type(self):
+        # The database column type of a OneToOneField is the column type
+        # of the field to which it points. An exception is if the OneToOneField
+        # points to an AutoField/PositiveIntegerField/PositiveSmallIntegerField,
+        # in which case the column type is simply that of an IntegerField.
+        rel_field = self.rel.get_related_field()
+        if isinstance(rel_field, (AutoField, PositiveIntegerField, PositiveSmallIntegerField)):
+            return IntegerField().db_type()
+        return rel_field.db_type()
-
-class ManyToManyField(RelatedField, Field):
@@ -745 +765 @@
-            defaults['initial'] = [i._get_pk_val() for i in defaults['initial']]
-        return super(ManyToManyField, self).formfield(**defaults)
+
+    def db_type(self):
+        # A ManyToManyField is not represented by a single column,
+        # so return None.
+        return None
-
-class ManyToOneRel(object):

django/trunk/docs/model-api.txt

@@ -981 +981 @@
-
-.. _One-to-one relationship model example: http://www.djangoproject.com/documentation/models/one_to_one/
+
+Custom field types
+------------------
+
+**New in Django development version**
+
+Django's built-in field types don't cover every possible database column type --
+only the common types, such as ``VARCHAR`` and ``INTEGER``. For more obscure
+column types, such as geographic polygons or even user-created types such as
+`PostgreSQL custom types`_, you can define your own Django ``Field`` subclasses.
+
+.. _PostgreSQL custom types: http://www.postgresql.org/docs/8.2/interactive/sql-createtype.html
+
+.. admonition:: Experimental territory
+
+    This is an area of Django that traditionally has not been documented, but
+    we're starting to include bits of documentation, one feature at a time.
+    Please forgive the sparseness of this section.
+
+    If you like living on the edge and are comfortable with the risk of
+    unstable, undocumented APIs, see the code for the core ``Field`` class
+    in ``django/db/models/fields/__init__.py`` -- but if/when the innards
+    change, don't say we didn't warn you.
+
+To create a custom field type, simply subclass ``django.db.models.Field``.
+Here is an incomplete list of the methods you should implement:
+
+``db_type()``
+~~~~~~~~~~~~~
+
+Returns the database column data type for the ``Field``, taking into account
+the current ``DATABASE_ENGINE`` setting.
+
+Say you've created a PostgreSQL custom type called ``mytype``. You can use this
+field with Django by subclassing ``Field`` and implementing the ``db_type()``
+method, like so::
+
+    from django.db import models
+
+    class MytypeField(models.Field):
+        def db_type(self):
+            return 'mytype'
+
+Once you have ``MytypeField``, you can use it in any model, just like any other
+``Field`` type::
+
+    class Person(models.Model):
+        name = models.CharField(maxlength=80)
+        gender = models.CharField(maxlength=1)
+        something_else = MytypeField()
+
+If you aim to build a database-agnostic application, you should account for
+differences in database column types. For example, the date/time column type
+in PostgreSQL is called ``timestamp``, while the same column in MySQL is called
+``datetime``. The simplest way to handle this in a ``db_type()`` method is to
+import the Django settings module and check the ``DATABASE_ENGINE`` setting.
+For example::
+
+    class MyDateField(models.Field):
+        def db_type(self):
+            from django.conf import settings
+            if settings.DATABASE_ENGINE == 'mysql':
+                return 'datetime'
+            else:
+                return 'timestamp'
+
+The ``db_type()`` method is only called by Django when the framework constructs
+the ``CREATE TABLE`` statements for your application -- that is, when you first
+create your tables. It's not called at any other time, so it can afford to
+execute slightly complex code, such as the ``DATABASE_ENGINE`` check in the
+above example.
-
-Meta options