Fields terminology for official Options API

[Daniel Pyrathon]

Hi All,

I am currently working on the new Options API (https://github.com/django/django/pull/2894).

The Options API is at the core of Django, it enables introspection of Django Models with the rest of the system. This enables lookups, queries, forms, admin to understand the capabilities of every model. The Options API is hidden under the _meta attribute of each model class. Options has always been a private API, but Django developers have always been using it in their own projects, in a non-official way.  As part of my SoC project, I am exposing the new API for public use. As we are also formalizing a new API that has always existed, It is important to revisit the terminology and document it.

The current terminology is described here https://code.djangoproject.com/wiki/new_meta_api in the section concepts. I would encourage all contributors to read the document and express their opinion, if they think something should be changed.

A few interesting comments up till now:

Loic on the PR:

• I prefer "concrete" to "data" as it makes the parallel with "virtual" more obvious.
• "related_objects" > "reverse_rel"
• "related_m2m" > "reverse_m2m"
• What about reverse o2o, do they currently fall under "related_objects"?
• The main issue I have with "related" is that it doesn't provide a sense of direction, after all both sides of a FK have related objects waiting on the other end. I also like the symmetry between "m2m" and "reverse_m2m".
• Django isn't always consistent (and sometime actually wrong) in naming relations, especially indjango/db/models/fields/related.py. Now that we start documenting all those things, I see value in getting it right.

Thanks,

Daniel

[Wim Feijen]

Hi Daniel,

First and foremost, thanks for all the good work, and for the clear and precise updates and explanations on django-developers!

I think renaming related to reverse is a good idea, because it is much clearer to me. Could reverse_rel become reverse_related in order not to use abbreviations? 

For me, data is a better term than concrete, because it deals with fields which store data and not concrete.

Good luck! 

Wim

[Collin Anderson]

This is awesome. I've always wished that django.contrib.admin used only documented django APIs. It's unfair to 3rd party apps. :) I'm also thankful I won't need to import bitflags just to use this API.

 

The Options API is at the core of Django, it enables introspection of Django Models with the rest of the system. This enables lookups, queries, forms, admin to understand the capabilities of every model. The Options API is hidden under the _meta attribute of each model class. Options has always been a private API, but Django developers have always been using it in their own projects, in a non-official way.  As part of my SoC project, I am exposing the new API for public use. As we are also formalizing a new API that has always existed, It is important to revisit the terminology and document it.

 

The word "Options" doesn't make much sense to me. I realize that both "meta options" and the fields are stored on the same object. I think "Model Meta API" or "Model Schema API" or "Model Fields API" or "Model Class API" or "Model Definition API" or "Model Structure API" would make more sense.

In the current docs, we're saying that meta options are "anything that's not a field", and it may make sense to keep "options" to referring to that.

https://docs.djangoproject.com/en/dev/topics/db/models/#meta-options

I prefer "concrete" to "data" as it makes the parallel with "virtual" more obvious.

Does this include m2m? We could call 'em "column" fields, as in fields that actually map to a column on the database table.

• "related_objects" > "reverse_rel"
• "related_m2m" > "reverse_m2m"
• What about reverse o2o, do they currently fall under "related_objects"?
• The main issue I have with "related" is that it doesn't provide a sense of direction, after all both sides of a FK have related objects waiting on the other end. I also like the symmetry between "m2m" and "reverse_m2m".
• Django isn't always consistent (and sometime actually wrong) in naming relations, especially indjango/db/models/fields/related.py. Now that we start documenting all those things, I see value in getting it right.

Maybe also "hidden" -> "reverse_hidden" to be consistent?

Maybe export_map -> return_names. or return_names_map.

[Josh Smeaton]

I was thinking "column" fields would make sense but it clashes with the internal concept of columns (Col types), and is only name-appropriate for a database backend. I'm not sure these are actually problems worth considering though.

[Robert Grant]

I was also thinking of MetaModels or something instead of Options, as I think it makes it more obvious what it's for.