[patch] allow replacing models.py with a subpackage models/__init__.py

I don't know offhand if it's documented anywhere (if it isn't we need to fix that), but splitting models up into files in a module actually works right now -- you just have to set the Meta option app_label to the name of the app, and make sure the __all__ statement in the module's __init__.py exports all the files you want to use.

There is some documentation at CookBookSplitModelsToFiles.

There used to be a small section in the old model_api docs, but that seems to have disappeared.

I did not see the Meta.app_name setting. With the patch you don't need to set the Meta.app_name anymore. Just move the Models in a subpackage and be done.

And it would be nice to have the models-as-subpackage doc paragraph back, I surely missed that :)

Looking good, Bastian.

Some documentation could be good, but I don't think it blocks this being checked in.

Stripping the "Ready for checking" as I'm about to upload documentation for that, please review it and set "Ready for checking" if it's ok.

Hope you don't mind ;)

Documentation for #2982

Apart from a few weird character typos in the documentation, it looks all right to me. I'm sure a core will check the wording / typos and change as appropriate.

Not quite ready for checkin yet, upon examination (no fault of the triagers, I just was looking over it before checking it in)...

In the past we've rejected this sort of approach because it required the redundant import statements in models/__init__.py (rather than just from models.foo.bar import MyModel in the code being sufficient). Ideally, it would be nice to descend from models (whether it's models/ or models.py) and extract all the models without needing the models/__init__.py import. I think db.models.loading is one place that needs fixing for that. I think it should be possible to make this work.

We should be able to make a test for this one, since we have models.py files in the tests already (make a new test directory and have a models/ directory in it). Need to make sure we test that it works sufficiently generally (models/foo/bar.py should work -- looks like it does, but testing makes perfect).

I don't like the use of "assert" in this patch, since assert is for things that should never fail and we can "guarantee" will be true. We cannot make guarantees about the user's (programmer's) code, though; they do make mistake and it's not Django's internal fault if that happens. So we should do a normal check and raise a proper exception (not AssertionError?) if there is a problem. Everywhere else in Django does this upon an end-user error, so it's consistent.

I'll probably fix some/all of these problems myself on the next pass through if nobody wants to do it first. Just recording the problems for future triage benefit.

This is yet another issue related to app_label, and so gets closed in favor of #3591.