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

* origin/pr/458:
  misc. typing fixes
  type-hint storage.py
  type-hint spinner.py
  type-hint log.py
  type-hint label.py

Pull request description:

Major: type-hint `storage.py`
Minor: type-hint `label.py spinner.py log.py`

In `__lt__` we have

```python3
            if self._vid and other._vid:
                return (self._pool, self._vid) < (other._pool, other._vid)
```
Technically, `_vid` is supposed to be non-None if `pool` is non-None, not the other way around. Shouldn't it be `if self.pool and other.pool:` ?

In `revert`:
```python3
        if not isinstance(revision, str):
            raise TypeError('revision must be a str')
```

but typing `def revert(self, revision: str) -> None:` raises no type-checker error, indicating that it's never called with a non-str argument. Is the raise really necessary ?

```python3
    def __str__(self):
        return self.name
```

but `self.name` can be `None`, and `__str__` should never be `None`. I added an `assert is not None` for now.

```python3
    def __lt__(self, other: object) -> bool:
        if isinstance(other, Pool):
            return self.name < other.name
```
What guarantees that `self.name` or `other.name` is defined here ?

Author: marmarek

qubesadmin/app.py

@@ -148,8 +148,15 @@ def get_blind(self, item: str) -> QubesVM:
 
     T = TypeVar("T")
 
-    def get(self, item: str | QubesVM, default: QubesVM | T=None)\
-            -> QubesVM | T:
+    @typing.overload
+    def get(self, item: str | QubesVM) -> QubesVM:
+        ...
+    @typing.overload
+    def get(self, item: str | QubesVM, default: T) -> QubesVM | T:
+        ...
+    # Overloaded to handle default None return type
+    def get(self, item: str | QubesVM, default: object=None)\
+            -> object:
         """
         Get a VM object, or return *default* if it can't be found.
         """

qubesadmin/backup/core2.py

@@ -87,7 +87,7 @@ def rule_from_xml_v1(node: _Element, action: str) -> Rule:
 
         expire = node.get('expire')
 
