Closes #43: Add type hints in the code base (#108)

Introduce typing across the whole code base. Use `ty` to perform type checks.

Fix a reference issue when passing the token from `refresh_authentication()`.

Author: gmazoyer

.github/workflows/publish.yml

@@ -16,19 +16,16 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v6
       with:
-        python-version: "3.9"
+        python-version: "3.10"
 
-    - name: Install Poetry
-      run: pipx install poetry
-
-    - name: Set PyPI secret
-      run: poetry config pypi-token.pypi ${{ secrets.PYPI_API_TOKEN }}
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
 
     - name: Build package
-      run: poetry build
+      run: uv build
 
     - name: List build
       run: ls -la dist/
 
     - name: Publish package in PyPI
-      run: poetry publish
+      run: uv publish --token ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/tests.yml

@@ -27,19 +27,22 @@ jobs:
       with:
         python-version: ${{ matrix.python }}
 
-    - name: Install Poetry
-      run: pipx install poetry
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
 
-    - name: Validate pyproject.toml and poetry.lock
-      run: poetry check
+    - name: Validate pyproject.toml and uv.lock
+      run: uv lock --locked --offline --no-cache --check
 
     - name: Install dependencies
-      run: poetry install --extras=dev
+      run: uv sync --locked --all-groups
 
     - name: Run format and lint
       run: |
-        poetry run ruff format --check --diff .
-        poetry run ruff check --diff .
+        uv run ruff format --check --diff .
+        uv run ruff check --diff .
+    
+    - name: Run type checking
+      run: uv run ty check .
 
     - name: Run Tests
-      run: poetry run pytest
+      run: uv run pytest

poetry.lock

@@ -1,4 +1,5 @@
 import warnings
+from typing import Any
 
 import requests
 
@@ -44,14 +45,14 @@ class API(object):
 
     def __init__(
         self,
-        url,
-        key,
-        secret,
-        access_token="",
-        refresh_token="",
-        user_agent=f"pyixapi/{__version__}",
-        proxies=None,
-    ):
+        url: str,
+        key: str,
+        secret: str,
+        access_token: str = "",
+        refresh_token: str = "",
+        user_agent: str = f"pyixapi/{__version__}",
+        proxies: dict[str, str] | None = None,
+    ) -> None:
         self.url = url.rstrip("/")
         self.key = key
         self.secret = secret
@@ -106,18 +107,18 @@ def version(self) -> int:
         return version
 
     @property
-    def accounts(self):
+    def accounts(self) -> Endpoint:
         return Endpoint(self, "customers" if self.version == 1 else "accounts", model=Account)
 
     @property
-    def product_offerings(self):
+    def product_offerings(self) -> Endpoint:
         return Endpoint(
             self,
             "products" if self.version == 1 else "product-offerings",
             model=ProductOffering,
         )
 
-    def authenticate(self):
+    def authenticate(self) -> Record | None:
         """
         Authenticate and generate a pair of tokens.
 
@@ -147,13 +148,16 @@ def authenticate(self):
 
         return Record(r, self, self.auth)
 
-    def refresh_authentication(self):
+    def refresh_authentication(self) -> Record:
         """
         Prolong authentication by refreshing the tokens pair.
         """
+        if not self.refresh_token:
+            raise ValueError("No refresh token available to refresh authentication")
+
         r = Request(
             cat(self.url, "auth", "refresh"),
-            token=self.refresh_token.encoded,
+            token=self.refresh_token,
             http_session=self.http_session,
             user_agent=self.user_agent,
             proxies=self.proxies,
@@ -164,7 +168,7 @@ def refresh_authentication(self):
 
         return Record(r, self, self.auth)
 
-    def health(self):
+    def health(self) -> dict[str, Any]:
         """
         Get the health information from IX-API.
 

pyixapi/core/api.py

@@ -1,7 +1,14 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
 from pyixapi.core.query import Request, RequestError
 from pyixapi.core.response import Record, RecordSet
 from pyixapi.core.util import cat
 
+if TYPE_CHECKING:
+    from pyixapi.core.api import API
+
 
 class Endpoint(object):
     """
@@ -11,16 +18,16 @@ class Endpoint(object):
     object.
     """
 
-    def __init__(self, api, name, model=None):
-        self.return_obj = model if model else Record
+    def __init__(self, api: API, name: str, model: type[Record] | None = None) -> None:
+        self.return_obj: type[Record] = model if model else Record
         self.api = api
         self.url = cat(api.url, name)
         self.name = name
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.url
 
-    def all(self):
+    def all(self) -> RecordSet:
         """
         Return all objects from an endpoint.
         """
@@ -33,7 +40,7 @@ def all(self):
         )
         return RecordSet(self, r)
 
-    def filter(self, *args, **kwargs):
+    def filter(self, *args: Any, **kwargs: Any) -> RecordSet:
         """
         Query the list of a given endpoint. Also take named arguments that match the
         usable filters on a given endpoint.
@@ -48,7 +55,7 @@ def filter(self, *args, **kwargs):
         )
         return RecordSet(self, r)
 
-    def get(self, *args, **kwargs):
+    def get(self, *args: Any, **kwargs: Any) -> Record | None:
         """
         Return a single object from an endpoint.
         """
@@ -89,7 +96,7 @@ def get(self, *args, **kwargs):
             else:
                 raise e
 
-    def create(self, *args, **kwargs):
+    def create(self, *args: Any, **kwargs: Any) -> Record:
         """
         Creates an object on an endpoint.