Fixed #122 -- BIG, BACKWARDS-INCOMPATIBLE CHANGE. Changed model syntax to use fieldname=FieldClass() syntax. See ModelSyntaxChangeInstructions for important information on how to change your models

git-svn-id: http://code.djangoproject.com/svn/django/trunk@549 bcc190cf-cafb-0310-a4f2-bffc1f526a37

7 files changed, 105 insertions, 162 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 40fe40a64d..3d9cc9b9c5 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -11,20 +11,16 @@ models, and how to create, retrieve, and update objects.
 Throughout this reference, we'll refer to the following Poll application::
 
     class Poll(meta.Model):
-        fields = (
-            meta.SlugField('slug', unique_for_month='pub_date'),
-            meta.CharField('question', maxlength=255),
-            meta.DateTimeField('pub_date'),
-            meta.DateTimeField('expire_date'),
-        )
+        slug = meta.SlugField(unique_for_month='pub_date')
+        question = meta.CharField(maxlength=255)
+        pub_date = meta.DateTimeField()
+        expire_date = meta.DateTimeField()
 
     class Choice(meta.Model):
-        fields = (
-            meta.ForeignKey(Poll, edit_inline=meta.TABULAR,
-                num_in_admin=10, min_num_in_admin=5),
-            meta.CharField('choice', maxlength=255, core=True),
-            meta.IntegerField('votes', editable=False, default=0),
-        )
+        poll = meta.ForeignKey(Poll, edit_inline=meta.TABULAR,
+            num_in_admin=10, min_num_in_admin=5)
+        choice = meta.CharField(maxlength=255, core=True)
+        votes = meta.IntegerField(editable=False, default=0)
 
 Basic lookup functions
 ======================
@@ -163,23 +159,18 @@ automatically.
 One-to-one relations
 --------------------
 
-Each object in a one-to-one relationship will have a ``get_relatedobject()``
+Each object in a one-to-one relationship will have a ``get_relatedobjectname()``
 method. For example::
 
     class Place(meta.Model):
-        fields = (
-            ...
-        )
+        # ...
 
     class Restaurant(meta.Model):
-        ...
-        fields = (
-            meta.OneToOneField(places.Place),
-            ...
-        )
+        # ...
+        the_place = meta.OneToOneField(places.Place)
 
 In the above example, each ``Place`` will have a ``get_restaurant()`` method,
-and each ``Restaurant`` will have a ``get_place()`` method.
+and each ``Restaurant`` will have a ``get_theplace()`` method.
 
 Many-to-one relations
 ---------------------
@@ -236,19 +227,15 @@ Note that ``select_related`` follows foreign keys as far as possible. If you hav
 following models::
 
     class Poll(meta.Model):
-        ...
+        # ...
 
     class Choice(meta.Model):
-        fields = (
-            meta.ForeignKey(Poll),
-            ...
-        )
+        # ...
+        poll = meta.ForeignKey(Poll)
 
     class SingleVote(meta.Model):
-        fields = (
-            meta.ForeignKey(Choice),
-            ...
-        )
+        # ...
+        choice = meta.ForeignKey(Choice)
 
 then a call to ``singlevotes.get_object(id__exact=4, select_related=True)`` will
 cache the related choice *and* the related poll::
diff --git a/docs/faq.txt b/docs/faq.txt
index d5400dd98c..e1f909cea3 100644
--- a/docs/faq.txt
+++ b/docs/faq.txt
@@ -291,14 +291,9 @@ dictionaries in order of query execution. Each dictionary has the following::
 Can I use Django with a pre-existing database?
 ----------------------------------------------
 
-Yes. You have two options:
+Yes. See `Integrating with a legacy database`_.
 
-    * Write models that describe your already-existing database layout, and
-      just point Django at your database.
-    * Use the alpha ``django-admin.py inspectdb`` function to automatically
-      create models by introspecting a given database. See `Ticket 90`_.
-
-.. _`Ticket 90`: http://code.djangoproject.com/ticket/90
+.. _`Integrating with a legacy database`: http://www.djangoproject.com/documentation/legacy_databases/
 
 The admin site
 ==============
