This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Document the constants in the socket module
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.7
Status: open Resolution:
Dependencies: 12887 13256 14345 27409 Superseder:
Assigned To: Nosy List: ammar2, bjourne, georg.brandl, giampaolo.rodola, martin.panter, r.david.murray, sonderblade
Priority: normal Keywords: patch

Created on 2007-06-06 20:46 by sonderblade, last changed 2022-04-11 14:56 by admin.

File name Uploaded Description Edit
doc-for-socket-af-constants.patch sonderblade, 2007-06-06 20:46
Messages (17)
msg52732 - (view) Author: Björn Lindqvist (sonderblade) Date: 2007-06-06 20:46
I wish to add documentation for the constants in the socket module. AF_*, SO_*, MSG_* etc. Some of them are really useful such as SO_KEEPALIVE and MSG_WAITALL. The modules documentation currently just refers the reader to UNIX manual pages, but I think we can do better.

This patch is for the AF_* constants. If it is accepted, I'd like to submit patches for the other constants too. Maybe there should be a subsection for all constants?
msg52733 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2007-06-07 13:44
I fear that intermixing \dataline with content within one datadesc is not correct.

I think I'd put the constants and their explanation into a table.
msg52734 - (view) Author: Björn Lindqvist (sonderblade) Date: 2007-06-07 17:57
I assume you like the general idea of the patch then? I'll create a patch with the tables and create a new subsection to contain them.
msg52735 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2007-06-07 18:05
Yes, more documentation is almost always better than less. :-)
msg59375 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-01-06 14:28
Be sure to use reST format now that we've switched to that. Much easier
to type :)
msg66743 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-05-12 17:12
Is there progress on this?
msg66751 - (view) Author: Giampaolo Rodola' (giampaolo.rodola) * (Python committer) Date: 2008-05-12 18:56
Yes, having a subsection describing such things would be a cool idea.
Please don't leave behind this ticket.
msg67121 - (view) Author: Björn Lindqvist (bjourne) Date: 2008-05-20 10:21
There is no progress on this. I had lots of documentation written in
Latex on a laptop, but then I lost it. Sorry.
msg116686 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2010-09-17 17:25
msg67121 states proposed changes were lost :(
msg116690 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-09-17 17:33
Resolution "won't fix" is inappropriate.  We'd love to fix it, but someone has to volunteer to (re)write the doc update...
msg269459 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-29 02:45
Reopening because the consensus seems to be to update and apply this sort of change.
msg272496 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-08-12 04:26
Issue 12887 is open to add explanations of the SO_* constants
msg299206 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2017-07-26 04:34
Gonna take this and its dependencies on, eta 2-4 days.
msg300151 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2017-08-11 05:22
I've opened up a PR for this ticket's dependencies. There's some things I'm looking for feedback on there:
msg300189 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-08-12 05:23
Issue 13256 contains a patch documenting socket options, but was closed because the author lost interest.

Issue 27409 is a proposal to list the symbols available without documenting what each one is for.
msg300192 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-08-12 10:33
The general rule for documenting availability seems to be to only list the special cases. Many of the socket options are specified by Posix, and seem to be available on Linux, Windows, BSD and other OSes. If you say “Availability: Linux, Windows”, it could imply that the API is specific to those two platforms, and not available on Free BSD or other platforms in general.
msg300197 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2017-08-12 12:12
That makes sense, listing availability for exceptions would certainly make everything more succinct. How do you propose we mention that certain options don't actually do anything on Windows. Currently I have a footnote in the table that links to the MSDN documentation here:

control+f for "SO_RCVLOWAT" for example
Date User Action Args
2022-04-11 14:56:24adminsetgithub: 45048
2017-08-12 12:12:03ammar2setmessages: + msg300197
2017-08-12 10:33:59martin.pantersetmessages: + msg300192
2017-08-12 05:23:44martin.pantersetdependencies: + Document and test new socket options, List socket.SO_*, SCM_*, MSG_*, IPPROTO_* symbols
messages: + msg300189
2017-08-11 05:22:58ammar2setmessages: + msg300151
2017-07-26 04:34:53ammar2setnosy: + ammar2
messages: + msg299206
2017-07-26 01:39:51ned.deilysetassignee: georg.brandl ->
versions: + Python 3.7, - Python 2.6
2017-01-22 02:41:53martin.pantersetdependencies: + Document socket.SOL_SOCKET
2016-08-12 04:26:11martin.pantersetdependencies: + Documenting all SO_* constants in socket module
messages: + msg272496
2016-06-30 04:13:23BreamoreBoysetnosy: - BreamoreBoy
2016-06-29 02:45:42martin.pantersetstatus: closed -> open

nosy: + martin.panter
messages: + msg269459

stage: needs patch
2010-09-17 17:33:49r.david.murraysetnosy: + r.david.murray
messages: + msg116690
resolution: wont fix ->

type: enhancement
2010-09-17 17:25:21BreamoreBoysetstatus: open -> closed

nosy: + BreamoreBoy
messages: + msg116686

resolution: wont fix
2008-05-20 10:21:16bjournesetnosy: + bjourne
messages: + msg67121
2008-05-12 18:56:36giampaolo.rodolasetnosy: + giampaolo.rodola
messages: + msg66751
2008-05-12 17:12:03georg.brandlsetmessages: + msg66743
2008-01-06 14:28:48georg.brandlsetmessages: + msg59375
2008-01-06 12:33:56christian.heimessetassignee: georg.brandl
versions: + Python 2.6
2007-06-06 20:46:18sonderbladecreate