Merge remote-tracking branch 'origin/pr/304'

* origin/pr/304: (63 commits)
  q-dev: fix tests and pylint
  q-dev: less scary device category names
  q-dev: fix default behavior of qvm-device *CLASS*
  q-dev: update docs
  q-dev: do not suggest attaching pci devices
  q-dev: prettier device data printing
  q-dev: pylint + black
  q-dev: add short way to create DeviceAssignment
  q-dev: introduce AnyPort
  q-dev: minor device_protocol fixes
  q-dev: fix comparison of Ports
  q-dev: fix qvm-device
  q-dev: allow auto-attach of microphone
  q-dev: ignore mode of currently attached devices
  q-dev: add flag to device listing
  q-dev: allow mic auto-attachment
  q-dev: patching up qvm-device info
  q-dev: fixes corner cases in attach/assign
  q-dev: fixes of devices assignment fronted
  q-dev: fix loading devices in event handling
  ...

doc/manpages/qvm-device.rst

@@ -45,6 +45,10 @@ list
 
 List devices.
 
+.. option:: --assignments, -s
+
+   Include info about device assignments, indicated by '*' before qube name.
+
 .. option:: --all
 
    List devices from all qubes. You can use :option:`--exclude` to limit the
@@ -59,9 +63,11 @@ aliases: ls, l
 attach
 ^^^^^^
 
-| :command:`qvm-device` *DEVICE_CLASS* attach [-h] [--verbose] [--quiet] [--ro] *VMNAME* *BACKEND_DOMAIN:DEVICE_ID*
+| :command:`qvm-device` *DEVICE_CLASS* attach [-h] [--verbose] [--quiet] [--ro] *VMNAME* *BACKEND_DOMAIN:PORT_ID[:DEVICE_ID]*
 
-Attach the device with *DEVICE_ID* from *BACKEND_DOMAIN* to the domain *VMNAME*
+Attach the device from *BACKEND_DOMAIN* and port with *PORT_ID* to domain *VMNAME*.
+If optional *DEVICE_ID* is provided and does not match device ID of plugged device the attachment fails.
+The *DEVICE_ID* equals to `*` is ignored.
 
 .. option:: --option, -o
 
@@ -76,26 +82,30 @@ Attach the device with *DEVICE_ID* from *BACKEND_DOMAIN* to the domain *VMNAME*
 
 .. option:: --persistent, -p
 
-   Alias for `assign --required` for backward compatibility.
+   Short version for `attach` & `assign --required` for backward compatibility.
 
 aliases: a, at
 
 detach
 ^^^^^^
 
-| :command:`qvm-device` *DEVICE_CLASS* detach [-h] [--verbose] [--quiet] *VMNAME* *BACKEND_DOMAIN:DEVICE_ID*
+| :command:`qvm-device` *DEVICE_CLASS* detach [-h] [--verbose] [--quiet] *VMNAME* *BACKEND_DOMAIN:PORT_ID[:DEVICE_ID]*
 
-Detach the device with *BACKEND_DOMAIN:DEVICE_ID* from domain *VMNAME*.
+Detach the device with *BACKEND_DOMAIN:PORT_ID* from domain *VMNAME*.
+If optional *DEVICE_ID* is provided and does not match device ID of plugged device the detachment fails.
+The *DEVICE_ID* equals to `*` is ignored.
 If no device is given, detach all *DEVICE_CLASS* devices.
 
 aliases: d, dt
 
 assign
 ^^^^^^
 
-| :command:`qvm-device` *DEVICE_CLASS* assign [-h] [--verbose] [--quiet] [--ro] *VMNAME* *BACKEND_DOMAIN:DEVICE_ID*
+| :command:`qvm-device` *DEVICE_CLASS* assign [-h] [--verbose] [--quiet] [--ro] *VMNAME* *BACKEND_DOMAIN:PORT_ID[:DEVICE_ID]*
 
-Assign the device with *DEVICE_ID* from *BACKEND_DOMAIN* to the domain *VMNAME*
+Assign the device from *BACKEND_DOMAIN* and port with *PORT_ID* to domain *VMNAME*.
+If optional *DEVICE_ID* is not provided it device id of the plugged device is loaded.
+If *DEVICE_ID* is not provided and no device is currently plugged into the port, the assignment process will fail.
 
 .. option:: --option, -o
 
@@ -112,20 +122,40 @@ Assign the device with *DEVICE_ID* from *BACKEND_DOMAIN* to the domain *VMNAME*
 
    Assign device persistently which means it will be required to the qube's startup and then automatically attached.
 
