gazu 1.0.3__py2.py3-none-any.whl → 1.1.1__py2.py3-none-any.whl

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 shot as gazu_shot
 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,6 +1,9 @@
+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
 
@@ -8,7 +11,7 @@ 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,6 +1,8 @@
 import json
 import datetime
 
+from typing import Any
+
 
 class CustomJSONEncoder(json.JSONEncoder):
     """
@@ -8,7 +10,7 @@ class CustomJSONEncoder(json.JSONEncoder):
     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()
 

gazu/entity.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 from . import client as raw
 
 from .cache import cache
+from .client import KitsuClient
 from .sorting import sort_by_name
 from .helpers import normalize_model_parameter
 
@@ -8,7 +11,7 @@ default = raw.default_client
 
 
 @cache
-def all_entities(client=default):
+def all_entities(client: KitsuClient = default) -> list[dict]:
     """
     Returns:
         list: Retrieve all entities
@@ -17,7 +20,7 @@ def all_entities(client=default):
 
 
 @cache
-def all_entity_types(client=default):
+def all_entity_types(client: KitsuClient = default) -> list[dict]:
     """
     Returns:
         list: Entity types listed in database.
@@ -26,7 +29,7 @@ def all_entity_types(client=default):
 
 
 @cache
-def get_entity(entity_id, client=default):
+def get_entity(entity_id: str, client: KitsuClient = default) -> dict:
     """
     Args:
         entity_id (str): ID of claimed entity.
@@ -39,11 +42,15 @@ def get_entity(entity_id, client=default):
 
 
 @cache
-def get_entity_by_name(entity_name, project=None, client=default):
+def get_entity_by_name(
+    entity_name: str,
+    project: str | dict | None = None,
+    client: KitsuClient = default,
+) -> dict | None:
     """
     Args:
-        name (str): The name of the claimed entity.
-        project (str, dict): Project ID or dict.
+        entity_name (str): The name of the claimed entity.
+        project (str / dict): Project ID or dict.
 
     Returns:
         Retrieve entity matching given name (and project if given).
@@ -56,10 +63,13 @@ def get_entity_by_name(entity_name, project=None, client=default):
 
 
 @cache
-def get_entity_type(entity_type_id, client=default):
+def get_entity_type(
+    entity_type_id: str, client: KitsuClient = default
+) -> dict:
     """
     Args:
         entity_type_id (str): ID of claimed entity type.
+
     Returns:
         Retrieve entity type matching given ID (It can be an entity type of any
         kind).
@@ -68,7 +78,9 @@ def get_entity_type(entity_type_id, client=default):
 
 
 @cache
-def get_entity_type_by_name(entity_type_name, client=default):
+def get_entity_type_by_name(
+    entity_type_name: str, client: KitsuClient = default
+) -> dict | None:
     """
     Args:
         entity_type_name (str): The name of the claimed entity type
@@ -82,17 +94,17 @@ def get_entity_type_by_name(entity_type_name, client=default):
 
 
 @cache
-def guess_from_path(project_id, path, sep="/"):
+def guess_from_path(project_id: str, path: str, sep: str = "/") -> list[dict]:
     """
     Get list of possible project file tree templates matching a file path
     and data ids corresponding to template tokens.
 
     Args:
         project_id (str): Project id of given file
-        file_path (str): Path to a file
+        path (str): Path to a file
         sep (str): File path separator, defaults to "/"
     Returns:
-        list: dictionnaries with the corresponding entities and template name.
+        list: dictionaries with the corresponding entities and template name.
     """
     return raw.post(
         "/data/entities/guess_from_path",
@@ -100,38 +112,52 @@ def guess_from_path(project_id, path, sep="/"):
     )
 
 
-def new_entity_type(name, client=default):
+def new_entity_type(name: str, client: KitsuClient = default) -> dict:
     """
     Creates an entity type with the given name.
 
     Args:
