diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index 69562f6544..d08d044979 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -1410,6 +1410,30 @@ different database tables). Django will raise a :exc:`~django.core.exceptions.FieldError` if you override any model field in any ancestor model. +Organizing models in a package +============================== + +The :djadmin:`manage.py startapp ` command creates an application +structure that includes a ``models.py`` file. If you have many models, +organizing them in separate files may be useful. + +To do so, create a ``models`` package. Remove ``models.py`` and create a +``myapp/models/`` directory with an ``__init__.py`` file and the files to +store your models. You must import the models in the ``__init__.py`` file. + +For example, if you had ``organic.py`` and ``synthetic.py`` in the ``models`` +directory: + +.. snippet:: + :filename: myapp/models/__init__.py + + from .organic import Person + from .synthetic import Robot + +Explicitly importing each model rather than using ``from .models import *`` +has the advantages of not cluttering the namespace, making code more readable, +and keeping code analysis tools useful. + .. seealso:: :doc:`The Models Reference `