-.. option:: --port
+.. option:: --ask, --ask-to-attach
+
+   Assign device but always ask before auto-attachment.
+
+.. option:: --port, --only-port
+
+   Ignore device presented identity and attach automatically any device connected to this port in the future.
+   It is equivalent of providing `BACKEND_DOMAIN:PORT_ID:*` as argument.
 
-   Ignore device presented identity and attach any device connected to the given port number.
+.. option:: --device, --only-device
+
+   Ignore the current port where the device is plugged in and ensure that this device will be attached automatically in the future, regardless of which port it is connected to.
+   It is equivalent of providing `BACKEND_DOMAIN:*:DEVICE_ID` as argument.
 
 aliases: s
 
 unassign
 ^^^^^^^^
 
-| :command:`qvm-device` *DEVICE_CLASS* unassign [-h] [--verbose] [--quiet] *VMNAME* *BACKEND_DOMAIN:DEVICE_ID*
+| :command:`qvm-device` *DEVICE_CLASS* unassign [-h] [--verbose] [--quiet] *VMNAME* *BACKEND_DOMAIN:PORT_ID[:DEVICE_ID]*
 
-Remove assignment of device with *BACKEND_DOMAIN:DEVICE_ID* from domain *VMNAME*.
+Remove assignment of device with *BACKEND_DOMAIN:PORT_ID:DEVICE_ID* from domain *VMNAME*.
 If no device is given, remove assignments of all *DEVICE_CLASS* devices.
 
+.. option:: --port, --only-port
+
+   Remove port assignment.
+   It is equivalent of providing `BACKEND_DOMAIN:PORT_ID:*` as argument.
+
+.. option:: --device, --only-device
+
+   Remove device identity based assignment.
+   It is equivalent of providing `BACKEND_DOMAIN:*:DEVICE_ID` as argument.
+
 aliases: u
 
 info
@@ -137,8 +167,8 @@ Show info about the device with *DEVICE_ID* from *BACKEND_DOMAIN* attached to th
 
 aliases: i
 
-Device classes
-==============
+Port classes
+============
 
 block
 ^^^^^

qubesadmin/backup/core2.py

@@ -336,10 +336,10 @@ def import_core2_vm(self, element):
         if pcidevs:
             pcidevs = ast.literal_eval(pcidevs)
         for pcidev in pcidevs:
-            ident = pcidev.replace(':', '_')
+            port_id = pcidev.replace(':', '_')
             options = {'no-strict-reset': True} if not pci_strictreset else {}
             options['required'] = True
-            vm.devices['pci'][('dom0', ident)] = options
+            vm.devices['pci'][('dom0', port_id)] = options
 
     def load(self):
         with open(self.store, encoding='utf-8') as fh:

qubesadmin/backup/core3.py

@@ -122,14 +122,14 @@ def import_core3_vm(self, element):
             assert bus_name is not None
             for node in bus_node.findall('./device'):
                 backend_domain = node.get('backend-domain')
-                ident = node.get('id')
+                port_id = node.get('id')
                 options = {}
                 for opt_node in node.findall('./option'):
                     opt_name = opt_node.get('name')
                     options[opt_name] = opt_node.text
                 options['required'] = device_protocol.qbool(
                     node.get('required', 'yes'))
-                vm.devices[bus_name][(backend_domain, ident)] = options
+                vm.devices[bus_name][(backend_domain, port_id)] = options
 
         # extract base properties
         if vm.klass == 'AdminVM':

qubesadmin/backup/restore.py

@@ -2086,27 +2086,27 @@ def _restore_vms_metadata(self, restore_info):
                             tag, vm.name, err)
 
             for bus in vm.devices:
-                for backend_domain, ident in vm.devices[bus]:
-                    options = vm.devices[bus][(backend_domain, ident)]
+                for backend_domain, port_id in vm.devices[bus]:
+                    options = vm.devices[bus][(backend_domain, port_id)]
                     if 'required' in options:
                         required = options['required']
                         del options['required']
                     else:
                         required = False
-                    assignment = DeviceAssignment(
+                    assignment = DeviceAssignment.new(
                         backend_domain=self.app.domains[backend_domain],
-                        ident=ident,
+                        port_id=port_id,
                         devclass=bus,
+                        device_id=None,
                         options=options,
-                        attach_automatically=True,
-                        required=required,
+                        mode='required' if required else 'auto-attach',
                     )
                     try:
                         if not self.options.verify_only:
                             new_vm.devices[bus].assign(assignment)
                     except Exception as err:  # pylint: disable=broad-except
                         self.log.error('Error assigning device %s:%s to %s: %s',
-                            bus, ident, vm.name, err)
+                            bus, port_id, vm.name, err)
 
         # Set VM dependencies - only non-default setting
         for vm in vms.values():