-        name (str, client=default): The name of the entity type
+        name (str): The name of the entity type
 
     Returns:
         dict: The created entity type
+
+    Raises:
+        gazu.exception.ParameterException:
+            If an entity type with that name already exists.
     """
     data = {"name": name}
     return raw.create("entity-types", data, client=client)
 
 
-def remove_entity_type(entity_type, client=default):
+def remove_entity_type(
+    entity_type: str | dict, client: KitsuClient = default
+) -> str:
     """
     Remove given entity type from database.
 
     Args:
-        entity_type (dict / str): Entity type to remove.
+        entity_type (str / dict): Entity type to remove.
     """
     entity_type = normalize_model_parameter(entity_type)
     path = "data/entity-types/%s" % entity_type["id"]
     return raw.delete(path, client=client)
 
 
-def remove_entity(entity, force=False, client=default):
+def remove_entity(
+    entity: str | dict, force: bool = False, client: KitsuClient = default
+) -> str:
     """
     Remove given entity from database.
 
+    If the Entity has tasks linked to it, this will by default mark the
+    Entity as canceled. Deletion can be forced regardless of task links
+    with the `force` parameter.
+
     Args:
         entity (dict): Entity to remove.
+        force (bool): Whether to force deletion of the entity regardless of
+            whether it has links to tasks.
     """
     entity = normalize_model_parameter(entity)
     path = "data/entities/%s" % entity["id"]
@@ -141,10 +167,13 @@ def remove_entity(entity, force=False, client=default):
     return raw.delete(path, params, client=client)
 
 
-def all_entities_with_tasks_linked_to_entity(entity, client=default):
+def all_entities_with_tasks_linked_to_entity(
+    entity: str | dict, client: KitsuClient = default
+) -> list[dict]:
     """
     Args:
-        entity (dict): Entity to get linked entities.
+        entity (str / dict): Entity to get linked entities.
+
     Returns:
         list: Retrieve all entities linked to given entity.
     """

gazu/events.py

@@ -4,10 +4,17 @@ import inspect
 import signal
 import socketio
 
+from typing import Any, Callable
+
 from engineio.base_client import signal_handler
 from .exception import AuthFailedException
 
-from .client import default_client, get_event_host, make_auth_header
+from .client import (
+    default_client,
+    get_event_host,
+    KitsuClient,
+    make_auth_header,
+)
 
 
 if os.name == "nt":
@@ -25,23 +32,23 @@ if os.name == "nt":
 
 
 class EventsNamespace(socketio.ClientNamespace):
-    def on_connect(self):
+    def on_connect(self) -> None:
         pass
 
-    def on_disconnect(self):
+    def on_disconnect(self) -> None:
         pass
 
-    def on_error(self, data):
+    def on_error(self, data: str) -> str:
         return connect_error(data)
 
 
 def init(
-    client=default_client,
-    ssl_verify=False,
-    reconnection=True,
-    logger=False,
-    **kwargs
-):
+    client: KitsuClient = default_client,
+    ssl_verify: bool = False,
+    reconnection: bool = True,
+    logger: bool = False,
+    **kwargs: Any
+) -> socketio.Client:
     """
     Init configuration for SocketIO client.
 
@@ -61,13 +68,15 @@ def init(
     return event_client
 
 
-def connect_error(data):
+def connect_error(data: str) -> str:
     print("The connection failed!")
     print(data)
     return data
 
 
-def add_listener(event_client, event_name, event_handler):
+def add_listener(
+    event_client: socketio.Client, event_name: str, event_handler: Callable
+) -> socketio.Client:
     """
     Set a listener that reacts to a given event.
     """
@@ -75,7 +84,7 @@ def add_listener(event_client, event_name, event_handler):
     return event_client
 
 
-def run_client(event_client):
+def run_client(event_client: socketio.Client) -> socketio.Client:
     """
     Run event client (it blocks current thread). It listens to all events
     configured.