Opened 7 years ago

Closed 2 years ago

Last modified 15 months ago

#12663 closed New feature (fixed)

Formalize, refactor, and document Model._meta

Reported by: Massimiliano Owned by: pirosb3
Component: Database layer (models, ORM) Version: master
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 6 years ago.

Download all attachments as: .zip

Change History (26)

comment:1 Changed 7 years ago by James Bennett

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 Changed 7 years ago by Russell Keith-Magee

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 Changed 7 years ago by Russell Keith-Magee

milestone: 1.2

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

comment:4 Changed 6 years ago by Adam Vandenberg

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

Changed 6 years ago by Adam Vandenberg

Attachment: document-meta.diff added

comment:5 Changed 6 years ago by Adam Vandenberg

Initial doc patch; needs review.

Developed after #14841.

comment:6 Changed 6 years ago by Adam Vandenberg

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

comment:7 Changed 6 years ago by Adam Vandenberg

Developed this patch after this one: #14842

comment:8 Changed 6 years ago by Adam Vandenberg

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

comment:9 Changed 6 years ago by Tim Graham

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

comment:10 Changed 6 years ago by Russell Keith-Magee

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 Changed 6 years ago by Tim Graham

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

comment:12 Changed 6 years ago by Matt McClanahan

Severity: Normal
Type: New feature

comment:13 Changed 5 years ago by Aymeric Augustin

UI/UX: unset

Change UI/UX from NULL to False.

comment:14 Changed 5 years ago by Aymeric Augustin

Easy pickings: unset

Change Easy pickings from NULL to False.

comment:15 Changed 3 years ago by Unai Zalakain

Cc: unai@… added

comment:16 Changed 3 years ago by pirosb3

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 Changed 3 years ago by Tim Graham

Patch needs improvement: set

comment:18 Changed 2 years ago by Tim Graham <timograham@…>

In d862fae5bbfb52ab7aeaad5a59b3d8b27b30c8f9:

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

Thanks Russell Keith-Magee and Tim Graham for reviews.

comment:19 Changed 2 years ago by Tim Graham

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 Changed 2 years ago by Tim Graham

Keywords: 1.8-alpha added; Model Meta Documentation removed

comment:21 Changed 2 years ago by Collin Anderson

Cc: cmawebsite@… added

comment:22 Changed 2 years ago by Tim Graham

Patch needs improvement: unset
Triage Stage: AcceptedReady for checkin

comment:23 Changed 2 years ago by Tim Graham <timograham@…>

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 Changed 23 months ago by Collin Anderson

I found a regression: #24146

comment:25 Changed 15 months ago by Tim Graham <timograham@…>

In c64dd64:

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

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