[Django] #36766: Reference to package as "module" is confusing

[Django]

#36766: Reference to package as "module" is confusing
-----------------------------------------+---------------------------
Reporter: Bob Kline | Owner: Bob Kline
Type: Bug | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Keywords: tutorial
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-----------------------------------------+---------------------------
Following up on the related [https://forum.djangoproject.com/t/package-
versus-module/43560 forum discussion], I propose changing

> ... add the name of the module that contains your `models.py`.

to

> ... add the name of the package that contains your `models` module.

in the [https://docs.djangoproject.com/en/5.2/topics/db/models/#using-
models Using models] section of the tutorial.

In my experience, most Python programmers are not aware that, technically
speaking, a package ''is'' a special type of module. This is due
principally to the fact that most of the language in the Python
documentation implies that the term "modules" does not include packages.
Earlier in the tutorial this package is referred to as a "package," not a
"module," and there is no reason not to use the more specific term here,
preventing unnecessary confusion.

I will submit a PR shortly.
--
Ticket URL: <https://code.djangoproject.com/ticket/36766>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36766: Reference to package as "module" is confusing

-------------------------------+--------------------------------------

Reporter: Bob Kline | Owner: Bob Kline
Type: Bug | Status: assigned
Component: Documentation | Version: 5.2

Severity: Normal | Resolution:

Keywords: tutorial | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

-------------------------------+--------------------------------------
Description changed by Bob Kline:

Old description:

> Following up on the related [https://forum.djangoproject.com/t/package-
> versus-module/43560 forum discussion], I propose changing
>
> > ... add the name of the module that contains your `models.py`.
>
> to
>
> > ... add the name of the package that contains your `models` module.
>
> in the [https://docs.djangoproject.com/en/5.2/topics/db/models/#using-
> models Using models] section of the tutorial.
>
> In my experience, most Python programmers are not aware that, technically
> speaking, a package ''is'' a special type of module. This is due
> principally to the fact that most of the language in the Python
> documentation implies that the term "modules" does not include packages.
> Earlier in the tutorial this package is referred to as a "package," not a
> "module," and there is no reason not to use the more specific term here,
> preventing unnecessary confusion.
>
> I will submit a PR shortly.

New description:

Following up on the related [https://forum.djangoproject.com/t/package-
versus-module/43560 forum discussion], I propose changing

> ... add the name of the module that contains your `models.py`.

to

> ... add the name of the package that contains your `models` module.

in the [https://docs.djangoproject.com/en/5.2/topics/db/models/#using-
models Using models] section of the tutorial.

In my experience, most Python programmers are not aware that, technically
speaking, a package ''is'' a special type of module. This is due

principally to the fact that most of the relevant language in the Python

documentation implies that the term "modules" does not include packages.
Earlier in the tutorial this package is referred to as a "package," not a
"module," and there is no reason not to use the more specific term here,
preventing unnecessary confusion.

I will submit a PR shortly.

--

--
Ticket URL: <https://code.djangoproject.com/ticket/36766#comment:1>

[Django]

#36766: Reference to package as "module" is confusing
-------------------------------+--------------------------------------
Reporter: Bob Kline | Owner: Bob Kline
Type: Bug | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: tutorial | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+--------------------------------------
Description changed by Bob Kline:

Old description:

> Following up on the related [https://forum.djangoproject.com/t/package-
> versus-module/43560 forum discussion], I propose changing
>
> > ... add the name of the module that contains your `models.py`.
>
> to
>
> > ... add the name of the package that contains your `models` module.
>
> in the [https://docs.djangoproject.com/en/5.2/topics/db/models/#using-
> models Using models] section of the tutorial.
>
> In my experience, most Python programmers are not aware that, technically
> speaking, a package ''is'' a special type of module. This is due

> principally to the fact that most of the relevant language in the Python
> documentation implies that the term "modules" does not include packages.
> Earlier in the tutorial this package is referred to as a "package," not a
> "module," and there is no reason not to use the more specific term here,
> preventing unnecessary confusion.
>
> I will submit a PR shortly.

New description:

Following up on the related [https://forum.djangoproject.com/t/package-
versus-module/43560 forum discussion], I propose changing

> ... add the name of the module that contains your `models.py`.

to

> ... add the name of the package that contains your `models` module.

in the [https://docs.djangoproject.com/en/5.2/topics/db/models/#using-

models Using models] section of the documentation.

In my experience, most Python programmers are not aware that, technically
speaking, a package ''is'' a special type of module. This is due
principally to the fact that most of the relevant language in the Python
documentation implies that the term "modules" does not include packages.

In the tutorial the application package is referred to as a "package," not

a "module," and there is no reason not to use the more specific term here,
preventing unnecessary confusion.

I will submit a PR shortly.

--
--

Ticket URL: <https://code.djangoproject.com/ticket/36766#comment:2>

[Django]

#36766: Reference to package as "module" is confusing
-------------------------------+--------------------------------------
Reporter: Bob Kline | Owner: Bob Kline
Type: Bug | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:

Keywords: models | Triage Stage: Unreviewed

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+--------------------------------------

Changes (by Bob Kline):

* keywords: tutorial => models

--
Ticket URL: <https://code.djangoproject.com/ticket/36766#comment:3>

[Django]

#36766: Reference to package as "module" is confusing
-------------------------------+--------------------------------------
Reporter: Bob Kline | Owner: Bob Kline
Type: Bug | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: models | Triage Stage: Unreviewed

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+--------------------------------------
Changes (by Bob Kline):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36766#comment:4>

[Django]

#36766: Reference to package as "module" is confusing
-------------------------------+--------------------------------------
Reporter: Bob Kline | Owner: Bob Kline

Type: Bug | Status: closed
Component: Documentation | Version: 5.2
Severity: Normal | Resolution: wontfix

Keywords: models | Triage Stage: Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
-------------------------------+--------------------------------------

Changes (by Jacob Walls):

* resolution: => wontfix
* status: assigned => closed

Comment:

Hi Bob, thanks for the ticket. I saw this on forum and was going to reply.
I don't think we want to describe the models module as a package, as it's
not intended to be distributed by itself.

That sense of "package" as "packaged for distribution" is clarified here:
https://docs.djangoproject.com/en/5.2/intro/reusable-apps/#reusability-
matters

Given that startapp doesn't create any package metadata I'm wary of
adopting that "package" wording in additional places. In other words,
neither the models module nor the app needs to be a package.
--
Ticket URL: <https://code.djangoproject.com/ticket/36766#comment:5>