bpo-22865: Expand on documentation for the pty.spawn function

[RadicalZephyr]

Documentation enhancements for the pyt.spawn function as discussed in issue 22865.

https://bugs.python.org/issue22865

[the-knights-who-say-ni]

Hello, and thanks for your contribution!

I'm a bot set up to make sure that the project can legally accept your contribution by verifying you have signed the PSF contributor agreement (CLA).

Unfortunately we couldn't find an account corresponding to your GitHub username on bugs.python.org (b.p.o) to verify you have signed the CLA (this might be simply due to a missing "GitHub Name" entry in your b.p.o account settings). This is necessary for legal reasons before we can look at your contribution. Please follow the steps outlined in the CPython devguide to rectify this issue.

You can check yourself to see if the CLA has been received.

Thanks again for your contribution, we look forward to reviewing it!

[JulienPalard]

LGTM, as the _read function is:

def _read(fd):
    """Default read function."""
    return os.read(fd, 1024)

and the os.read documentation states If the end of the file referred to by fd has been reached, an empty bytes object is returned., it's consistent.

[RadicalZephyr]

I rewrote some things and included the suggestions made by @vadmium.

I also added a bunch of documentation about what happens when an EOF condition is signalled.

[vstinner]

I don't know well the pty module and so is unable to review this long description. So I asked for a review at:
https://bugs.python.org/issue26228#msg336689

By the way, I'm fine with documenting bugs, but for the longer term we should maybe try to fix it ;-)

[RadicalZephyr]

@vstinner oh, I'm on it 😀 #12049 I just figured it should be a separate PR. Depending on which gets merged first I'll update or delete the comments about the known bug.

[vstinner]

LGTM.

[RadicalZephyr]

Is there anything I can do to help move this forward again? @vstinner @csabella @JulienPalard

[miss-islington]

Thanks @RadicalZephyr for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7.
🐍🍒⛏🤖

[miss-islington]

Sorry, @RadicalZephyr and @vstinner, I could not cleanly backport this to 3.7 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 522ccef8690970fc4f78f51a3adb995f2547871a 3.7

[vstinner]

Is there anything I can do to help move this forward again? @vstinner @csabella @JulienPalard

Honestly, I'm far from an expert of PTY. I trust you, so I just merged your PR :-D

Sorry, @RadicalZephyr and @vstinner, I could not cleanly backport this to 3.7 due to a conflict.

Can you please try to backport the change to 3.7? If not, I just close https://bugs.python.org/issue22865

[bedevere-bot]

GH-13455 is a backport of this pull request to the 3.7 branch.

[RadicalZephyr]

thanks @vstinner!

[vstinner]

thanks @vstinner!

Honestly, thanks to you. Your doc enhancement is really helpful, and we need more experts on some special functions like pty.spawn(). There are so many corner cases which are painful to discover by trail-and-error.