diff --git a/docs/forms.txt b/docs/forms.txt
index 5e2ddcdeed..e3a98feb32 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -26,14 +26,14 @@ this document, we'll be working with the following model, a "place" object::
     )
 
     class Place(meta.Model):
-        fields = (
-            meta.CharField('name', maxlength=100),
-            meta.CharField('address', maxlength=100, blank=True),
-            meta.CharField('city', maxlength=50, blank=True),
-            meta.USStateField('state'),
-            meta.CharField('zip_code', maxlength=5, blank=True),
-            meta.IntegerField('place_type', choices=PLACE_TYPES)
-        )
+        name = meta.CharField(maxlength=100),
+        address = meta.CharField(maxlength=100, blank=True),
+        city = meta.CharField(maxlength=50, blank=True),
+        state = meta.USStateField(),
+        zip_code = meta.CharField(maxlength=5, blank=True),
+        place_type = meta.IntegerField(choices=PLACE_TYPES)
+        class META:
+            admin = meta.Admin()
 
         def __repr__(self):
             return self.name
diff --git a/docs/model-api.txt b/docs/model-api.txt
index 02d7d7a509..bbe38929bf 100644
--- a/docs/model-api.txt
+++ b/docs/model-api.txt
@@ -6,15 +6,24 @@ Django's models are the bread and butter of the framework.  There's a huge
 array of options available to you when defining your data models. This
 document explains them.
 
-Options for models
-==================
+META options
+============
 
-A list of all possible options for a model object follows. Although there's a
-wide array of options, only ``fields`` is required.
+Give your model metadata by using an inner ``"class META"``, like so::
+
+    class Foo(meta.Model):
+        bar = meta.CharField(maxlength=30)
+        # ...
+        class META:
+            admin = meta.Admin()
+            # ...
+
+Here's a list of all possible ``META`` options. No options are required.
 
 ``admin``
-    A ``meta.Admin`` object; see `Admin options`_.  If this field isn't given,
-    the object will not have an admin interface.
+    A ``meta.Admin`` object; see `Admin options`_. If this field is given, the
+    object will have an admin interface. If it isn't given, the object won't
+    have one.
 
 ``db_table``
     The name of the database table to use for the module::
@@ -30,16 +39,6 @@ wide array of options, only ``fields`` is required.
 
         exceptions = ("DisgustingToppingsException", "BurntCrust")
 
-``fields``
-    A list of field objects. See `Field objects`_. For example::
-
-        fields = (
-            meta.CharField('customer_name', maxlength=15),
-            meta.BooleanField('use_extra_cheese'),
-            meta.IntegerField('customer_type', choices=CUSTOMER_TYPE_CHOICES),
-            ...
-        )
-
 ``get_latest_by``
     The name of a ``DateField`` or ``DateTimeField``; if given, the module will
     have a ``get_latest()`` function that fetches the "latest" object according
@@ -69,7 +68,7 @@ wide array of options, only ``fields`` is required.
     respect to a parent object.  For example, if a ``PizzaToppping`` relates to
     a ``Pizza`` object, you might use::
 
-        order_with_respect_to = 'pizza_id'
+        order_with_respect_to = 'pizza'
 
     to allow the toppings to be ordered with respect to the associated pizza.
 
@@ -95,7 +94,7 @@ wide array of options, only ``fields`` is required.
 ``unique_together``
     Sets of field names that, taken together, must be unique::
 
-        unique_together = (("driver_id", "restaurant_id"),)
+        unique_together = (("driver", "restaurant"),)
 
     This is a list of lists of fields that must be unique when considered
     together. It's used in the Django admin.
@@ -118,18 +117,14 @@ wide array of options, only ``fields`` is required.
 Field objects
 =============
 
-The list of fields is the most important part of a data model.  Each item in
-the ``fields`` list is an instance of a ``meta.Field`` subclass and maps to
-a database field.
-
-All field objects -- except for ``ForeignKey`` and ``ManyToManyField`` (see
-below) -- require the field's machine-readable name as the first positional
-argument. This must be a valid Python identifier -- no spaces, punctuation,
-etc., are allowed.
+The list of fields is the most important part of a data model. Each class
+variable in a model, aside from the optional inner ``class META``, should be
+an instance of a ``meta.Field`` subclass.
 
