Repository navigation
Document the constants in the socket module #45048
Description
| BPO | 1732367 |
|---|---|
| Nosy | @birkenfeld, @giampaolo, @bitdancer, @vadmium, @ammaraskar |
| Dependencies | |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2007-06-06.20:46:18.000>
labels = ['type-feature', '3.7', 'docs']
title = 'Document the constants in the socket module'
updated_at = <Date 2017-08-12.12:12:03.630>
user = 'https://bugs.python.org/sonderblade'bugs.python.org fields:
activity = <Date 2017-08-12.12:12:03.630>
actor = 'ammar2'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2007-06-06.20:46:18.000>
creator = 'sonderblade'
dependencies = ['12887', '13256', '14345', '27409']
files = ['8037']
hgrepos = []
issue_num = 1732367
keywords = ['patch']
message_count = 17.0
messages = ['52732', '52733', '52734', '52735', '59375', '66743', '66751', '67121', '116686', '116690', '269459', '272496', '299206', '300151', '300189', '300192', '300197']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'sonderblade', 'giampaolo.rodola', 'bjourne', 'r.david.murray', 'martin.panter', 'ammar2']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue1732367'
versions = ['Python 3.7']
Activity
sonderblade commentedon Jun 6, 2007
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?
birkenfeld commentedon Jun 7, 2007
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.
sonderblade commentedon Jun 7, 2007
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.
birkenfeld commentedon Jun 7, 2007
Yes, more documentation is almost always better than less. :-)
birkenfeld commentedon Jan 6, 2008
Be sure to use reST format now that we've switched to that. Much easier
to type :)
birkenfeld commentedon May 12, 2008
Is there progress on this?
giampaolo commentedon May 12, 2008
Yes, having a subsection describing such things would be a cool idea.
Please don't leave behind this ticket.
bjourne commentedon May 20, 2008
There is no progress on this. I had lots of documentation written in
Latex on a laptop, but then I lost it. Sorry.
BreamoreBoy commentedon Sep 17, 2010
msg67121 states proposed changes were lost :(
8 remaining items
ammaraskar commentedon Jul 26, 2017
Gonna take this and its dependencies on, eta 2-4 days.
ammaraskar commentedon Aug 11, 2017
I've opened up a PR for this ticket's dependencies. There's some things I'm looking for feedback on there: #3072
vadmium commentedon Aug 12, 2017
bpo-13256 contains a patch documenting socket options, but was closed because the author lost interest.
bpo-27409 is a proposal to list the symbols available without documenting what each one is for.
vadmium commentedon Aug 12, 2017
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.
ammaraskar commentedon Aug 12, 2017
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: https://msdn.microsoft.com/en-us/library/windows/desktop/ms740532(v=vs.85).aspx
control+f for "SO_RCVLOWAT" for example
pythongh-45048: Document the availability and uses of the SO_ constants.
pythongh-45048: Removed >= vista constrain on SO_BROADCAST support on…