From 9ad9c064df2eea02f83edecfbf2216f1a949ca8a Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sat, 5 Apr 2025 11:44:09 +0300 Subject: [PATCH 1/6] gh-132099: Fix documentation for the BTPROTO_HCI protocol --- Doc/library/socket.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 1bc7f76b5ba694..d7aeb670860817 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -154,14 +154,19 @@ created. Socket addresses are represented as follows: - :const:`BTPROTO_RFCOMM` accepts ``(bdaddr, channel)`` where ``bdaddr`` is the Bluetooth address as a string and ``channel`` is an integer. - - :const:`BTPROTO_HCI` accepts ``(device_id,)`` where ``device_id`` is - either an integer or a string with the Bluetooth address of the - interface. (This depends on your OS; NetBSD and DragonFlyBSD expect - a Bluetooth address while everything else expects an integer.) + - :const:`BTPROTO_HCI` accepts format that depends on your OS. + On FreeBSD, NetBSD and DragonFlyBSD it accepts ``bdaddr`` where ``bdaddr`` + is a :class:`bytes` object containing the Bluetooth address in a + string format. (ex. ``b'12:23:34:45:56:67'``) + On Linux it accepts a tuple ``(device_id,)`` where ``device_id`` + is an integer specifying the number of the Bluetooth device. .. versionchanged:: 3.2 NetBSD and DragonFlyBSD support added. + .. versionchanged:: 3.13.3 + FreeBSD support added. + - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is a :class:`bytes` object containing the Bluetooth address in a string format. (ex. ``b'12:23:34:45:56:67'``) This protocol is not From 1c32480316ddcff2ba1f6720cfc6cc2333d71d14 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sat, 5 Apr 2025 15:00:12 +0300 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/socket.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index d7aeb670860817..f7b5e969aa30f9 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -154,12 +154,12 @@ created. Socket addresses are represented as follows: - :const:`BTPROTO_RFCOMM` accepts ``(bdaddr, channel)`` where ``bdaddr`` is the Bluetooth address as a string and ``channel`` is an integer. - - :const:`BTPROTO_HCI` accepts format that depends on your OS. - On FreeBSD, NetBSD and DragonFlyBSD it accepts ``bdaddr`` where ``bdaddr`` - is a :class:`bytes` object containing the Bluetooth address in a - string format. (ex. ``b'12:23:34:45:56:67'``) - On Linux it accepts a tuple ``(device_id,)`` where ``device_id`` - is an integer specifying the number of the Bluetooth device. + - :const:`BTPROTO_HCI` accepts a format that depends on your OS. + - On FreeBSD, NetBSD and DragonFlyBSD it accepts ``bdaddr`` where ``bdaddr`` + is a :class:`bytes` object containing the Bluetooth address in a + string format. (ex. ``b'12:23:34:45:56:67'``) + - On Linux it accepts a tuple ``(device_id,)`` where ``device_id`` + is an integer specifying the number of the Bluetooth device. .. versionchanged:: 3.2 NetBSD and DragonFlyBSD support added. From e17e43e690037d79cd9f499d0c47dac685f5b0cf Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sat, 5 Apr 2025 15:46:11 +0300 Subject: [PATCH 3/6] Update Doc/library/socket.rst Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/library/socket.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index f7b5e969aa30f9..b947078961cf86 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -155,6 +155,7 @@ created. Socket addresses are represented as follows: is the Bluetooth address as a string and ``channel`` is an integer. - :const:`BTPROTO_HCI` accepts a format that depends on your OS. + - On FreeBSD, NetBSD and DragonFlyBSD it accepts ``bdaddr`` where ``bdaddr`` is a :class:`bytes` object containing the Bluetooth address in a string format. (ex. ``b'12:23:34:45:56:67'``) From 0e8b750d855e4524f8dc43eb195048a8e4fd27b8 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sat, 5 Apr 2025 15:52:18 +0300 Subject: [PATCH 4/6] Update Doc/library/socket.rst --- Doc/library/socket.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index b947078961cf86..f7b5e969aa30f9 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -155,7 +155,6 @@ created. Socket addresses are represented as follows: is the Bluetooth address as a string and ``channel`` is an integer. - :const:`BTPROTO_HCI` accepts a format that depends on your OS. - - On FreeBSD, NetBSD and DragonFlyBSD it accepts ``bdaddr`` where ``bdaddr`` is a :class:`bytes` object containing the Bluetooth address in a string format. (ex. ``b'12:23:34:45:56:67'``) From 7bd9d0639dfa7ca5a86e59757b011c53bdc31e07 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sat, 5 Apr 2025 15:58:22 +0300 Subject: [PATCH 5/6] Clean up. --- Doc/library/socket.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index f7b5e969aa30f9..85c8ad51b7152b 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -155,6 +155,7 @@ created. Socket addresses are represented as follows: is the Bluetooth address as a string and ``channel`` is an integer. - :const:`BTPROTO_HCI` accepts a format that depends on your OS. + - On FreeBSD, NetBSD and DragonFlyBSD it accepts ``bdaddr`` where ``bdaddr`` is a :class:`bytes` object containing the Bluetooth address in a string format. (ex. ``b'12:23:34:45:56:67'``) From 113b9b42b7fa6ade0f7e388d8c5bb6ec87b99063 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 13 Apr 2025 18:18:34 +0300 Subject: [PATCH 6/6] More tweaking. --- Doc/library/socket.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index bf526ece7242e1..2e38101c01d89d 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -149,18 +149,18 @@ created. Socket addresses are represented as follows: :const:`BDADDR_LE_RANDOM`. .. versionchanged:: 3.14 - Added ``cid`` and ``bdaddr_type`` fields. + Added ``cid`` and ``bdaddr_type`` fields. - :const:`BTPROTO_RFCOMM` accepts ``(bdaddr, channel)`` where ``bdaddr`` is the Bluetooth address as a string and ``channel`` is an integer. - :const:`BTPROTO_HCI` accepts a format that depends on your OS. - - On FreeBSD, NetBSD and DragonFlyBSD it accepts ``bdaddr`` where ``bdaddr`` - is a :class:`bytes` object containing the Bluetooth address in a - string format. (ex. ``b'12:23:34:45:56:67'``) - On Linux it accepts a tuple ``(device_id,)`` where ``device_id`` is an integer specifying the number of the Bluetooth device. + - On FreeBSD, NetBSD and DragonFly BSD it accepts ``bdaddr`` where ``bdaddr`` + is a :class:`bytes` object containing the Bluetooth address in a + string format. (ex. ``b'12:23:34:45:56:67'``) .. versionchanged:: 3.2 NetBSD and DragonFlyBSD support added. @@ -668,16 +668,15 @@ Constants These constants describe the Bluetooth address type when binding or connecting a :const:`BTPROTO_L2CAP` socket. - .. versionadded:: 3.14 + .. versionadded:: 3.14 .. data:: HCI_FILTER HCI_TIME_STAMP HCI_DATA_DIR - For use with :const:`BTPROTO_HCI`. :const:`HCI_FILTER` is not - available for NetBSD or DragonFlyBSD. :const:`HCI_TIME_STAMP` and - :const:`HCI_DATA_DIR` are not available for FreeBSD, NetBSD, or - DragonFlyBSD. + For use with :const:`BTPROTO_HCI`. :const:`!HCI_FILTER` is only + available on Linux and FreeBSD. :const:`!HCI_TIME_STAMP` and + :const:`!HCI_DATA_DIR` are only available on Linux. .. data:: AF_QIPCRTR