-The second positional argument, a human-readable name, is optional. If the
-human-readable name isn't given, Django will use the machine-readable name,
-coverting underscores to spaces.
+Each field type, except for ``ForeignKey``, ``ManyToManyField`` and
+``OneToOneField``, takes an optional first positional argument, a
+human-readable name. If the human-readable name isn't given, Django will use
+the machine-readable name, converting underscores to spaces.
 
 General field options
 ---------------------
@@ -173,6 +168,10 @@ common to all field types. These arguments are:
                             It is an error to have an inline-editable
                             relation without at least one core 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.
+
     ``db_index``            If ``True``, the SQL generator will create a database
                             index on this field.
 
@@ -229,7 +228,7 @@ Field Types
     use this directly; a primary key field will automatically be added to your
     model if you don't specify otherwise. That automatically-added field is::
 
-        meta.AutoField('id', primary_key=True)
+        id = meta.AutoField(primary_key=True)
 
 ``BooleanField``
     A true/false field.
@@ -370,13 +369,6 @@ Field Types
 
                              Not used with ``edit_inline``.
 
-    ``rel_name``             The name of the relation. In the above example,
-                             this would default to 'pizza' (so that the
-                             ``Toppings`` object would have a ``get_pizza()``
-                             function. If you set ``rel_name`` to "pie", then
-                             the function would be called ``get_pie()`` and the
-                             field name would be ``pie_id``.
-
     ``related_name``         The name to use for the relation from the related
                              object back to this one.  For example, when if
                              ``Topping`` has this field::
@@ -405,11 +397,9 @@ Field Types
 
                                     ...
                                     meta.ForeignKey(Category, name="primary_category_id",
-                                                    rel_name="primary_category",
                                                     related_name="primary_story"),
 
                                     meta.ForeignKey(Category, name="secondary_category_id",
-                                                    rel_name="secondary_category",
                                                     related_name="secondary_story"),
                                     ...
 
@@ -445,24 +435,18 @@ Field Types
     ``core.flatfiles`` object::
 
         class FlatFile(meta.Model):
-            fields = (
-                ...
-                meta.ManyToManyField(Site),
-            )
+            # ...
+            sites = meta.ManyToManyField(Site)
 
     Many-to-many relations are a bit different from other fields.  First, they
     aren't actually a field per se, because they use a intermediary join table.
     Second, they don't take the same options as the rest of the fields. The
-    only arguments taken are:
+    first position argument is required and should be a model class. Other
+    available arguments, all of which are optional, are:
 
     =======================  ============================================================
     Argument                 Description
     =======================  ============================================================
-    ``rel_name``             Use this if you have more than one
-                             ``ForeignKey``  in the same model that relate
-                             to the same model. Django will use ``rel_name`` in
-                             the generated API.
-
     ``related_name``         See the description of ``related_name`` in
                              ``ForeignKey``, above.
 
@@ -475,14 +459,6 @@ Field Types
 
     ``limit_choices_to``     See the description under ``ForeignKey`` above.
 
-    ``name``                 An alphanumeric name for the relationship. If this
-                             isn't provided, Django uses the ``module_name`` of
-                             the related object.
-
-                             This is only really useful when you have a single
-                             object that relates to the same object more than
-                             once.
-
     ``verbose_name``         A human-readable name for the object, singular. If
                              this isn't provided, Django uses the
                              ``verbose_name`` for the related object.
@@ -534,7 +510,7 @@ Field Types
     from which to auto-populate the slug, via JavaScript, in the object's admin
     form::
 
-        meta.SlugField("slug", prepopulate_from=("pre_name", "name")),
+        meta.SlugField(prepopulate_from=("pre_name", "name")),
 
 ``SmallIntegerField``
     Like an ``IntegerField``, but only allows values under a certain
@@ -691,9 +667,7 @@ object's behavior.  First, any methods you define will be available as methods
 of object instances. For example::
 
     class Pizza(meta.Model):
-        fields = (
-            ...
-        )
+        # ...
 
         def is_disgusting(self):
             return "anchovies" in [topping.name for topping in self.get_topping_list()]
@@ -742,9 +716,7 @@ that module.  Any model method that begins with "_module_" is turned into a
 module-level function::
 
     class Pizza(meta.Model):
-        fields = (
-            ...
-        )
+        # ...
 
         def _module_get_pizzas_to_deliver():
             return get_list(delivered__exact=False)
@@ -769,9 +741,7 @@ fields because manipulators automatically call any method that begins with
 "validate"::
 
     class Pizza(meta.Model):
-        fields = (
-            ...
-        )
+        # ...
 
         def _manipulator_validate_customer_id(self, field_data, all_data):
             from django.core import validators
diff --git a/docs/overview.txt b/docs/overview.txt
index 6917ef8a1d..90e3db9302 100644
--- a/docs/overview.txt
+++ b/docs/overview.txt
@@ -21,20 +21,16 @@ offers many rich ways of representing your models -- so far, it's been
 solving two years' worth of database-schema problems. Here's a quick example::
 
     class Reporter(meta.Model):
-        fields = (
-            meta.CharField('full_name', maxlength=70),
-        )
+        full_name = meta.CharField(maxlength=70)
 
         def __repr__(self):
             return self.full_name
 
     class Article(meta.Model):
-        fields = (
-            meta.DateTimeField('pub_date'),
-            meta.CharField('headline', maxlength=200),
-            meta.TextField('article'),
-            meta.ForeignKey(Reporter),
-        )
+        pub_date = meta.DateTimeField('pub_date')
+        headline = meta.CharField('headline', maxlength=200)
+        article = meta.TextField('article')
+        reporter = meta.ForeignKey(Reporter)
 
         def __repr__(self):
             return self.headline
@@ -134,17 +130,16 @@ A dynamic admin interface: It's not just scaffolding -- it's the whole house
 
 Once your models are defined, Django can automatically create an administrative
 interface -- a Web site that lets authenticated users add, change and
-delete objects. It's as easy as adding an extra admin attribute to your model
-classes::
+delete objects. It's as easy as adding an extra ``admin`` attribute to your
+model classes::
 
     class Article(meta.Model):
-        fields = (
-            meta.DateTimeField('pub_date'),
-            meta.CharField('headline', maxlength=200),
-            meta.TextField('article'),
-            meta.ForeignKey(Reporter),
-        )
-        admin = meta.Admin()
+        pub_date = meta.DateTimeField('pub_date')
+        headline = meta.CharField('headline', maxlength=200)
+        article = meta.TextField('article')
+        reporter = meta.ForeignKey(Reporter)
+        class META:
+            admin = meta.Admin()
 
 The philosophy here is that your site is edited by a staff, or a client, or
 maybe just you -- and you don't want to have to deal with creating backend
diff --git a/docs/tutorial01.txt b/docs/tutorial01.txt
index 112f5ca05c..6b4380290f 100644
--- a/docs/tutorial01.txt
+++ b/docs/tutorial01.txt
@@ -167,41 +167,36 @@ These concepts are represented by simple Python classes. Edit the
     from django.core import meta
 
     class Poll(meta.Model):
-        fields = (
-            meta.CharField('question', maxlength=200),
-            meta.DateTimeField('pub_date', 'date published'),
-        )
+        question = meta.CharField(maxlength=200)
+        pub_date = meta.DateTimeField('date published')
 
     class Choice(meta.Model):
-        fields = (
-            meta.ForeignKey(Poll),
-            meta.CharField('choice', maxlength=200),
-            meta.IntegerField('votes'),
-        )
+        poll = meta.ForeignKey(Poll)
+        choice = meta.CharField(maxlength=200)
+        votes = meta.IntegerField()
 
 The code is straightforward. Each model is represented by a class that
-subclasses ``django.core.meta.Model``. Each model has a single class variable,
-``fields``, which is a tuple of database fields in the model.
+subclasses ``django.core.meta.Model``. Each model a number of class variables,
+each of which represents a database field in the model.
 
 Each field is represented by an instance of a ``meta.*Field`` class -- e.g.,
 ``meta.CharField`` for character fields and ``meta.DateTimeField`` for
 datetimes. This tells Django what type of data each field holds.
 
-The first argument to each ``Field`` call is the field's name, in
-machine-friendly format. You'll use this value in your Python code, and your
-database will use it as the column name.
+The name of each ``meta.*Field`` instance (e.g. ``question`` or ``pub_date`` )
+is the field's name, in machine-friendly format. You'll use this value in your
+Python code, and your database will use it as the column name.
 
-The second, optional, argument is the field's human-readable name. That's used
-in a couple of introspective parts of Django, and it doubles as documentation.
-If this field isn't provided, Django will use the machine-readable name. In
-this example, we've only defined a human-readable name for ``Poll.pub_date``.
-For all other fields in this model, the field's machine-readable name will
-suffice as its human-readable name.
+You can use an optional first positional argument to a ``Field`` to designate a
+human-readable name. That's used in a couple of introspective parts of Django,
+and it doubles as documentation. If this field isn't provided, Django will use
+the machine-readable name. In this example, we've only defined a human-readable
+name for ``Poll.pub_date``. For all other fields in this model, the field's
+machine-readable name will suffice as its human-readable name.
 
-Some ``meta.*Field`` classes have additional required elements.
-``meta.CharField``, for example, requires that you give it a ``maxlength``.
-That's used not only in the database schema, but in validation, as we'll soon
-see.
+Some ``meta.*Field`` classes have required elements. ``meta.CharField``, for
+example, requires that you give it a ``maxlength``. That's used not only in the
+database schema, but in validation, as we'll soon see.
 
 Finally, note a relationship is defined, using ``meta.ForeignKey``. That tells
 Django each Choice is related to a single Poll. Django supports all the common
@@ -266,6 +261,9 @@ Note the following:
 
     * Primary keys (IDs) are added automatically. (You can override this, too.)
 
+    * Django appends ``"_id"`` to the foreign key field name, by convention.
+      Yes, you can override this, as well.
+
     * The foreign key relationship is made explicit by a ``REFERENCES`` statement.
 
     * It's tailored to the database you're using, so database-specific field types
diff --git a/docs/tutorial02.txt b/docs/tutorial02.txt
index b42bafb374..e1d0401592 100644
--- a/docs/tutorial02.txt
+++ b/docs/tutorial02.txt
@@ -89,9 +89,7 @@ objects have an admin interface. Edit the ``myproject/apps/polls/models/polls.py
 file and make the following change to add an ``admin`` attribute::
 
     class Poll(meta.Model):
-        fields = (
-            # ...
-        )
+        # ...
         admin = meta.Admin()
 
 Now reload the Django admin page to see your changes. Note that you don't have
@@ -242,15 +240,15 @@ Poll object. Let's make that happen.
 Remove the ``admin`` for the Choice model. Then, edit the ``ForeignKey(Poll)``
 field like so::
 
-    meta.ForeignKey(Poll, edit_inline=meta.STACKED, num_in_admin=3),
+    poll = meta.ForeignKey(Poll, edit_inline=meta.STACKED, num_in_admin=3)
 
 This tells Django: "Choice objects are edited on the Poll admin page. By
 default, provide enough fields for 3 Choices."
 
 Then change the other fields in ``Choice`` to give them ``core=True``::
 
-    meta.CharField('choice', 'choice', maxlength=200, core=True),
-    meta.IntegerField('votes', 'votes', core=True),
+    choice = meta.CharField(maxlength=200, core=True)
+    votes = meta.IntegerField(core=True)
 
 This tells Django: "When you edit a Choice on the Poll admin page, the 'choice'
 and 'votes' fields are required. The presence of at least one of them signifies
@@ -274,7 +272,7 @@ One small problem, though. It takes a lot of screen space to display all the
 fields for entering related Choice objects. For that reason, Django offers an
 alternate way of displaying inline related objects::
 
-    meta.ForeignKey(Poll, edit_inline=meta.TABULAR, num_in_admin=3),
+    poll = meta.ForeignKey(Poll, edit_inline=meta.TABULAR, num_in_admin=3)
 
 With that ``edit_inline=meta.TABULAR`` (instead of ``meta.STACKED``), the
 related objects are displayed in a more compact, table-based format: