In Django, how is the term "app" defined?

Question

In my Django app, I have a lot of code so I have split up my source files and put them into sub-folders, as follows:

myproject/
    myapp/
        management/
            __init__.py
        models/
            __init__.py
            common.py
            users.py
            matches.py
        questionnaires/
            demographics/
                templates/
                __init__.py
                models.py
                views.py
            ...
        views/
            __init__.py
            abstract.py
            concrete.py

Now I'm confused what to put in INSTALLED_APPS. Is it all the folders containing models? Or all the folders containing source? If i include all child folders, do I also need to include the parent folder? Should this match what's in my my setup.py's packages argument?

Note: I know I could refactor this into multiple apps, but (1) I would like for all this functionality to have a common namespace since it's being redistributed and (2) I am regardless curious for the answer to my question.

Answer 1

Put the directory containing the models.py file, that is your "App". Django uses the models to bind to the database, everything after that is just filler.

The DJango startup is (very slimmed down) as such

manage.py

# The important part
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "path.to.your.settings")

This will define the important pieces, but lets look at the installed

settings.py

INSTALLED_APPS=(
   'your.app.name'
)

Which basically states, you'll find my models.py there and some model definitions (they don't have to be defined, but models.py needs to exist)

your/app/name/models.py

class SomeModel(models.Model):
    #... model definition ...
    pass

Now back to your settings.py

Your source can live ANYWHERE because DJango looks in some very specific locations for certain things, but this is mostly configured in your settings.py

ROOT_URLCONF = 'path.to.urls' # this is the pythonic module path to your `urls.py` file

in your urls.py file you can define a url such as

url(r'^/some/url/def/$', 'some.other.module.handler'),

as long as handler from some.other.module returns a valid HttpResponse object and is on the PYTHONPATH it does not matter where the class lives.

Django has some specifics about management commands, they must live inside your app directory (the same as your model dir) so to define those (if your model.py file is inside a different location) you must put them in your data dir

For example I have a project with the following layout

/app  
  /data  
     /commands  
        some_command.py
     models.py  
  /app  
     urls.py  
     settings.py
     ...other-source-files...

My settings.py simple says load the app data and point to app.url for the url configuration, from that point on it doesn't matter where your source lives (for the most part).

We did this so that our database tables would be named data_sometablename vs app_sometablename (i was not part of this choice, happened long before i joined)