-        kwargs = {
+        kwargs: dict[str, object] = {
             'action': action,
         }
         if dsthost:

qubesadmin/backup/restore.py

@@ -1438,7 +1438,7 @@ def _process_qubes_xml(self) -> Core2Qubes | Core3Qubes:
         queue.put(QUEUE_FINISHED)
 
         qubes_xml_path = os.path.join(self.tmpdir, 'qubes-restored.xml')
-        handlers = {
+        handlers: dict[str, Callable] = {
             'qubes.xml': functools.partial(self._save_qubes_xml, qubes_xml_path)
             }
         extract_proc = self._start_inner_extraction_worker(queue, handlers)

qubesadmin/device_protocol.py

@@ -513,7 +513,8 @@ def __lt__(self, other: object) -> bool:
                 other.port, AnyPort
             ):
                 return False
-            reprs = {self: [self.port], other: [other.port]}
+            reprs: dict[VirtualDevice | DeviceAssignment, list[Port | str]] \
+                = {self: [self.port], other: [other.port]}
             for obj, obj_repr in reprs.items():
                 if obj.device_id != "*":
                     obj_repr.append(obj.device_id)

qubesadmin/label.py

@@ -19,9 +19,14 @@
 # with this program; if not, see <http://www.gnu.org/licenses/>.
 
 '''VM Labels'''
+from __future__ import annotations
+from typing import TYPE_CHECKING
 
 import qubesadmin.exc
 
+if TYPE_CHECKING:
+    from qubesadmin.app import QubesBase
+
 
 class Label:
     '''Label definition for virtual machines
@@ -32,14 +37,14 @@ class Label:
     :param str name: label's name like "red" or "green"
     '''
 
-    def __init__(self, app, name):
+    def __init__(self, app: QubesBase, name: str):
         self.app = app
         self._name = name
-        self._color = None
-        self._index = None
+        self._color: str | None = None
+        self._index: int | None = None
 
     @property
-    def color(self):
+    def color(self) -> str:
         '''color specification as in HTML (``#abcdef``)'''
         if self._color is None:
             try:
@@ -51,18 +56,18 @@ def color(self):
         return self._color
 
     @property
-    def name(self):
+    def name(self) -> str:
         '''label's name like "red" or "green"'''
         return self._name
 
     @property
-    def icon(self):
+    def icon(self) -> str:
         '''freedesktop icon name, suitable for use in
         :py:meth:`PyQt4.QtGui.QIcon.fromTheme`'''
         return 'appvm-' + self.name
 
     @property
-    def index(self):
+    def index(self) -> int:
         '''label numeric identifier'''
         if self._index is None:
             try:
@@ -73,13 +78,13 @@ def index(self):
             self._index = int(qubesd_response.decode())
         return self._index
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self._name
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         if isinstance(other, Label):
             return self.name == other.name
         return NotImplemented
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         return hash(self.name)

qubesadmin/log.py

@@ -37,7 +37,7 @@
 formatter_debug = logging.Formatter(FORMAT_DEBUG)
 
 
-def enable():
+def enable() -> None:
     '''Enable global logging
 
     Use :py:mod:`logging` module from standard library to log messages.
@@ -58,7 +58,7 @@ def enable():
     logging.root.setLevel(logging.INFO)
 
 
-def enable_debug():
+def enable_debug() -> None:
     '''Enable debug logging
 
     Enable more messages and additional info to message format.

qubesadmin/spinner.py

@@ -39,9 +39,11 @@
 import curses
 import io
 import itertools
+import typing
+from typing import IO
 
-CHARSET = '-\\|/'
-ENTERPRISE_CHARSET = CHARSET * 4 + '-._.-^' * 2
+CHARSET: str = '-\\|/'
+ENTERPRISE_CHARSET: str = CHARSET * 4 + '-._.-^' * 2
 
 class AbstractSpinner:
     '''The base class for all Spinners
@@ -54,57 +56,57 @@ class AbstractSpinner:
         2. zero or more calls to :py:meth:`update()`
         3. exactly one call to :py:meth:`hide()`
     '''
-    def __init__(self, stream, charset=CHARSET):
+    def __init__(self, stream: IO, charset: str=CHARSET):
         self.stream = stream
         self.charset = itertools.cycle(charset)
 
-    def show(self, prompt):
+    def show(self, prompt: str) -> None:
         '''Show the spinner, with a prompt
 
         :param str prompt: prompt, like "please wait"
         '''
         raise NotImplementedError()
 
-    def hide(self):
+    def hide(self) -> None:
         '''Hide the spinner and the prompt'''
         raise NotImplementedError()
 
-    def update(self):
+    def update(self) -> None:
         '''Show next spinner character'''
         raise NotImplementedError()
 
 
 class DummySpinner(AbstractSpinner):
     '''Dummy spinner, does not do anything'''
-    def show(self, prompt):
+    def show(self, prompt: str) -> None:
         pass
 
-    def hide(self):
+    def hide(self) -> None:
         pass
 
-    def update(self):
+    def update(self) -> None:
         pass
 
 
 class QubesSpinner(AbstractSpinner):
     '''Basic spinner
 
     This spinner uses standard ASCII control characters'''
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args, **kwargs) -> None:
         super().__init__(*args, **kwargs)
         self.hidelen = 0
         self.cub1 = '\b'
 
-    def show(self, prompt):
+    def show(self, prompt: str) -> None:
         self.hidelen = len(prompt) + 2
         self.stream.write('{} {}'.format(prompt, next(self.charset)))
         self.stream.flush()
 
-    def hide(self):
+    def hide(self) -> None:
         self.stream.write('\r' + ' ' * self.hidelen + '\r')
         self.stream.flush()
 
-    def update(self):
+    def update(self) -> None:
         self.stream.write(self.cub1 + next(self.charset))
         self.stream.flush()
 
@@ -114,7 +116,7 @@ class QubesSpinnerEnterpriseEdition(QubesSpinner):
 
     This is tty- and terminfo-aware spinner. Recommended.
     '''
-    def __init__(self, stream, charset=None):
+    def __init__(self, stream: IO, charset: str | None=None):
         # our Enterprise logic follows
         self.stream_isatty = stream.isatty()
         if charset is None:
@@ -126,18 +128,20 @@ def __init__(self, stream, charset=None):
             try:
                 curses.setupterm()
                 self.has_terminfo = True
-                self.cub1 = curses.tigetstr('cub1').decode()
+                self.cub1 = typing.cast(bytes, curses.tigetstr('cub1')).decode()
             except (curses.error, io.UnsupportedOperation):
                 # we are in very non-Enterprise environment
                 self.has_terminfo = False
         else:
             self.cub1 = ''
 
-    def hide(self):
+    def hide(self) -> None:
         if self.stream_isatty:
             hideseq = '\r' + ' ' * self.hidelen + '\r'
             if self.has_terminfo:
-                hideseq_l = (curses.tigetstr('cr'), curses.tigetstr('clr_eol'))
+                hideseq_l = typing.cast(
+                    tuple[bytes, bytes],
+                    (curses.tigetstr('cr'), curses.tigetstr('clr_eol')))
                 if all(seq is not None for seq in hideseq_l):
                     hideseq = ''.join(seq.decode() for seq in hideseq_l)
         else: