We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
Either documentation or behavior with a second Unifying Receiver - How to specify?
Arch Linux
solaar-git 1.0.5rc2.r0.g8d01e28-1
2021 Feb 20

Suppose you have, for instance, a second Unifying Receiver that you want to pair with a particular device, perhaps before moving the second receiver and the paired device to another machine.

To specify and pair that particular device with a specific Unifying Receiver, when there is more than one receiver, and consulting the embedded documentation, compare:
```
$ solaar pair --help
usage: solaar pair [-h] [receiver]

positional arguments:
  receiver    select a certain receiver when more than one is present

optional arguments:
  -h, --help  show this help message and exit

The Logitech Unifying Receiver supports up to 6 paired devices at the same time.1 Feb 20
```
versus:
```
$ solaar --help
usage: solaar [-h] [-d] [-D PATH] [--restart-on-wake-up] [-w {show,hide,only}] [-b {regular,symbolic,solaar}] [-V] [--help-actions] ...

positional arguments:
  {show,probe,config,pair,unpair}
                        optional actions to perform

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           print logging messages, for debugging purposes (may be repeated for extra verbosity)
  -D PATH, --hidraw PATH
                        unifying receiver to use; the first detected receiver if unspecified. Example: /dev/hidraw2
  --restart-on-wake-up  restart Solaar on sleep wake-up (experimental)
  -w {show,hide,only}, --window {show,hide,only}
                        start with window showing / hidden / only (no tray icon)
  -b {regular,symbolic,solaar}, --battery-icons {regular,symbolic,solaar}
                        prefer regular battery / symbolic battery / solaar icons
  -V, --version         show program's version number and exit
  --help-actions        print help for the optional actions
```

Note that, currently, the first approach fails - assuming that the receiver is selected using its Serial number, found with `solaar show` - giving:
```
$ solaar pair xxxxxxxx
solaar: error: Traceback (most recent call last):
  File "/usr/lib/python3.9/site-packages/solaar/cli/__init__.py", line 202, in run
    m.run(c, args, _find_receiver, _find_device)
  File "/usr/lib/python3.9/site-packages/solaar/cli/pair.py", line 35, in run
    receiver = find_receiver(receiver_name)
TypeError: _find_receiver() missing 1 required positional argument: 'name'
```
Well, no, the "1 required positional argument" was not "missing", it was just not recognized.  Using "Device path" as the name, instead of "Serial", produces the same failed result.

Instead, the second approach does work:
```
$ solaar -D /dev/hidraw0 pair
Pairing: turn your new device on (timing out in 20 seconds).
Paired device 1: Wireless Mouse M525 (M525) [4013:xxxxxxxx]
```

So, what is the preferred behavior?  If the device path switch approach is preferred, then the `solaar pair --help` usage message should be revised.  If, instead, the original `solaar pair [-h] [receiver]` approach is preferred, then that would suggest that the device path switch approach should be reverted.  I expect that there was a good reason to implement the device path switch approach, which maybe implies that the original `solaar pair [-h] [receiver]` approach is now deprecated.

It just seems that `/usr/lib/python3.9/site-packages/solaar/cli/pair.py` is still expecting `find_receiver(receiver_name)`, so, a little confusing.  I haven't tried to grok the code, but I do notice there is still:
```
/usr/lib/python3.9/site-packages/solaar/cli/__init__.py
def _find_receiver(receivers, name):
    assert receivers
    assert name

    for r in receivers:
        if name in r.name.lower() or (r.serial is not None and name == r.serial.lower()):
            return r
```

Maybe someone can take a look at all this and see what is going on?

--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `lib/solaar/cli/pair.py`
Content:
```
1 # -*- python-mode -*-
2 # -*- coding: UTF-8 -*-
3 
4 ## Copyright (C) 2012-2013  Daniel Pavel
5 ##
6 ## This program is free software; you can redistribute it and/or modify
7 ## it under the terms of the GNU General Public License as published by
8 ## the Free Software Foundation; either version 2 of the License, or
9 ## (at your option) any later version.
10 ##
11 ## This program is distributed in the hope that it will be useful,
12 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 ## GNU General Public License for more details.
15 ##
16 ## You should have received a copy of the GNU General Public License along
17 ## with this program; if not, write to the Free Software Foundation, Inc.,
18 ## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 
20 from __future__ import absolute_import, division, print_function, unicode_literals
21 
22 from time import time as _timestamp
23 
24 from logitech_receiver import base as _base
25 from logitech_receiver import hidpp10 as _hidpp10
26 from logitech_receiver import notifications as _notifications
27 from logitech_receiver import status as _status
28 
29 
30 def run(receivers, args, find_receiver, _ignore):
31     assert receivers
32 
33     if args.receiver:
34         receiver_name = args.receiver.lower()
35         receiver = find_receiver(receiver_name)
36         if not receiver:
37             raise Exception("no receiver found matching '%s'" % receiver_name)
38     else:
39         receiver = receivers[0]
40 
41     assert receiver
42     receiver.status = _status.ReceiverStatus(receiver, lambda *args, **kwargs: None)
43 
44     # check if it's necessary to set the notification flags
45     old_notification_flags = _hidpp10.get_notification_flags(receiver) or 0
46     if not (old_notification_flags & _hidpp10.NOTIFICATION_FLAG.wireless):
47         _hidpp10.set_notification_flags(receiver, old_notification_flags | _hidpp10.NOTIFICATION_FLAG.wireless)
48 
49     # get all current devices
50     known_devices = [dev.number for dev in receiver]
51 
52     class _HandleWithNotificationHook(int):
53         def notifications_hook(self, n):
54             nonlocal known_devices
55             assert n
56             if n.devnumber == 0xFF:
57                 _notifications.process(receiver, n)
58             elif n.sub_id == 0x41 and len(n.data) == _base._SHORT_MESSAGE_SIZE - 4:
59                 kd, known_devices = known_devices, None  # only process one connection notification
60                 if kd is not None:
61                     if n.devnumber not in kd:
62                         receiver.status.new_device = receiver.register_new_device(n.devnumber, n)
63                     elif receiver.re_pairs:
64                         del receiver[n.devnumber]  # get rid of information on device re-paired away
65                         receiver.status.new_device = receiver.register_new_device(n.devnumber, n)
66 
67     timeout = 20  # seconds
68     receiver.handle = _HandleWithNotificationHook(receiver.handle)
69 
70     receiver.set_lock(False, timeout=timeout)
71     print('Pairing: turn your new device on (timing out in', timeout, 'seconds).')
72 
73     # the lock-open notification may come slightly later, wait for it a bit
74     pairing_start = _timestamp()
75     patience = 5  # seconds
76 
77     while receiver.status.lock_open or _timestamp() - pairing_start < patience:
78         n = _base.read(receiver.handle)
79         if n:
80             n = _base.make_notification(*n)
81             if n:
82                 receiver.handle.notifications_hook(n)
83 
84     if not (old_notification_flags & _hidpp10.NOTIFICATION_FLAG.wireless):
85         # only clear the flags if they weren't set before, otherwise a
86         # concurrently running Solaar app might stop working properly
87         _hidpp10.set_notification_flags(receiver, old_notification_flags)
88 
89     if receiver.status.new_device:
90         dev = receiver.status.new_device
91         print('Paired device %d: %s (%s) [%s:%s]' % (dev.number, dev.name, dev.codename, dev.wpid, dev.serial))
92     else:
93         error = receiver.status.get(_status.KEYS.ERROR)
94         if error:
95             raise Exception('pairing failed: %s' % error)
96         else:
97             print('Paired a device')  # this is better than an error
98
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/lib/solaar/cli/pair.py b/lib/solaar/cli/pair.py
--- a/lib/solaar/cli/pair.py
+++ b/lib/solaar/cli/pair.py
@@ -32,7 +32,7 @@
 
     if args.receiver:
         receiver_name = args.receiver.lower()
-        receiver = find_receiver(receiver_name)
+        receiver = find_receiver(receivers, receiver_name)
         if not receiver:
             raise Exception("no receiver found matching '%s'" % receiver_name)
     else:

{"golden_diff": "diff --git a/lib/solaar/cli/pair.py b/lib/solaar/cli/pair.py\n--- a/lib/solaar/cli/pair.py\n+++ b/lib/solaar/cli/pair.py\n@@ -32,7 +32,7 @@\n \n     if args.receiver:\n         receiver_name = args.receiver.lower()\n-        receiver = find_receiver(receiver_name)\n+        receiver = find_receiver(receivers, receiver_name)\n         if not receiver:\n             raise Exception(\"no receiver found matching '%s'\" % receiver_name)\n     else:\n", "issue": "Either documentation or behavior with a second Unifying Receiver - How to specify?\nArch Linux\r\nsolaar-git 1.0.5rc2.r0.g8d01e28-1\r\n2021 Feb 20\r\n\r\nSuppose you have, for instance, a second Unifying Receiver that you want to pair with a particular device, perhaps before moving the second receiver and the paired device to another machine.\r\n\r\nTo specify and pair that particular device with a specific Unifying Receiver, when there is more than one receiver, and consulting the embedded documentation, compare:\r\n```\r\n$ solaar pair --help\r\nusage: solaar pair [-h] [receiver]\r\n\r\npositional arguments:\r\n  receiver    select a certain receiver when more than one is present\r\n\r\noptional arguments:\r\n  -h, --help  show this help message and exit\r\n\r\nThe Logitech Unifying Receiver supports up to 6 paired devices at the same time.1 Feb 20\r\n```\r\nversus:\r\n```\r\n$ solaar --help\r\nusage: solaar [-h] [-d] [-D PATH] [--restart-on-wake-up] [-w {show,hide,only}] [-b {regular,symbolic,solaar}] [-V] [--help-actions] ...\r\n\r\npositional arguments:\r\n  {show,probe,config,pair,unpair}\r\n                        optional actions to perform\r\n\r\noptional arguments:\r\n  -h, --help            show this help message and exit\r\n  -d, --debug           print logging messages, for debugging purposes (may be repeated for extra verbosity)\r\n  -D PATH, --hidraw PATH\r\n                        unifying receiver to use; the first detected receiver if unspecified. Example: /dev/hidraw2\r\n  --restart-on-wake-up  restart Solaar on sleep wake-up (experimental)\r\n  -w {show,hide,only}, --window {show,hide,only}\r\n                        start with window showing / hidden / only (no tray icon)\r\n  -b {regular,symbolic,solaar}, --battery-icons {regular,symbolic,solaar}\r\n                        prefer regular battery / symbolic battery / solaar icons\r\n  -V, --version         show program's version number and exit\r\n  --help-actions        print help for the optional actions\r\n```\r\n\r\nNote that, currently, the first approach fails - assuming that the receiver is selected using its Serial number, found with `solaar show` - giving:\r\n```\r\n$ solaar pair xxxxxxxx\r\nsolaar: error: Traceback (most recent call last):\r\n  File \"/usr/lib/python3.9/site-packages/solaar/cli/__init__.py\", line 202, in run\r\n    m.run(c, args, _find_receiver, _find_device)\r\n  File \"/usr/lib/python3.9/site-packages/solaar/cli/pair.py\", line 35, in run\r\n    receiver = find_receiver(receiver_name)\r\nTypeError: _find_receiver() missing 1 required positional argument: 'name'\r\n```\r\nWell, no, the \"1 required positional argument\" was not \"missing\", it was just not recognized.  Using \"Device path\" as the name, instead of \"Serial\", produces the same failed result.\r\n\r\nInstead, the second approach does work:\r\n```\r\n$ solaar -D /dev/hidraw0 pair\r\nPairing: turn your new device on (timing out in 20 seconds).\r\nPaired device 1: Wireless Mouse M525 (M525) [4013:xxxxxxxx]\r\n```\r\n\r\nSo, what is the preferred behavior?  If the device path switch approach is preferred, then the `solaar pair --help` usage message should be revised.  If, instead, the original `solaar pair [-h] [receiver]` approach is preferred, then that would suggest that the device path switch approach should be reverted.  I expect that there was a good reason to implement the device path switch approach, which maybe implies that the original `solaar pair [-h] [receiver]` approach is now deprecated.\r\n\r\nIt just seems that `/usr/lib/python3.9/site-packages/solaar/cli/pair.py` is still expecting `find_receiver(receiver_name)`, so, a little confusing.  I haven't tried to grok the code, but I do notice there is still:\r\n```\r\n/usr/lib/python3.9/site-packages/solaar/cli/__init__.py\r\ndef _find_receiver(receivers, name):\r\n    assert receivers\r\n    assert name\r\n\r\n    for r in receivers:\r\n        if name in r.name.lower() or (r.serial is not None and name == r.serial.lower()):\r\n            return r\r\n```\r\n\r\nMaybe someone can take a look at all this and see what is going on?\n", "before_files": [{"content": "# -*- python-mode -*-\n# -*- coding: UTF-8 -*-\n\n## Copyright (C) 2012-2013  Daniel Pavel\n##\n## This program is free software; you can redistribute it and/or modify\n## it under the terms of the GNU General Public License as published by\n## the Free Software Foundation; either version 2 of the License, or\n## (at your option) any later version.\n##\n## This program is distributed in the hope that it will be useful,\n## but WITHOUT ANY WARRANTY; without even the implied warranty of\n## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n## GNU General Public License for more details.\n##\n## You should have received a copy of the GNU General Public License along\n## with this program; if not, write to the Free Software Foundation, Inc.,\n## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n\nfrom __future__ import absolute_import, division, print_function, unicode_literals\n\nfrom time import time as _timestamp\n\nfrom logitech_receiver import base as _base\nfrom logitech_receiver import hidpp10 as _hidpp10\nfrom logitech_receiver import notifications as _notifications\nfrom logitech_receiver import status as _status\n\n\ndef run(receivers, args, find_receiver, _ignore):\n    assert receivers\n\n    if args.receiver:\n        receiver_name = args.receiver.lower()\n        receiver = find_receiver(receiver_name)\n        if not receiver:\n            raise Exception(\"no receiver found matching '%s'\" % receiver_name)\n    else:\n        receiver = receivers[0]\n\n    assert receiver\n    receiver.status = _status.ReceiverStatus(receiver, lambda *args, **kwargs: None)\n\n    # check if it's necessary to set the notification flags\n    old_notification_flags = _hidpp10.get_notification_flags(receiver) or 0\n    if not (old_notification_flags & _hidpp10.NOTIFICATION_FLAG.wireless):\n        _hidpp10.set_notification_flags(receiver, old_notification_flags | _hidpp10.NOTIFICATION_FLAG.wireless)\n\n    # get all current devices\n    known_devices = [dev.number for dev in receiver]\n\n    class _HandleWithNotificationHook(int):\n        def notifications_hook(self, n):\n            nonlocal known_devices\n            assert n\n            if n.devnumber == 0xFF:\n                _notifications.process(receiver, n)\n            elif n.sub_id == 0x41 and len(n.data) == _base._SHORT_MESSAGE_SIZE - 4:\n                kd, known_devices = known_devices, None  # only process one connection notification\n                if kd is not None:\n                    if n.devnumber not in kd:\n                        receiver.status.new_device = receiver.register_new_device(n.devnumber, n)\n                    elif receiver.re_pairs:\n                        del receiver[n.devnumber]  # get rid of information on device re-paired away\n                        receiver.status.new_device = receiver.register_new_device(n.devnumber, n)\n\n    timeout = 20  # seconds\n    receiver.handle = _HandleWithNotificationHook(receiver.handle)\n\n    receiver.set_lock(False, timeout=timeout)\n    print('Pairing: turn your new device on (timing out in', timeout, 'seconds).')\n\n    # the lock-open notification may come slightly later, wait for it a bit\n    pairing_start = _timestamp()\n    patience = 5  # seconds\n\n    while receiver.status.lock_open or _timestamp() - pairing_start < patience:\n        n = _base.read(receiver.handle)\n        if n:\n            n = _base.make_notification(*n)\n            if n:\n                receiver.handle.notifications_hook(n)\n\n    if not (old_notification_flags & _hidpp10.NOTIFICATION_FLAG.wireless):\n        # only clear the flags if they weren't set before, otherwise a\n        # concurrently running Solaar app might stop working properly\n        _hidpp10.set_notification_flags(receiver, old_notification_flags)\n\n    if receiver.status.new_device:\n        dev = receiver.status.new_device\n        print('Paired device %d: %s (%s) [%s:%s]' % (dev.number, dev.name, dev.codename, dev.wpid, dev.serial))\n    else:\n        error = receiver.status.get(_status.KEYS.ERROR)\n        if error:\n            raise Exception('pairing failed: %s' % error)\n        else:\n            print('Paired a device')  # this is better than an error\n", "path": "lib/solaar/cli/pair.py"}], "after_files": [{"content": "# -*- python-mode -*-\n# -*- coding: UTF-8 -*-\n\n## Copyright (C) 2012-2013  Daniel Pavel\n##\n## This program is free software; you can redistribute it and/or modify\n## it under the terms of the GNU General Public License as published by\n## the Free Software Foundation; either version 2 of the License, or\n## (at your option) any later version.\n##\n## This program is distributed in the hope that it will be useful,\n## but WITHOUT ANY WARRANTY; without even the implied warranty of\n## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n## GNU General Public License for more details.\n##\n## You should have received a copy of the GNU General Public License along\n## with this program; if not, write to the Free Software Foundation, Inc.,\n## 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n\nfrom __future__ import absolute_import, division, print_function, unicode_literals\n\nfrom time import time as _timestamp\n\nfrom logitech_receiver import base as _base\nfrom logitech_receiver import hidpp10 as _hidpp10\nfrom logitech_receiver import notifications as _notifications\nfrom logitech_receiver import status as _status\n\n\ndef run(receivers, args, find_receiver, _ignore):\n    assert receivers\n\n    if args.receiver:\n        receiver_name = args.receiver.lower()\n        receiver = find_receiver(receivers, receiver_name)\n        if not receiver:\n            raise Exception(\"no receiver found matching '%s'\" % receiver_name)\n    else:\n        receiver = receivers[0]\n\n    assert receiver\n    receiver.status = _status.ReceiverStatus(receiver, lambda *args, **kwargs: None)\n\n    # check if it's necessary to set the notification flags\n    old_notification_flags = _hidpp10.get_notification_flags(receiver) or 0\n    if not (old_notification_flags & _hidpp10.NOTIFICATION_FLAG.wireless):\n        _hidpp10.set_notification_flags(receiver, old_notification_flags | _hidpp10.NOTIFICATION_FLAG.wireless)\n\n    # get all current devices\n    known_devices = [dev.number for dev in receiver]\n\n    class _HandleWithNotificationHook(int):\n        def notifications_hook(self, n):\n            nonlocal known_devices\n            assert n\n            if n.devnumber == 0xFF:\n                _notifications.process(receiver, n)\n            elif n.sub_id == 0x41 and len(n.data) == _base._SHORT_MESSAGE_SIZE - 4:\n                kd, known_devices = known_devices, None  # only process one connection notification\n                if kd is not None:\n                    if n.devnumber not in kd:\n                        receiver.status.new_device = receiver.register_new_device(n.devnumber, n)\n                    elif receiver.re_pairs:\n                        del receiver[n.devnumber]  # get rid of information on device re-paired away\n                        receiver.status.new_device = receiver.register_new_device(n.devnumber, n)\n\n    timeout = 20  # seconds\n    receiver.handle = _HandleWithNotificationHook(receiver.handle)\n\n    receiver.set_lock(False, timeout=timeout)\n    print('Pairing: turn your new device on (timing out in', timeout, 'seconds).')\n\n    # the lock-open notification may come slightly later, wait for it a bit\n    pairing_start = _timestamp()\n    patience = 5  # seconds\n\n    while receiver.status.lock_open or _timestamp() - pairing_start < patience:\n        n = _base.read(receiver.handle)\n        if n:\n            n = _base.make_notification(*n)\n            if n:\n                receiver.handle.notifications_hook(n)\n\n    if not (old_notification_flags & _hidpp10.NOTIFICATION_FLAG.wireless):\n        # only clear the flags if they weren't set before, otherwise a\n        # concurrently running Solaar app might stop working properly\n        _hidpp10.set_notification_flags(receiver, old_notification_flags)\n\n    if receiver.status.new_device:\n        dev = receiver.status.new_device\n        print('Paired device %d: %s (%s) [%s:%s]' % (dev.number, dev.name, dev.codename, dev.wpid, dev.serial))\n    else:\n        error = receiver.status.get(_status.KEYS.ERROR)\n        if error:\n            raise Exception('pairing failed: %s' % error)\n        else:\n            print('Paired a device')  # this is better than an error\n", "path": "lib/solaar/cli/pair.py"}]}