Package versus module

Django Internals Documentation
1

The topic page for Models has a paragraph which says:

Once you have defined your models, you need to tell Django you’re going to use those models. Do this by editing your settings file and changing the INSTALLED_APPS setting to add the name of the module that contains your models.py .

While it is technically correct that a package is a special type of module, might it be more helpful to say “… name of the package that contains …”?

If folks agree, I’d be happy to create a ticket and a PR.

2

… might it be more helpful …

That’s a little vague, isn’t it? :thinking: Let me elaborate with some more explicit rationale. In my experience, the percentage of Python programmers who are consciously aware that packages are also modules is not that high. This is partly due, perhaps, to the fact that in quite a few places (including the PEPs) the official Python documentation refers to “modules and packages” as well as “modules or packages” as if “modules” by itself would not also include packages. Because of this, in combination with the fact that the Django tutorial uses “package” (not “package module” or “module”) when describing the directory containing a Django application, I wouldn’t be surprised if more than one reader might stumble when reading the paragraph quoted above, wondering which “module” the documentation could be referring to. I don’t see any downsides to using the more specific term here, but if there are any, I’m confident that someone will point them out. :sweat_smile:

3

IMO it would be clearer to talk about a package here. Something like:

to add the name of the package that contains your models submodule

(avoiding mixing up module names and filenames!)

If needed, the paragraph (or maybe the tutorial?) could be explicit with an example:

If your app is implemented by a package with this file layout:

superblog/
   __init__.py
   models.py
   views.py
   urls.py
   tests/

then add 'superblog' to INSTALLED_APPS.

1 Like