Opened 14 years ago

Closed 9 years ago

Last modified 5 years ago

#12663 closed New feature (fixed)

Formalize, refactor, and document Model._meta

Reported by: Massimiliano Owned by: pirosb3
Component: Database layer (models, ORM) Version: dev
Severity: Normal Keywords: 1.8-alpha
Cc: unai@…, pirosb3, cmawebsite@… Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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/

Attachments (1)

document-meta.diff (2.6 KB ) - added by Adam Vandenberg 13 years ago.

Download all attachments as: .zip

Change History (28)

comment:1 by James Bennett, 14 years ago

Resolution: wontfix
Status: newclosed

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.

comment:2 by Russell Keith-Magee, 14 years ago

Resolution: wontfix
Status: closedreopened
Triage Stage: UnreviewedSomeday/Maybe

@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.

comment:3 by Russell Keith-Magee, 14 years ago

milestone: 1.2

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

comment:4 by Adam Vandenberg, 13 years ago

Needs documentation: set
Owner: changed from nobody to Adam Vandenberg
Status: reopenednew
Version: 1.2-alphaSVN

by Adam Vandenberg, 13 years ago

Attachment: document-meta.diff added

comment:5 by Adam Vandenberg, 13 years ago

Initial doc patch; needs review.

Developed after #14841.

comment:6 by Adam Vandenberg, 13 years ago

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

comment:7 by Adam Vandenberg, 13 years ago

Developed this patch after this one: #14842

comment:8 by Adam Vandenberg, 13 years ago

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

comment:9 by Tim Graham, 13 years ago

Has patch: set
milestone: 1.3
Needs documentation: unset
Triage Stage: Someday/MaybeAccepted

comment:10 by Russell Keith-Magee, 13 years ago

milestone: 1.3
Triage Stage: AcceptedSomeday/Maybe

@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.

comment:11 by Tim Graham, 13 years ago

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

comment:12 by Matt McClanahan, 13 years ago

Severity: Normal
Type: New feature

comment:13 by Aymeric Augustin, 12 years ago

UI/UX: unset

Change UI/UX from NULL to False.

comment:14 by Aymeric Augustin, 12 years ago

Easy pickings: unset

Change Easy pickings from NULL to False.

comment:15 by Unai Zalakain, 10 years ago

Cc: unai@… added

comment:16 by pirosb3, 10 years ago

Cc: pirosb3 added
Owner: changed from Adam Vandenberg to pirosb3
Status: newassigned
Triage Stage: Someday/MaybeAccepted

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

comment:17 by Tim Graham, 10 years ago

Patch needs improvement: set

comment:18 by Tim Graham <timograham@…>, 10 years ago

In d862fae5bbfb52ab7aeaad5a59b3d8b27b30c8f9:

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

Thanks Russell Keith-Magee and Tim Graham for reviews.

comment:19 by Tim Graham, 10 years ago

Component: DocumentationDatabase layer (models, ORM)
Summary: Information provided by Model._meta should be documented in <djangodocs>/models/options/Formalize, refactor, and document Model._meta

comment:20 by Tim Graham, 9 years ago

Keywords: 1.8-alpha added; Model Meta Documentation removed

comment:21 by Collin Anderson, 9 years ago

Cc: cmawebsite@… added

comment:22 by Tim Graham, 9 years ago

Patch needs improvement: unset
Triage Stage: AcceptedReady for checkin

comment:23 by Tim Graham <timograham@…>, 9 years ago

Resolution: fixed
Status: assignedclosed

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!

comment:24 by Collin Anderson, 9 years ago

I found a regression: #24146

comment:25 by Tim Graham <timograham@…>, 8 years ago

In c64dd64:

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

comment:26 by GitHub <noreply@…>, 6 years ago

In dd367e0d:

Refs #12663 -- Removed Meta API upgrade guide.

comment:27 by Tim Graham <timograham@…>, 5 years ago

In 218a485b:

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

Note: See TracTickets for help on using tickets.
Back to Top