Split django.db.models.fields.related into multiple modules.

[loic84]

The django.db.models.fields.related module is very large and pretty hard to work with.

It contains a lot of similar concepts with only slight differences, and one thing can easily be mistaken for its exact opposite, which makes navigating the file very error-prone. This is made worse by the fact that some class name are borderline wrong, (e.g. ReverseSingleRelatedObjectDescriptor which actually is the forward FK descriptor).

Quoting akaariai: "fields/related.py is a brain melting machine".

This ticket proposes that we turn related.py into a package with the following modules: related_field.py, many_to_one.py, one_to_one.py and many_to_many.py.

[Tim Graham]

I suggest we do it after 1.7 is released so backporting any bug fixes in this area in the meantime is not so painful.

[loic84]

@timo, very good point, clearly this needs to wait for the 1.7 release.

The latest effort regarding this ticket is tracked at ​https://github.com/django/django/pull/2411.

[Loic Bistuer]

I'm planning to resume work on this.

​https://github.com/django/django/pull/2411#issuecomment-56624379 shows a summary of where we were.

I wonder if ForeignObject shouldn't move to many_to_one.py as well.

[Tim Graham]

I'm tagging this ticket 1.8-alpha so we can try to make this change close to that date (currently scheduled for January 12) before we fork stable/1.8.x.

[Ivan Kolodyazhny]

@loic hi. this ticket isn't assigned to anybody. are you planing to resume on this ticker or i can start to do it?

[Loic Bistuer]

Hi @e0ne, I'm still planning to tackle this once I return from holiday. I discussed this recently on IRC and it'll go further than just splitting the files:

• Refactor ForeignObject to not depend on ReverseSingleRelatedObjectDescriptor, which includes factoring out the relevant bits of ReverseSingleRelatedObjectDescriptor into a new descriptor.
• Move the existing ReverseSingleRelatedObjectDescriptor to many_to_one.py but deprecate it and introduce a new better named descriptor, since this is actually the forward side of a FK.

[Tim Graham]

from Loic on the PR: "I think we are going to postpone this refactor some more."

[Aymeric Augustin]

The discussions on the previous attempt show that grouping code by the type of relation (one-to-one, one-to-many, many-to-many) doesn't work very well. It raises hard questions about where code would end up after plausible refactorings.

I'd like to suggest a different approach: group code by the type of objects defined:

• descriptors
• managers
• "rel objects" (these don't have a good name)
• etc.

This is straightforward, reasonably future proof — if we introduce a new kind of object it's easy to add a module.

It groups similar code nicely and allows for module docstrings explaining the role of each layer.

[Aymeric Augustin]

See ​https://github.com/django/django/pull/5318.

[Aymeric Augustin <aymeric.augustin@…>]

In 005c9fc:

Fixed #22341 -- Split django.db.models.fields.related.

At 2800 lines it was the largest module in the django package. This
commit brings it down to a more manageable 1620 lines.

Very small changes were performed to uniformize import style.