chore: added generic type hints to several more modules + docstring cleanup.

gazu/context.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from . import user as gazu_user
 from . import project as gazu_project
 from . import asset as gazu_asset
@@ -6,7 +8,7 @@
 from . import scene as gazu_scene
 
 
-def all_open_projects(user_context=False):
+def all_open_projects(user_context: bool = False) -> list[dict]:
     """
     Return the list of projects for which the user has a task.
     """
@@ -16,7 +18,9 @@ def all_open_projects(user_context=False):
         return gazu_project.all_open_projects()
 
 
-def all_assets_for_project(project, user_context=False):
+def all_assets_for_project(
+    project: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of assets for which the user has a task.
     """
@@ -26,7 +30,9 @@ def all_assets_for_project(project, user_context=False):
         return gazu_asset.all_assets_for_project(project)
 
 
-def all_asset_types_for_project(project, user_context=False):
+def all_asset_types_for_project(
+    project: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of asset types for which the user has a task.
     """
@@ -37,8 +43,8 @@ def all_asset_types_for_project(project, user_context=False):
 
 
 def all_assets_for_asset_type_and_project(
-    project, asset_type, user_context=False
-):
+    project: str | dict, asset_type: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of assets for given project and asset_type and for which
     the user has a task.
@@ -51,7 +57,9 @@ def all_assets_for_asset_type_and_project(
         return gazu_asset.all_assets_for_project_and_type(project, asset_type)
 
 
-def all_task_types_for_asset(asset, user_context=False):
+def all_task_types_for_asset(
+    asset: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of tasks for given asset and current user.
     """
@@ -61,7 +69,9 @@ def all_task_types_for_asset(asset, user_context=False):
         return gazu_task.all_task_types_for_asset(asset)
 
 
-def all_task_types_for_shot(shot, user_context=False):
+def all_task_types_for_shot(
+    shot: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of tasks for given shot and current user.
     """
@@ -71,7 +81,9 @@ def all_task_types_for_shot(shot, user_context=False):
         return gazu_task.all_task_types_for_shot(shot)
 
 
-def all_task_types_for_scene(scene, user_context=False):
+def all_task_types_for_scene(
+    scene: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of tasks for given scene and current user.
     """
@@ -81,7 +93,9 @@ def all_task_types_for_scene(scene, user_context=False):
         return gazu_task.all_task_types_for_scene(scene)
 
 
-def all_task_types_for_sequence(sequence, user_context=False):
+def all_task_types_for_sequence(
+    sequence: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of tasks for given sequence and current user.
     """
@@ -91,7 +105,9 @@ def all_task_types_for_sequence(sequence, user_context=False):
         return gazu_task.all_task_types_for_sequence(sequence)
 
 
-def all_sequences_for_project(project, user_context=False):
+def all_sequences_for_project(
+    project: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of sequences for given project and current user.
     """
@@ -101,7 +117,9 @@ def all_sequences_for_project(project, user_context=False):
         return gazu_shot.all_sequences_for_project(project)
 
 
-def all_scenes_for_project(project, user_context=False):
+def all_scenes_for_project(
+    project: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of scenes for given project and current user.
     """
@@ -111,7 +129,9 @@ def all_scenes_for_project(project, user_context=False):
         return gazu_scene.all_scenes(project)
 
 
-def all_shots_for_sequence(sequence, user_context=False):
+def all_shots_for_sequence(
+    sequence: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of shots for given sequence and current user.
     """
@@ -121,7 +141,9 @@ def all_shots_for_sequence(sequence, user_context=False):
         return gazu_shot.all_shots_for_sequence(sequence)
 
 
-def all_scenes_for_sequence(sequence, user_context=False):
+def all_scenes_for_sequence(
+    sequence: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of scenes for given sequence and current user.
     """
@@ -131,7 +153,9 @@ def all_scenes_for_sequence(sequence, user_context=False):
         return gazu_scene.all_scenes_for_sequence(sequence)
 
 
-def all_sequences_for_episode(episode, user_context=False):
+def all_sequences_for_episode(
+    episode: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of shots for given sequence and current user.
     """
@@ -141,7 +165,9 @@ def all_sequences_for_episode(episode, user_context=False):
         return gazu_shot.all_sequences_for_episode(episode)
 
 
-def all_episodes_for_project(project, user_context=False):
+def all_episodes_for_project(
+    project: str | dict, user_context: bool = False
+) -> list[dict]:
     """
     Return the list of shots for given sequence and current user.
     """

gazu/edit.py

@@ -1,14 +1,17 @@
+from __future__ import annotations
+
 from . import client as raw
 
 from .cache import cache
+from .client import KitsuClient
 from .helpers import normalize_model_parameter
 from gazu.sorting import sort_by_name
 
 default = raw.default_client
 
 
 @cache
-def get_edit(edit_id, client=default):
+def get_edit(edit_id: str, client: KitsuClient = default) -> dict:
     """
     Args:
         edit_id (str): ID of claimed edit.
@@ -20,7 +23,9 @@ def get_edit(edit_id, client=default):
 
 
 @cache
-def get_edit_by_name(project, edit_name, client=default):
+def get_edit_by_name(
+    project: str | dict, edit_name: str, client: KitsuClient = default
+) -> dict | None:
     """
     Args:
         project (str / dict): The project dict or the project ID.
@@ -38,7 +43,7 @@ def get_edit_by_name(project, edit_name, client=default):
 
 
 @cache
-def get_edit_url(edit, client=default):
+def get_edit_url(edit: str | dict, client: KitsuClient = default) -> str:
     """
     Args:
         edit (str / dict): The edit dict or the edit ID.
@@ -62,7 +67,9 @@ def get_edit_url(edit, client=default):
 
 
 @cache
-def all_edits_for_project(project, client=default):
+def all_edits_for_project(
+    project: str | dict, client: KitsuClient = default
+) -> list[dict]:
     """
     Args:
         project (str / dict): The project dict or the project ID.
@@ -76,7 +83,9 @@ def all_edits_for_project(project, client=default):
 
 
 @cache
-def all_previews_for_edit(edit, client=default):
+def all_previews_for_edit(
+    edit: str | dict, client: KitsuClient = default
+) -> list[dict]:
     """
     Args:
         edit (str / dict): The edit dict or the edit ID.
@@ -89,13 +98,13 @@ def all_previews_for_edit(edit, client=default):
 
 
 def new_edit(
-    project,
-    name,
-    description=None,
-    data={},
-    episode=None,
-    client=default,
-):
+    project: str | dict,
+    name: str,
+    description: str | None = None,
+    data: dict = {},
+    episode: str | dict | None = None,
+    client: KitsuClient = default,
+) -> dict:
     """
     Create an edit for given project (and episode if given).
     Allow to set metadata too.
@@ -128,12 +137,20 @@ def new_edit(
         return edit
 
 
-def remove_edit(edit, force=False, client=default):
+def remove_edit(
+    edit: str | dict, force: bool = False, client: KitsuClient = default
+) -> str:
     """
     Remove given edit from database.
 
+    If the Edit has tasks linked to it, this will by default mark the
+    Edit as canceled. Deletion can be forced regardless of task links
+    with the `force` parameter.
+
     Args:
-        edit (dict / str): Edit to remove.
+        edit (str / dict): Edit to remove.
+        force (bool): Whether to force deletion of the edit regardless of
+            whether it has links to tasks.
     """
     edit = normalize_model_parameter(edit)
     path = "data/edits/%s" % edit["id"]
@@ -143,7 +160,7 @@ def remove_edit(edit, force=False, client=default):
     return raw.delete(path, params, client=client)
 
 
-def update_edit(edit, client=default):
+def update_edit(edit: dict, client: KitsuClient = default) -> dict:
     """
     Save given edit data into the API. Metadata are fully replaced by the ones
     set on given edit.
@@ -157,13 +174,15 @@ def update_edit(edit, client=default):
     return raw.put("data/entities/%s" % edit["id"], edit, client=client)
 
 
-def update_edit_data(edit, data={}, client=default):
+def update_edit_data(
+    edit: str | dict, data: dict = {}, client: KitsuClient = default
+) -> dict:
     """
     Update the metadata for the provided edit. Keys that are not provided are
     not changed.
 
     Args:
-        edit (dict / ID): The edit dict or ID to save in database.
+        edit (str / dict): The edit dict or ID to save in database.
         data (dict): Free field to set metadata of any kind.
 
     Returns:

gazu/encoder.py

@@ -1,14 +1,16 @@
 import json
 import datetime
 
+from typing import Any
+
 
 class CustomJSONEncoder(json.JSONEncoder):
     """
     This JSON encoder is here to handle dates which are not handled by default.
     The standard does not want to assum how you handle dates.
     """
 
-    def default(self, obj):
+    def default(self, obj: Any) -> Any:
         if isinstance(obj, datetime.datetime):
             return obj.isoformat()