[Django] #35107: How to write a management command that reads from stdin should be documented

[Django]

#35107: How to write a management command that reads from stdin should be
documented
-------------------------------------------+------------------------
Reporter: Andrew Northall | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 5.0
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
-------------------------------------------+------------------------
This seems like a fairly common use case, which is supported by Django,
but as far as I can tell no mention of it is made in the documentation. It
seems like it should be documented.

For an example of how to do it, `loaddata` and `shell` read from stdin in
Django core:

https://github.com/django/django/blob/main/django/core/management/commands/loaddata.py
https://github.com/django/django/blob/main/django/core/management/commands/shell.py

I hear you say, 'but reading from stdin is a Python feature, not a Django
feature, why should we document it?'. In my mind, the documentation as it
exists now could lead to confusion: it makes specific mention that you
should use `BaseCommand.stdout` and `BaseCommand.stderr` within a
management command to write to stdout or stderr. It is not a big jump to
then assume that you should also be using `BaseCommand.stdin` (which does
not exist) to handle incoming data. The API, in this narrow sense, is
inconsistent, and this is why the documentation would be helpful.

--
Ticket URL: <https://code.djangoproject.com/ticket/35107>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35107: How to write a management command that reads from stdin should be
documented

---------------------------------+----------------------------------------
Reporter: Andrew Northall | Owner: Richard Zhao
Type: Uncategorized | Status: assigned
Component: Documentation | Version: 5.0
Severity: Normal | Resolution:

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

---------------------------------+----------------------------------------
Changes (by Richard Zhao):

* owner: nobody => Richard Zhao
* status: new => assigned

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

[Django]

#35107: How to write a management command that reads from stdin should be
documented

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

Reporter: Andrew Northall | Owner: Richard

Type: | Zhao
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.0
Severity: Normal | Resolution: wontfix

Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Mariusz Felisiak):

* status: assigned => closed
* type: Uncategorized => Cleanup/optimization
* resolution: => wontfix
* easy: 1 => 0

Comment:

Replying to [ticket:35107 Andrew Northall]:

> I hear you say, 'but reading from stdin is a Python feature, not a
Django feature, why should we document it?'.

Thanks for the ticket, however, we cannot document everything.

> In my mind, the documentation as it exists now could lead to confusion:
it makes specific mention that you should use `BaseCommand.stdout` and
`BaseCommand.stderr` within a management command to write to stdout or
stderr. It is not a big jump to then assume that you should also be using
`BaseCommand.stdin` (which does not exist) to handle incoming data. The
API, in this narrow sense, is inconsistent, and this is why the
documentation would be helpful.

I don't see anything inconsistency in API or docs. We don't document
nonexistent attributes, and users cannot assume that attributes exist if
they are not documented. In management commands you can use `sys.stdin`
like everywhere else, there is nothing specific that they provide. You can
start a discussion on DevelopersMailingList if you don't agree.

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