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!

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.

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?

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...)

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?

I added a note to BTPROTO_SCO that it doesn't work in FreeBSD (I forgot to mention that).

changed "This protocol does not work under FreeBSD." to the more accurate "This protocol is not supported under FreeBSD."

Uploading new patches is correct.  We generally don't unlink the old ones unless the history starts to get really confusing.

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.)

Martin, looks good.  Thanks for pointing out how to properly tag the version change, and thanks for adding me to the ACKS file.

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

Thanks for the patch, Tim. I think we can also create separate issues for AF_PACKET and AF_CAN and mark them as "easy".

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.

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.

oops.  yeah, I got my terminology wrong.  It accepts only a byte-string.

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