classification
Title: Doc: make serve uses http.server instead of Tools/scripts/server.py
Type: Stage: resolved
Components: Documentation Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, brett.cannon, docs@python, matrixise, mdk, ned.deily, serhiy.storchaka, vstinner
Priority: normal Keywords: patch

Created on 2019-03-18 13:57 by matrixise, last changed 2019-05-15 08:43 by matrixise.

Pull Requests
URL Status Linked Edit
PR 12408 open matrixise, 2019-03-18 14:14
PR 12511 merged matrixise, 2019-03-23 09:22
PR 12522 closed matrixise, 2019-03-24 12:29
PR 12562 merged matrixise, 2019-03-26 14:10
Messages (22)
msg338224 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-18 13:57
The Makefile of Doc/ has a `serve` target. Currently, this one uses `Tools/scripts/serve.py`. But since 3.7, this script could be replaced by `python -m http.server -d directory`.

@mdk and myself thinking we could deprecate `Tools/scripts/serve.py` with a warning and propose to use `-m http.server -d directory`
msg338247 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-03-18 15:46
I'm ok with modifying "make server" to reuse http.server, but I'm not sure about deprecating Tools/scripts/serve.py.

serve.py uses wsgiref which is different than http.server. Does anyone use it? I would prefer to keep it. If you want to remove it, please send an email to python-dev to ask who uses it.


"make serve" has been added by bpo-8004 which added Tools/scripts/serve.py.

commit e4c74e1ea26e77b065a8999b7192160595474211
Author: Dirkjan Ochtman <dirkjan@ochtman.nl>
Date:   Wed Feb 24 04:12:11 2010 +0000

    Issue #8004: add a serve target to the Doc Makefile.
msg338258 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-03-18 16:53
I disagree with deprecating serve.py. It is a demo for the wsgiref module.
msg338276 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2019-03-18 18:18
If it's appreciated as a demo for wsgiref, wouldn't it be better to move it inside Doc/library/wsgiref.rst?

It was written specifically for the Doc/Makefile, it's no longer needed for the Doc/Makefile, so the question pops: is it usefull to anyone? If not it's better to drop it (or move it to the documentation as a nice, time-proven example).
msg338396 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-03-19 18:55
I agree that if it's a good example of using wsgiref then it should exist in the wsgiref docs as an example. Then that would mean dropping the script and updating the Makefile.
msg338631 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-23 00:16
Hi @mdk and @brett

with your suggestions, I will move the serve.py in the documentation of wsgiref and change Doc/Makefile.
msg338637 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-03-23 01:01
> with your suggestions, I will move the serve.py in the documentation of wsgiref and change Doc/Makefile.

I suggest to write two separated PRs for each change.
msg338662 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-23 10:10
@vstinner

I propose two PRs.

The first one will remove the Tools/scripts/serve.py file and update the Makefile.

The second and independent PR just add a new example in the documentation of wsgiref, the example is based on Tools/scripts/serve.py
msg338665 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-03-23 11:07
I would remove to move the script into the doc in 1 PR and just modify
Makefile in the other one. So the Makefile can be updated first.
msg338666 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-03-23 11:09
Maybe others prefer to do both changes at once. I don't know.
msg338739 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2019-03-24 16:25
The files in the Tools directory are installed on user systems by various distributions: for example, in Debian, as part of the python3.x-examples package and by the macOS python.org installer.  If you move serve.py, it will no longer be available to end users there.  I don't think there is any benefit to removing the file in Tools/scripts and there is some downside; let's leave it there.

https://packages.debian.org/sid/all/python3.7-examples/filelist
msg338741 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-24 16:29
Hi Ned,

There are 3 PRs, part-0, part-1 and part-2

We can ignore the part-1, this one remove serve.py and the two others are independent.
msg338743 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2019-03-24 18:41
Just dropping part-1 is fine with me, thanks.
msg338833 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-03-25 22:53
New changeset 360e1e4c519cfc139de707bcdd1e6c871eec79ee by Brett Cannon (Stéphane Wirtel) in branch 'master':
bpo-36345: Add a new example in the documentation of wsgiref (#12511)
https://github.com/python/cpython/commit/360e1e4c519cfc139de707bcdd1e6c871eec79ee
msg338864 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-26 09:08
Thank you for the merge.

Stéphane
msg338874 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-03-26 12:33
Would it me sense to use ".. literalinclude:: ../../Tools/scripts/serve.py" in the wsgi doc to keep serve.py and and this example up to date? It seems like serve.py is going to stay.
msg338909 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2019-03-26 18:19
I actually still think we should remove serve.py as the person who had needed to clean up that directory when we realized we had massive bitrot in /Tools. :) I don't' think that just because Debian packages means we need to continue supporting and maintaining it (e.g. if wsgiref was changed who is going to remember to update this script?).
msg340338 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-04-16 12:53
New changeset 2b7f93b99afbe78e4e567d9252d9470d29f387c8 by Stéphane Wirtel in branch 'master':
bpo-36345: Update wsgiref example (GH-12562)
https://github.com/python/cpython/commit/2b7f93b99afbe78e4e567d9252d9470d29f387c8
msg341162 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2019-04-30 20:41
Please revert 360e1e4c519cfc139de707bcdd1e6c871eec79ee. It's not a good example to put into the documentation.

It uses different naming convention. It would only confuse users relatively new to the wsgiref module and WSGI protocol.

FileWrapper was supposed to support __getitem__ and __iter__ protocols for compatibility with older Python versions, but its __getiem__ implementation is buggy and is already deprecated. It has no use case in modern Python code.

