classification
Title: document AF_BLUETOOTH socket address formats
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Tim.Tisdall, berker.peksag, docs@python, martin.panter, python-dev, r.david.murray
Priority: normal Keywords: patch

Created on 2015-09-02 16:06 by Tim.Tisdall, last changed 2015-09-11 02:37 by martin.panter. This issue is now closed.

Files
File name Uploaded Description Edit
bluetooth_socket_docs.patch Tim.Tisdall, 2015-09-02 16:06 review
bluetooth_socket_docs_2.patch Tim.Tisdall, 2015-09-03 14:09 review
bluetooth_socket_docs_3.patch Tim.Tisdall, 2015-09-03 15:03 review
bluetooth_socket_docs_4.patch Tim.Tisdall, 2015-09-03 15:23 review
bluetooth_socket_docs_5.patch martin.panter, 2015-09-05 05:51 review
Messages (16)
msg249554 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-02 16:06
Currently https://docs.python.org/3.6/library/socket.html#socket-families only says "Certain other address families (AF_BLUETOOTH, AF_PACKET, AF_CAN) support specific representations." and there's a comment in the docs saying "document them!"...  So, I'm documenting the AF_BLUETOOTH.

I'm not sure about which versions this should be added to except for 3.6 so I'm listing the pertinent issues when changes were made: 

issue929192 seems to be where the current address format was added for L2CAP, RFCOMM, and SCO

issue1432399 seems to be where HCI was added

issue5510 seems to be where the alternate address format for HCI was added for NetBSD and DragonFlyBSD

It seems SCO used to accept a regular string but at 23ab586c427a it was changed to use a `bytes`...  I'm not sure the issue behind that.


This is my first contribution to CPython so I figured a patch to the docs would be easiest.  Please let me know if I'm doing anything wrong!
msg249580 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-02 22:35
Thanks for the patch and the archeological research. I made some minor grammar nitpicks in the code review.

Documentation typically gets applied to all the open branches. In this case 3.4–3.6 should be applicable. Maybe 2.7 also if you are interested; it may need a modified patch though, with different notices about the versions things were introduced.

Sounds like most of these addresses were added in 2.4, so no need for a “New in version” notice unless you add a 2.7 doc patch. But it maybe be useful to mention that the BSD support was added in 3.2.

Regarding revision 23ab586c427a (“Renamed PyString to PyBytes”, 2008), I haven’t checked, but you will probably find that was made before Python 3 was released, so it is just one of those differences between Python 2 and 3.
msg249641 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-03 14:09
I'm not sure the proper way to update the patch... I can't seem to edit the existing one or replace it.  I'm uploading an updated one, but should I simply "unlink" (aka delete) the old one?
msg249646 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-03 14:25
Martin, the odd thing with the SCO protocol is it's expecting an bluetooth address as a byte string (ex b'12:23:34:45:56:67' [note the `b`]) where the other 3 are expecting a regular string (ex '12:23:34:45:56:67').  I think it may have been a case of someone doing a blanket search-and-replace and missing the consequences there, but I'm really not sure.  However, this is somewhat besides the point as right now I'm trying to focus on just documenting the actual behaviour.  ;)

The issue is, what versions have the changes from 23ab586c427a in it, and what versions come before that where it's probably expecting a regular string.  Unfortunately I can't access the web interface for the repo at the moment so I can't even try to figure that out at right now.  (Though, I haven't confirmed that the old method was looking at regular strings or not...)
msg249647 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-03 14:33
I'm not really sure how to add a `versionadded` tag to specify that only the BSD-specific support was added in 3.2 (as general support was there prior to that).  If I just add the plain tag below that bullet point it would imply that the whole protocol was added in 3.2 .

Perhaps I should reword it to just list the original (prior to 3.2) documentation, then add the difference with BSD in a separate paragraph such that I can tag just that part?  Or maybe I shouldn't bother?
msg249653 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-03 15:03
I added a note to BTPROTO_SCO that it doesn't work in FreeBSD (I forgot to mention that).
msg249659 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-03 15:23
changed "This protocol does not work under FreeBSD." to the more accurate "This protocol is not supported under FreeBSD."
msg249667 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-09-03 15:55
Uploading new patches is correct.  We generally don't unlink the old ones unless the history starts to get really confusing.
msg249896 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-05 05:51
Here is a suggestion of how to add a versionchanged tag. Let me know if it is accurate or not. (I’m not actually familiar with the history.)
msg250204 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-08 13:58
Martin, looks good.  Thanks for pointing out how to properly tag the version change, and thanks for adding me to the ACKS file.
msg250293 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-09-09 06:59
New changeset da9b26670e44 by Martin Panter <vadmium> in branch '3.4':
Issue #24984: Document AF_BLUETOOTH socket address formats
https://hg.python.org/cpython/rev/da9b26670e44

