Add a security warning to pydoc

[StanFromIreland]

@picnixz and @woodruffw IIRC you've also suggested this before.

[picnixz]

Yeah, I'm tired of closing reports that claim vulns when it affects a dev component. So I'm in favor of that. But move that warning below (L75 in your PR) where we mention HTTP server. pydoc can be used in the CLI

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32841370 | 📁 Comparing e900b15 against main (c714b56)

  🔍 Preview build  

1 file changed

± library/pydoc.html

[StanFromIreland]

But move that warning below (L75 in your PR) where we mention HTTP server. pydoc can be used in the CLI

I'll disagree here, the introductory paragraph introduces that it can "served to a web browser," and there is no section specifically for the HTTP server. I'd generally prefer to put warnings in visible places (i.e., at the top of sections).

[woodruffw]

Seems reasonable to me! I don't have an opinion on placement.

[picnixz]

there is no section specifically for the HTTP server

The paragraph serves a section for me. It has sufficient information about the port as well:

You can also use :program:pydoc to start an HTTP server on the local machine
that will serve documentation to visiting web browsers. :program:python -m pydoc -p 1234
will start a HTTP server on port 1234, allowing you to browse the
documentation at http://localhost:1234/ in your preferred web browser.
Specifying 0 as the port number will select an arbitrary unused port.

:program:python -m pydoc -n <hostname> will start the server listening at the given
hostname. By default the hostname is 'localhost' but if you want the server to
be reached from other machines, you may want to change the host name that the
server responds to. During development this is especially useful if you want
to run pydoc from within a container.

The fact that it serves localhost is important as well. So I would prefer having it there. Serving to a web browser has nothing to do with the HTTP server itself. You can serve to a webbrowser using other means. What's vulnerable is the HTTP server itself.

Note that someone wanting to know about the HTTP server itself may have Google jump to that sentence in the paragraph specifically. And having the warning closer is better. Especially if we use the words "especially useful".

[StanFromIreland]

Discussing the position isn't particularly productive, so I've conceded and moved it.

[picnixz]

Thank you! I simulated a user asking how to use pydoc HTTP and since the CLI for -p/-n is below on the page, you don't see it directly. So when you search for it, you'll see the warning at the correct place. Otherwise, you might miss the warning.

To make it better, I would suggest that we actually have separate sections so that web browsers can directly jump to it (follow-up PR). WDYT?