refactor: convert type comments to type hints (#255)

The converts the type comments into type hints, and adds a few extra typing fixes.
Also improved readability by breaking down long typed argument lists on multiple lines.

Removing the types from the docstrings will be done in a future PR or gradually while improving the docstrings.

* refactor: remove unused results_list_attribute_name

* test: add mypy linter

* ci: add lint job

* chore: convert type comments to annotations

* style: break down large arg list on multiline

* refactor: fix type hints

* chore: fix server type hint

Co-authored-by: Julian Tölle <julian.toelle97@gmail.com>

* chore: fix type hints

* docs: add note about new lint task

---------

Co-authored-by: Julian Tölle <julian.toelle97@gmail.com>

Author: jooola

.github/workflows/lint.yml

@@ -21,3 +21,19 @@ jobs:
 
       - name: Run pre-commit
         run: pre-commit run --all-files --show-diff-on-failure
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: make venv
+
+      - name: Run lint
+        run: make lint

.gitlab-ci.yml

@@ -7,6 +7,15 @@ include:
 stages:
   - test
 
+lint:
+  stage: test
+
+  image: python:3.11-alpine
+  before_script:
+    - make venv
+  script:
+    - make lint
+
 test:
   stage: test
 

Makefile

@@ -5,6 +5,9 @@ venv:
 	python3 -m venv venv
 	venv/bin/pip install -e .[docs,test]
 
+lint: venv
+	venv/bin/mypy hcloud
+
 test: venv
 	venv/bin/pytest -v
 

README.md

@@ -75,6 +75,12 @@ Build the documentation and open it in your browser:
 make docs
 ```
 
+Lint the code:
+
+```sh
+make lint
+```
+
 Run tests using the current `python3` version:
 
 ```sh

hcloud/_client.py

@@ -187,7 +187,7 @@ def request(
         url: str,
         tries: int = 1,
         **kwargs,
-    ) -> bytes | dict:
+    ) -> dict:
         """Perform a request to the Hetzner Cloud API, wrapper around requests.request
 
         :param method: HTTP Method to perform the Request
@@ -211,6 +211,7 @@ def request(
 
         if not response.ok:
             if content:
+                assert isinstance(content, dict)
                 if content["error"]["code"] == "rate_limit_exceeded" and tries < 5:
                     time.sleep(tries * self._retry_wait_time)
                     tries = tries + 1
@@ -220,4 +221,5 @@ def request(
             else:
                 self._raise_exception_from_response(response)
 
-        return content
+        # TODO: return an empty dict instead of an empty string when content == "".
+        return content  # type: ignore[return-value]

hcloud/_exceptions.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Any
+
 
 class HCloudException(Exception):
     """There was an error while using the hcloud library"""
@@ -8,7 +10,7 @@ class HCloudException(Exception):
 class APIException(HCloudException):
     """There was an error while performing an API Request"""
 
-    def __init__(self, code, message, details):
+    def __init__(self, code: int | str, message: str, details: Any):
         super().__init__(message)
         self.code = code
         self.message = message

hcloud/actions/client.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import time
-from typing import TYPE_CHECKING, NamedTuple
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from ..core import BoundModelBase, ClientEntityBase, Meta
 from .domain import Action, ActionFailedException, ActionTimeoutException
@@ -15,7 +15,7 @@ class BoundAction(BoundModelBase):
 
     model = Action
 
-    def wait_until_finished(self, max_retries=100):
+    def wait_until_finished(self, max_retries: int = 100) -> None:
         """Wait until the specific action has status="finished" (set Client.poll_interval to specify a delay between checks)
 
         :param max_retries: int
@@ -43,8 +43,7 @@ class ActionsPageResult(NamedTuple):
 class ActionsClient(ClientEntityBase):
     _client: Client
 
-    def get_by_id(self, id):
-        # type: (int) -> BoundAction
+    def get_by_id(self, id: int) -> BoundAction:
         """Get a specific action by its ID.
 
         :param id: int
@@ -56,12 +55,11 @@ def get_by_id(self, id):
 
     def get_list(
         self,
-        status=None,  # type: Optional[List[str]]
-        sort=None,  # type: Optional[List[str]]
-        page=None,  # type: Optional[int]
-        per_page=None,  # type: Optional[int]
-    ):
-        # type: (...) -> PageResults[List[BoundAction]]
+        status: list[str] | None = None,
+        sort: list[str] | None = None,
+        page: int | None = None,
+        per_page: int | None = None,
+    ) -> ActionsPageResult:
         """Get a list of actions from this account
 
         :param status: List[str] (optional)
@@ -74,7 +72,7 @@ def get_list(
                Specifies how many results are returned by page
         :return: (List[:class:`BoundAction <hcloud.actions.client.BoundAction>`], :class:`Meta <hcloud.core.domain.Meta>`)
         """
-        params = {}
+        params: dict[str, Any] = {}
         if status is not None:
             params["status"] = status
         if sort is not None:
@@ -90,8 +88,11 @@ def get_list(
         ]
         return ActionsPageResult(actions, Meta.parse_meta(response))
 
-    def get_all(self, status=None, sort=None):
-        # type: (Optional[List[str]], Optional[List[str]]) -> List[BoundAction]
+    def get_all(
+        self,
+        status: list[str] | None = None,
+        sort: list[str] | None = None,
+    ) -> list[BoundAction]:
         """Get all actions of the account
 
         :param status: List[str] (optional)

hcloud/actions/domain.py

@@ -1,10 +1,15 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from dateutil.parser import isoparse
 
 from .._exceptions import HCloudException
 from ..core import BaseDomain
 
+if TYPE_CHECKING:
+    from .client import BoundAction
+
 
 class Action(BaseDomain):
     """Action Domain
@@ -39,14 +44,14 @@ class Action(BaseDomain):
 
     def __init__(
         self,
-        id,
-        command=None,
-        status=None,
-        progress=None,
-        started=None,
-        finished=None,
-        resources=None,
-        error=None,
+        id: int,
+        command: str | None = None,
+        status: str | None = None,
+        progress: int | None = None,
+        started: str | None = None,
+        finished: str | None = None,
+        resources: list[dict] | None = None,
+        error: dict | None = None,
     ):
         self.id = id
         self.command = command
@@ -62,7 +67,8 @@ def __init__(
 class ActionException(HCloudException):
     """A generic action exception"""
 
-    def __init__(self, action):
+    def __init__(self, action: Action | BoundAction):
+        assert self.__doc__ is not None
         message = self.__doc__
         if action.error is not None and "message" in action.error:
             message += f": {action.error['message']}"