New changeset 4ce8450da22d by Martin Panter <vadmium> in branch '3.5':
Issue #24984: Merge 3.4 into 3.5
https://hg.python.org/cpython/rev/4ce8450da22d

New changeset ec4ba0cb1ce0 by Martin Panter <vadmium> in branch 'default':
Issue #24984: Merge 3.5 into 3.6
https://hg.python.org/cpython/rev/ec4ba0cb1ce0
msg250298 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2015-09-09 09:13
Thanks for the patch, Tim. I think we can also create separate issues for AF_PACKET and AF_CAN and mark them as "easy".
msg250309 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-09 13:13
I created #25041 to handle AF_PACKET.  It seems AF_CAN is already in the docs, so the person making the change for AF_PACKET can just remove that mention of AF_CAN farther down.
msg250339 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-09 22:52
Hello again. The patch I committed says BTPROTO_SCO accepts a bytes-like object. However I suspect it is actually restricted to bytes only:

>>> s = socket(AF_BLUETOOTH, SOCK_SEQPACKET, BTPROTO_SCO)
>>> s.bind(bytearray(b"12:23:34:45:56:67"))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OSError: getsockaddrarg: wrong format
>>> s.bind(b"12:23:34:45:56:67")

If you can confirm this, I will update the documentation.
msg250369 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-10 13:14
oops.  yeah, I got my terminology wrong.  It accepts only a byte-string.
msg250437 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-09-11 02:36
New changeset 00db99149cdd by Martin Panter <vadmium> in branch '3.4':
Issue #24984: BTPROTO_SCO supports only bytes objects
https://hg.python.org/cpython/rev/00db99149cdd

New changeset b507a7e79154 by Martin Panter <vadmium> in branch '3.5':
Issue #24984: Merge BTPROTO_SCO doc fix from 3.4 into 3.5
https://hg.python.org/cpython/rev/b507a7e79154

New changeset 7e4391155d9c by Martin Panter <vadmium> in branch 'default':
Issue #24984: Merge BTPROTO_SCO doc fix from 3.5
https://hg.python.org/cpython/rev/7e4391155d9c
History
Date User Action Args
2015-09-11 02:37:33martin.pantersetstatus: open -> closed
2015-09-11 02:36:39python-devsetmessages: + msg250437
2015-09-10 13:14:14Tim.Tisdallsetmessages: + msg250369
2015-09-09 22:52:01martin.pantersetstatus: closed -> open

messages: + msg250339
2015-09-09 13:13:12Tim.Tisdallsetmessages: + msg250309
2015-09-09 09:13:10berker.peksagsetstatus: open -> closed
type: enhancement
messages: + msg250298

resolution: fixed
stage: patch review -> resolved
2015-09-09 06:59:28python-devsetnosy: + python-dev
messages: + msg250293
2015-09-09 06:50:05martin.pantersetnosy: + berker.peksag
2015-09-08 13:58:31Tim.Tisdallsetmessages: + msg250204
2015-09-05 05:51:03martin.pantersetfiles: + bluetooth_socket_docs_5.patch

messages: + msg249896
2015-09-03 15:55:41r.david.murraysetnosy: + r.david.murray
messages: + msg249667
2015-09-03 15:23:45Tim.Tisdallsetfiles: + bluetooth_socket_docs_4.patch

messages: + msg249659
2015-09-03 15:03:17Tim.Tisdallsetfiles: + bluetooth_socket_docs_3.patch

messages: + msg249653
2015-09-03 14:33:29Tim.Tisdallsetmessages: + msg249647
2015-09-03 14:25:50Tim.Tisdallsetmessages: + msg249646
2015-09-03 14:09:11Tim.Tisdallsetfiles: + bluetooth_socket_docs_2.patch

messages: + msg249641
2015-09-02 22:35:00martin.pantersetversions: + Python 3.4, Python 3.5, Python 3.6
nosy: + martin.panter

messages: + msg249580

stage: patch review
2015-09-02 16:06:50Tim.Tisdallcreate