It has zero exception handling and will return a cryptic traceback if mimetype cannot detect type of the file.

The examples in the wsgiref documentation already cover most of the cases. There is no need to add more similar ones.
msg342046 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-05-10 02:36
Berker Peksag:
> Please revert 360e1e4c519cfc139de707bcdd1e6c871eec79ee. It's not a good example to put into the documentation.

I looked at other examples: they are nice but far from a "real application". I like the last example which combines multiple wsgiref features and is written like a real application: parse command line arguments, handle CTRL+c, etc.


> It uses different naming convention. It would only confuse users relatively new to the wsgiref module and WSGI protocol.

Would you mind to elaborate? I don't understand what you mean by "naming convention" here, sorry.


> FileWrapper was supposed to support __getitem__ and __iter__ protocols for compatibility with older Python versions, but its __getiem__ implementation is buggy and is already deprecated. It has no use case in modern Python code.

Do you mean that app() must not return FileWrapper? How do you return file content in that case?

Maybe FileWrapper API should be clarified? It's surprising to read Python 3.8 mentioning compatibility with Python 2.1 :-)


> It has zero exception handling and will return a cryptic traceback if mimetype cannot detect type of the file.

Which kind of exceptions do you expect? The example checks if the file exists for example.
msg342060 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2019-05-10 08:00
> I looked at other examples: they are nice but far from a "real application".

You can use the same argument for pretty much every example in the stdlib documentation :)

wsgiref is a low level module, users should use projects like WebOb instead. Also, a complete example would need to contain basic routing and middleware support (which is not easy to implement correctly)

> Would you mind to elaborate? I don't understand what you mean by "naming convention" here, sorry.

For example, the response() callable in the example is explicitly documented as start_response() in PEP 3333:

    https://www.python.org/dev/peps/pep-3333/#the-start-response-callable

You can read PEP 3333 for more details.

> Do you mean that app() must not return FileWrapper? How do you return file content in that case?
> Maybe FileWrapper API should be clarified? It's surprising to read Python 3.8 mentioning compatibility with Python 2.1 :-)

The whole point of the API was to support both __getitem__ and __iter__ protocols at the same time without breaking user code. I've already deprecated the support for __getitem__ protocol (84a13fbda0d79789e3c9efcc9f64752261ce1e8d) because it wasn't working as expected (it ignores its 'index' argument)

Its only valid use case is to read a file chunk by chunk by using its blksize argument, but there are much better ways to achieve the same thing (use os.sendfile() or nginx :))

> Which kind of exceptions do you expect? The example checks if the file exists for example.

I'm talking about exceptions that can be raised by the application code, such as the one that I've mentioned (i.e. mimetypes) in my earlier comment.

Sorry, but it's not really a good example to put into documentation and it would be much better if we could save our bikeshedding bandwidth to other issues :)
msg342135 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2019-05-10 21:25
Ok, thanks Berker for your longer answer. I have no opinion on this example anymore. Stéphane and others: I let you decide how to handle it ;-)
History
Date User Action Args
2019-05-15 08:43:26matrixisesettitle: Deprecate Tools/scripts/serve.py in favour of python -m http.server -d -> Doc: make serve uses http.server instead of Tools/scripts/server.py
2019-05-10 21:25:10vstinnersetmessages: + msg342135
2019-05-10 08:00:27berker.peksagsetmessages: + msg342060
2019-05-10 02:36:07vstinnersetmessages: + msg342046
2019-04-30 20:41:36berker.peksagsetnosy: + berker.peksag
messages: + msg341162
2019-04-19 09:16:47matrixisesetstatus: closed -> open
resolution: fixed ->
2019-04-19 09:16:23matrixisesetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2019-04-16 12:53:14matrixisesetmessages: + msg340338
2019-03-26 18:19:48brett.cannonsetmessages: + msg338909
2019-03-26 14:10:31matrixisesetpull_requests: + pull_request12507
2019-03-26 12:33:51vstinnersetmessages: + msg338874
2019-03-26 09:08:30matrixisesetmessages: + msg338864
2019-03-25 22:53:05brett.cannonsetmessages: + msg338833
2019-03-24 18:41:10ned.deilysetmessages: + msg338743
2019-03-24 16:29:16matrixisesetmessages: + msg338741
2019-03-24 16:25:16ned.deilysetnosy: + ned.deily
messages: + msg338739
2019-03-24 12:29:44matrixisesetpull_requests: + pull_request12473
2019-03-23 11:09:16vstinnersetmessages: + msg338666
2019-03-23 11:07:40vstinnersetmessages: + msg338665
2019-03-23 10:10:58matrixisesetmessages: + msg338662
2019-03-23 09:22:33matrixisesetpull_requests: + pull_request12462
2019-03-23 01:01:14vstinnersetmessages: + msg338637
2019-03-23 00:16:53matrixisesetmessages: + msg338631
2019-03-19 18:55:30brett.cannonsetnosy: + brett.cannon
messages: + msg338396
2019-03-18 18:18:00mdksetmessages: + msg338276
2019-03-18 16:53:37serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg338258
2019-03-18 15:46:55vstinnersetnosy: + vstinner
messages: + msg338247
2019-03-18 14:32:16mdklinkissue36211 superseder
2019-03-18 14:14:45matrixisesetkeywords: + patch
stage: patch review
pull_requests: + pull_request12362
2019-03-18 14:00:38matrixisesetnosy: + mdk
2019-03-18 13:57:39matrixisecreate