Formalize, refactor, and document Model._meta

[Massimiliano]

When creating a view template for a Model instance, it is often useful to display the fields in the same order as they were defined.

The Model._meta has many useful tools when you are in such a situation, for example Model._meta.fields, but they are undocumented.

So documentation should be added to ​http://docs.djangoproject.com/en/1.1/ref/models/options/

[James Bennett]

This is still considered internal API and subject to change; documenting it would commit us to a stability and backwards-compatibility guarantee I don't think we can make at the moment.

[Russell Keith-Magee]

@ubernostrum - Jacob and I spoke briefly about this the other day, in the context of database routers. Although we didn't come to a final decision, I think it is inevitable that we will have to formally document at least parts of _meta. In particular, there are some really ancient parts like app_label and get_field() that haven't changed, even since pre-magic removal, aren't really like to change in the future, and if they did change, would break so much code in the wild that it would be a backwards incompatibility in practice, if not in name.

I'll mark this someday/maybe since it is on the plan; if someone gets really enthused, we might be able to make a first cut for 1.2.

[Russell Keith-Magee]

Deferring; if nobody has made a start on this, it won't get done for 1.2.

[Adam Vandenberg]

Initial doc patch; needs review.

Developed after #14841.

[Adam Vandenberg]

Er, disregard the cross-link bug in that last post.

[Adam Vandenberg]

Developed this patch after this one: #14842

[Adam Vandenberg]

Now that r15110 landed, I'll be redoing this commit to be clean against those changes.

[Russell Keith-Magee]

@timo - it's great that you're taking a look at this ticket, but it can't happen for 1.3. This is an unusal case where it's not just a matter of documentation. When we document something, it becomes stable API. *Most* of the contents of _meta is *effectively* stable API, but we need to have a discussion about which parts of _meta should be stable, which parts should be private, and which parts should be cleaned up (and there are more than a few of those bits).

If you want to tackle this as a 1.4 task (including driving the relevant discussion on django-dev), that would be awesome; but I don't see it happening for 1.3.

[Tim Graham]

Thanks for the response Russ -- figured I might get some pushback on this at this point.

[Aymeric Augustin]

Change UI/UX from NULL to False.

[Aymeric Augustin]

Change Easy pickings from NULL to False.

[pirosb3]

Hi!

I will pick this up as SoC 2014, where I will be refactoring Meta: ​https://docs.google.com/document/d/1yp2_skqkxyrc0egdRv6ofnRGCI9nmvxDFBkCXgy0Jwo/edit#

For anything, ping me on #django-dev or on the Google Groups

[Tim Graham <timograham@…>]

In d862fae5bbfb52ab7aeaad5a59b3d8b27b30c8f9:

Refs #12663 -- Added tests for methods in db.models.options.

Thanks Russell Keith-Magee and Tim Graham for reviews.

[Tim Graham]

​Latest Pull Request

[Tim Graham <timograham@…>]

In fb48eb05816b1ac87d58696cdfe48be18c901f16:

Fixed #12663 -- Formalized the Model._meta API for retrieving fields.

Thanks to Russell Keith-Magee for mentoring this Google Summer of
Code 2014 project and everyone else who helped with the patch!

[Collin Anderson]

I found a regression: #24146

[Tim Graham <timograham@…>]

In c64dd64:

Refs #12663 -- Removed deprecated Model._meta methods.

[GitHub <noreply@…>]

In dd367e0d:

Refs #12663 -- Removed Meta API upgrade guide.

[Tim Graham <timograham@…>]

In 218a485b:

Refs #12663 -- Fixed reference to nonexistent field in model_fields tests.