#

## Django documentation

# 1. Bare-bones model

This is a basic model with only two non-primary-key fields.

## Model source code

    from django.core import meta

    class Article(meta.Model):
        headline = meta.CharField(maxlength=100, default='Default headline')
        pub_date = meta.DateTimeField()

## API reference

### Article objects have the following methods:

- `delete()`
- `get_next_by_pub_date()`
- `get_previous_by_pub_date()`
- `save()`

## Sample API usage

This sample code assumes the above model has been saved in a file `examplemodel.py`.

    >>> from django.models.examplemodel import articles

    # No articles are in the system yet.
    >>> articles.get_list()
    []

    # Create an Article.
    >>> from datetime import datetime
    >>> a = articles.Article(id=None, headline='Area man programs in Python',
    ...     pub_date=datetime(2005, 7, 28))

    # Save it into the database. You have to call save() explicitly.
    >>> a.save()

    # Now it has an ID. Note it's a long integer, as designated by the trailing "L".
    >>> a.id
    1L

    # Access database columns via Python attributes.
    >>> a.headline
    'Area man programs in Python'
    >>> a.pub_date
    datetime.datetime(2005, 7, 28, 0, 0)

    # Change values by changing the attributes, then calling save().
    >>> a.headline = 'Area woman programs in Python'
    >>> a.save()

    # get_list() displays all the articles in the database. Note that the article
    # is represented by "", because we haven't given the Article
    # model a __repr__() method.
    >>> articles.get_list()
    []

    # Django provides a rich database lookup API that's entirely driven by
    # keyword arguments.
    >>> articles.get_object(id__exact=1)

    >>> articles.get_object(headline__startswith='Area woman')

    >>> articles.get_object(pub_date__year=2005)

    >>> articles.get_object(pub_date__year=2005, pub_date__month=7)

    >>> articles.get_object(pub_date__year=2005, pub_date__month=7, pub_date__day=28)

    >>> articles.get_list(pub_date__year=2005)
    []
    >>> articles.get_list(pub_date__year=2004)
    []
    >>> articles.get_list(pub_date__year=2005, pub_date__month=7)
    []

    # Django raises an ArticleDoesNotExist exception for get_object()
    >>> articles.get_object(id__exact=2)
    Traceback (most recent call last):
        ...
    ArticleDoesNotExist: Article does not exist for {'id__exact': 2}

    >>> articles.get_object(pub_date__year=2005, pub_date__month=8)
    Traceback (most recent call last):
        ...
    ArticleDoesNotExist: Article does not exist for ...

    # Lookup by a primary key is the most common case, so Django provides a
    # shortcut for primary-key exact lookups.
    # The following is identical to articles.get_object(id__exact=1).
    >>> articles.get_object(pk=1)

    # Model instances of the same type and same ID are considered equal.
    >>> a = articles.get_object(pk=1)
    >>> b = articles.get_object(pk=1)
    >>> a == b
    True

    # You can initialize a model instance using positional arguments, which should
    # match the field order as defined in the model...
    >>> a2 = articles.Article(None, 'Second article', datetime(2005, 7, 29))
    >>> a2.save()
    >>> a2.id
    2L
    >>> a2.headline
    'Second article'
    >>> a2.pub_date
    datetime.datetime(2005, 7, 29, 0, 0)

    # ...or, you can use keyword arguments.
    >>> a3 = articles.Article(id=None, headline='Third article',
    ...    pub_date=datetime(2005, 7, 30))
    >>> a3.save()
    >>> a3.id
    3L
    >>> a3.headline
    'Third article'
    >>> a3.pub_date
    datetime.datetime(2005, 7, 30, 0, 0)

    # You can also mix and match position and keyword arguments, but be sure not to
    # duplicate field information.
    >>> a4 = articles.Article(None, 'Fourth article', pub_date=datetime(2005, 7, 31))
    >>> a4.save()
    >>> a4.headline
    'Fourth article'

    # Don't use invalid keyword arguments.
    >>> a5 = articles.Article(id=None, headline='Invalid', pub_date=datetime(2005, 7, 31), foo='bar')
    Traceback (most recent call last):
        ...
    TypeError: 'foo' is an invalid keyword argument for this function

    # You can leave off the ID.
    >>> a5 = articles.Article(headline='Article 6', pub_date=datetime(2005, 7, 31))
    >>> a5.save()
    >>> a5.id
    5L
    >>> a5.headline
    'Article 6'

    # If you leave off a field with "default" set, Django will use the default.
    >>> a6 = articles.Article(pub_date=datetime(2005, 7, 31))
    >>> a6.save()
    >>> a6.headline
    'Default headline'

    # For DateTimeFields, Django saves as much precision (in seconds) as you
    # give it.
    >>> a7 = articles.Article(headline='Article 7', pub_date=datetime(2005, 7, 31, 12, 30))
    >>> a7.save()
    >>> articles.get_object(id__exact=7).pub_date
    datetime.datetime(2005, 7, 31, 12, 30)

    >>> a8 = articles.Article(headline='Article 8', pub_date=datetime(2005, 7, 31, 12, 30, 45))
    >>> a8.save()
    >>> articles.get_object(id__exact=8).pub_date
    datetime.datetime(2005, 7, 31, 12, 30, 45)
    >>> a8.id
    8L

    # Saving an object again shouldn't create a new object -- it just saves the old one.
    >>> a8.save()
    >>> a8.id
    8L
    >>> a8.headline = 'Updated article 8'
    >>> a8.save()
    >>> a8.id
    8L

    # In PostgreSQL, microsecond-level precision is available.
    >>> a9 = articles.Article(headline='Article 9', pub_date=datetime(2005, 7, 31, 12, 30, 45, 180))
    >>> a9.save()
    >>> articles.get_object(id__exact=9).pub_date
    datetime.datetime(2005, 7, 31, 12, 30, 45, 180)

    # In MySQL, microsecond-level precision isn't available. You'll lose
    # microsecond-level precision once the data is saved.
    >>> a9 = articles.Article(headline='Article 9', pub_date=datetime(2005, 7, 31, 12, 30, 45, 180))
    >>> a9.save()
    >>> articles.get_object(id__exact=9).pub_date
    datetime.datetime(2005, 7, 31, 12, 30, 45)

## Comments

## Post a comment

Note: Please only use the comments for questions/critcisms/suggestions on the docs; if you experience errors please file a ticket, ask in the IRC channel, or post to the django-users list. Comments will be periodically reviewed, integrated into the documentation proper, and removed.

Your name:

Comment: