Title: document socket constants for Bluetooth
Type: enhancement Stage: resolved
Components: Documentation, Library (Lib) Versions: Python 3.6, Python 3.4, Python 3.5
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: martin.panter Nosy List: Tim.Tisdall, berker.peksag, docs@python, martin.panter, python-dev
Priority: normal Keywords: patch

Created on 2015-09-09 15:00 by Tim.Tisdall, last changed 2015-09-11 23:33 by martin.panter. This issue is now closed.

File name Uploaded Description Edit
bdaddr_36_1.patch Tim.Tisdall, 2015-09-10 13:09 review
bdaddr_34_1.patch Tim.Tisdall, 2015-09-10 13:10
bdaddr_35_1.patch Tim.Tisdall, 2015-09-10 13:11
bdaddr_36_2.patch Tim.Tisdall, 2015-09-11 13:50
Messages (8)
msg250314 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-09 15:00
further to #24984, I noticed there are constants that aren't mentioned in the docs.  Also BDADDR_ALL is missing (which is defined in Bluez's bluetooth.h) so I added it.

Now, I'm not totally clear on supplying multi-version patches...  I know 3.5 is in "freeze" so I'm guessing adding the BDADDR_ALL constant is a no-no.  I guess I checkout out the different version branches, make the changes, and then create a patch labelled for which version it's for?  (I see the patch has the hash for which commit it's to be applied to, but not which branch)

The repo is down right now, so I'll include a patch once I can update my local copy...  :(
msg250338 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-09 22:29
The new constant would probably have to go into 3.6 only. I suggest make two patches: your documentation patch to be applied to 3.4+, and the new constant, against 3.6 only. Also, it would be good to get a unit test for the new constant.
msg250368 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-10 13:02
I'm not sure how to unit test a constant...  it's just a string.  If you're asking for a unit test for when you'd actually make use of the constant, I haven't been able to figure out that situation yet.  It seems like in Bluez 4.101 it's used to issue a command to all interfaces (but in contexts I don't quite understand), but in Bluez 5.XX there's no example or documentation of its use (it remains as a constant, though).  [looking through the Bluez git, I found where the constant was added in 2004 and the log message is simply "Add BDADDR_ALL constant"; ]
msg250430 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-10 23:27
Well if the constant is not very useful then maybe we shouldn’t add it :)

For testing, nothing complicated. Maybe check the module attributes exist, and are strings. In the past, people have converted module-level constants to enums, and introduced a typo in a name along the way. Even the simplest test case would pick up this sort of typo.
msg250472 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-11 13:50
Okay, since there's currently no existing tests for the Bluetooth components of socket and the only example for BDADDR_ALL seems to be for something I'm not sure you can do in socket, I'm just going to not bother including it.

I've attached a 3.6 patch without BDADDR_ALL.
msg250475 - (view) Author: Tim Tisdall (Tim.Tisdall) * Date: 2015-09-11 14:30
okay, I talked to one of the Bluez developers and he recommended leaving out BDADDR_ALL since it doesn't seem to correspond to anything in the kernel.
msg250498 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-11 21:36
Thanks for your work on this. I think the patch is good, although I might add :const:`BDADDR_ANY` etc markup around the references within the text.

By the way, you don’t normally need to make separate patches for each branch. When I commit this I will just apply the 3.4 version, and then automatically merging to the other branches should be trivial.
msg250501 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-09-11 23:32
New changeset 152568976062 by Martin Panter <vadmium> in branch '3.4':
Issue #25043: Document BDADDR_ and HCI_ Bluetooth socket constants

New changeset 3f475417eadd by Martin Panter <vadmium> in branch '3.5':
Issue #25043: Merge Bluetooth doc from 3.4 into 3.5

New changeset 5325233f117d by Martin Panter <vadmium> in branch 'default':
Issue #25043: Merge Bluetooth doc from 3.5
Date User Action Args
2015-09-11 23:33:48martin.pantersetstatus: open -> closed
resolution: fixed
stage: commit review -> resolved
2015-09-11 23:32:13python-devsetnosy: + python-dev
messages: + msg250501
2015-09-11 21:36:19martin.pantersetnosy: + berker.peksag
messages: + msg250498

assignee: docs@python -> martin.panter
stage: commit review
2015-09-11 14:30:57Tim.Tisdallsetmessages: + msg250475
2015-09-11 13:50:45Tim.Tisdallsetfiles: + bdaddr_36_2.patch

messages: + msg250472
2015-09-10 23:27:10martin.pantersetmessages: + msg250430
2015-09-10 13:11:15Tim.Tisdallsetfiles: + bdaddr_35_1.patch
2015-09-10 13:10:04Tim.Tisdallsetfiles: + bdaddr_34_1.patch
2015-09-10 13:09:54Tim.Tisdallsetfiles: + bdaddr_36_1.patch
keywords: + patch
2015-09-10 13:02:37Tim.Tisdallsetmessages: + msg250368
2015-09-09 22:29:34martin.pantersetnosy: + martin.panter
messages: + msg250338
2015-09-09 15:00:39Tim.Tisdallcreate