Django model manager objects.create where is the documentation?

Question

I always read that I should use

model = Model(a=5, b=6)
model.save()

But I just saw there is a manager function create, because I saw an opensource django app using it.

model = Model.objects.create(a=5, b=6)
print model.pk
1

So is it suggested to use it? Or is it still preferred to use the .save method. I'm guessing that objects.create will try to create it no matter what, whereas save may save an existing object if the pk is specified.

These are the docs that I found: https://docs.djangoproject.com/en/dev/topics/db/queries/#creating-objects

Answer 1

p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

equivalent to:

p = Person(first_name="Bruce", last_name="Springsteen") 
p.save(force_insert=True)

The force_insert means that a new object will always be created.
Normally you won’t need to worry about this. However, if your model contains a manual primary key value that you set and if that value already exists in the database, a call to create() will fail with an IntegrityError since primary keys must be unique. Be prepared to handle the exception if you are using manual primary keys.

Answer 2

It's in the page "QuerySet API reference", linked from the documentation index.

Answer 3

create essentially does the same. below is the source code for create.

def create(self, **kwargs):
    """
    Creates a new object with the given kwargs, saving it to the database
    and returning the created object.
    """
    obj = self.model(**kwargs)
    self._for_write = True
    obj.save(force_insert=True, using=self.db)
    return obj

it creates an instance and then saves it.