Opened 6 years ago

Closed 7 months ago

Last modified 7 months ago

#12663 closed New feature (fixed)

Formalize, refactor, and document Model._meta

Reported by: MadeR 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 adamv 5 years ago.

Download all attachments as: .zip

Change History (25)

comment:1 Changed 6 years ago by ubernostrum

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to wontfix
  • Status changed from new to closed

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 6 years ago by russellm

  • Resolution wontfix deleted
  • Status changed from closed to reopened
  • Triage Stage changed from Unreviewed to Someday/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 5 years ago by russellm

  • milestone 1.2 deleted

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

comment:4 Changed 5 years ago by adamv

  • Needs documentation set
  • Owner changed from nobody to adamv
  • Status changed from reopened to new
  • Version changed from 1.2-alpha to SVN

Changed 5 years ago by adamv

comment:5 Changed 5 years ago by adamv

Initial doc patch; needs review.

Developed after #14841.

comment:6 Changed 5 years ago by adamv

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

comment:7 Changed 5 years ago by adamv

Developed this patch after this one: #14842

comment:8 Changed 5 years ago by adamv

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

comment:9 Changed 5 years ago by timo

  • Has patch set
  • milestone set to 1.3
  • Needs documentation unset
  • Triage Stage changed from Someday/Maybe to Accepted

comment:10 Changed 5 years ago by russellm

  • milestone 1.3 deleted
  • Triage Stage changed from Accepted to Someday/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 5 years ago by timo

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

comment:12 Changed 4 years ago by mattmcc

  • Severity set to Normal
  • Type set to New feature

comment:13 Changed 3 years ago by aaugustin

  • UI/UX unset

Change UI/UX from NULL to False.

comment:14 Changed 3 years ago by aaugustin

  • Easy pickings unset

Change Easy pickings from NULL to False.

comment:15 Changed 22 months ago by unaizalakain

  • Cc unai@… added

comment:16 Changed 15 months ago by pirosb3

  • Cc pirosb3 added
  • Owner changed from adamv to pirosb3
  • Status changed from new to assigned
  • Triage Stage changed from Someday/Maybe to Accepted

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 15 months ago by timo

  • Patch needs improvement set

comment:18 Changed 14 months 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 13 months ago by timo

  • Component changed from Documentation to Database layer (models, ORM)
  • Summary changed from Information provided by Model._meta should be documented in <djangodocs>/models/options/ to Formalize, refactor, and document Model._meta

comment:20 Changed 7 months ago by timgraham

  • Keywords 1.8-alpha added; Model Meta Documentation removed

comment:21 Changed 7 months ago by collinanderson

  • Cc cmawebsite@… added

comment:22 Changed 7 months ago by timgraham

  • Patch needs improvement unset
  • Triage Stage changed from Accepted to Ready for checkin

comment:23 Changed 7 months ago by Tim Graham <timograham@…>

  • Resolution set to fixed
  • Status changed from assigned to closed

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 7 months ago by collinanderson

I found a regression: #24146

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