gazu 1.0.2__py2.py3-none-any.whl → 1.1.0__py2.py3-none-any.whl

gazu/helpers.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import sys
 import os
 import re
@@ -19,7 +21,9 @@ _UUID_RE = re.compile(
 )
 
 
-def normalize_model_parameter(model_parameter):
+def normalize_model_parameter(
+    model_parameter: str | dict | None,
+) -> dict | None:
     """
     Args:
         model_parameter (str / dict): The parameter to convert.
@@ -45,7 +49,9 @@ def normalize_model_parameter(model_parameter):
             raise ValueError("Wrong format: expected ID string or Data dict")
 
 
-def normalize_list_of_models_for_links(models=[]):
+def normalize_list_of_models_for_links(
+    models: list[str | dict] = [],
+) -> list[str]:
     """
     Args:
         models (list): The models to convert.
@@ -59,7 +65,7 @@ def normalize_list_of_models_for_links(models=[]):
     return [normalize_model_parameter(model)["id"] for model in models]
 
 
-def validate_date_format(date_text):
+def validate_date_format(date_text: str) -> str:
     try:
         datetime.datetime.strptime(date_text, "%Y-%m-%dT%H:%M:%S")
     except ValueError:
@@ -73,14 +79,16 @@ def validate_date_format(date_text):
     return date_text
 
 
-def sanitize_filename(filename):
+def sanitize_filename(filename: str) -> str:
     forbidden = "@|():%/,\\[]<>*?;`\n"
     return "".join(
         [c for c in filename.replace("..", "_") if c not in forbidden]
     ).strip()
 
 
-def download_file(url, file_path=None, headers={}):
+def download_file(
+    url: str, file_path: str | None = None, headers: dict = {}
+) -> str:
     """
     Download file located at *file_path* to given url *url*.
 

gazu/person.py

@@ -1,3 +1,8 @@
+from __future__ import annotations
+
+import datetime
+from typing_extensions import Literal
+
 from . import client as raw
 
 from .sorting import sort_by_name
@@ -6,12 +11,14 @@ from .helpers import (
     normalize_list_of_models_for_links,
 )
 from .cache import cache
+from .client import KitsuClient
+
 
 default = raw.default_client
 
 
 @cache
-def all_organisations(client=default):
+def all_organisations(client: KitsuClient = default) -> list[dict]:
     """
     Returns:
         list: Organisations listed in database.
@@ -20,7 +27,7 @@ def all_organisations(client=default):
 
 
 @cache
-def all_departments(client=default):
+def all_departments(client: KitsuClient = default) -> list[dict]:
     """
     Returns:
         list: Departments listed in database.
@@ -29,7 +36,7 @@ def all_departments(client=default):
 
 
 @cache
-def all_persons(client=default):
+def all_persons(client: KitsuClient = default) -> list[dict]:
     """
     Returns:
         list: Persons listed in database.
@@ -38,7 +45,12 @@ def all_persons(client=default):
 
 
 @cache
-def get_time_spents_range(person_id, start_date, end_date, client=default):
+def get_time_spents_range(
+    person_id: str,
+    start_date: str,
+    end_date: str,
+    client: KitsuClient = default,
+) -> list:
     """
     Gets the time spents of the current user for the given date range.
 
@@ -48,6 +60,7 @@ def get_time_spents_range(person_id, start_date, end_date, client=default):
                           the following format: YYYY-MM-DD
         end_date (str): The last day of the date range as a date string with
                         the following format: YYYY-MM-DD
+
     Returns:
         list: All of the person's time spents
     """
@@ -62,7 +75,9 @@ def get_time_spents_range(person_id, start_date, end_date, client=default):
     )
 
 
-def get_all_month_time_spents(id, date, client=default):
+def get_all_month_time_spents(
+    id: str, date: datetime.date, client: KitsuClient = default
+) -> list:
     """
     Args:
         id (str): An uuid identifying a person.
@@ -79,7 +94,9 @@ def get_all_month_time_spents(id, date, client=default):
 
 
 @cache
-def get_department_by_name(name, client=default):
+def get_department_by_name(
+    name: str, client: KitsuClient = default
+) -> dict | None:
     """
     Args:
         name (str): Department name.
@@ -95,7 +112,7 @@ def get_department_by_name(name, client=default):
 
 
 @cache
-def get_department(department_id, client=default):
+def get_department(department_id: str, client: KitsuClient = default) -> dict:
     """
     Args:
         department_id (str): An uuid identifying a department.
@@ -107,14 +124,17 @@ def get_department(department_id, client=default):
 
 
 @cache
-def get_person(id, relations=False, client=default):
+def get_person(
+    id: str, relations: bool = False, client: KitsuClient = default
+) -> dict | None:
     """
     Args:
         id (str): An uuid identifying a person.
         relations (bool): Whether to get the relations for the given person.
 
     Returns:
-        dict: Person corresponding to given id.
+        dict: Person corresponding to given id, or None if no Person exists
+            with that ID.
     """
     params = {"id": id}
     if relations:
@@ -124,7 +144,9 @@ def get_person(id, relations=False, client=default):
 
 
 @cache
-def get_person_by_desktop_login(desktop_login, client=default):
+def get_person_by_desktop_login(
+    desktop_login: str, client: KitsuClient = default
+) -> dict | None:
     """
     Args:
         desktop_login (str): Login used to sign in on the desktop computer.
@@ -140,7 +162,9 @@ def get_person_by_desktop_login(desktop_login, client=default):
 
 
 @cache
-def get_person_by_email(email, client=default):
+def get_person_by_email(
+    email: str, client: KitsuClient = default
+) -> dict | None:
     """
     Args:
         email (str): User's email.
@@ -155,8 +179,11 @@ def get_person_by_email(email, client=default):
 
 @cache
 def get_person_by_full_name(
-    full_name, first_name=None, last_name=None, client=default
-):
+    full_name: str,
+    first_name: str | None = None,
+    last_name: str | None = None,
+    client: KitsuClient = default,
+) -> dict | None:
     """
     Args:
         full_name (str): User's full name
@@ -164,7 +191,7 @@ def get_person_by_full_name(
         last_name (str): User's last name
 
     Returns:
-        dict: Person corresponding to given name.
+        dict: Person corresponding to given name, or None if not found.
     """
     if first_name is not None and last_name is not None:
         return raw.fetch_first(
@@ -185,7 +212,7 @@ def get_person_by_full_name(
 
 
 @cache
-def get_person_url(person, client=default):
+def get_person_url(person: str | dict, client: KitsuClient = default) -> str:
     """
     Args:
         person (str / dict): The person dict or the person ID.
@@ -202,7 +229,7 @@ def get_person_url(person, client=default):
 
 
 @cache
-def get_organisation(client=default):
+def get_organisation(client: KitsuClient = default) -> dict:
     """
     Returns:
         dict: Database information for organisation linked to auth tokens.
@@ -210,16 +237,22 @@ def get_organisation(client=default):
     return raw.get("auth/authenticated", client=client)["organisation"]
 
 
-def new_department(name, color="", archived=False, client=default):
+def new_department(
+    name: str,
+    color: str = "",
+    archived: bool = False,
+    client: KitsuClient = default,
+) -> dict:
     """
-    Create a new departement based on given parameters.
+    Create a new department based on given parameters.
 
     Args:
-        name (str): the name of the departement.
-        color (str): the color of the departement.
-        archived (bool): Whether the departement is archived or not.
+        name (str): the name of the department.
+        color (str): the color of the department as a Hex string, e.g "#00FF00".
+        archived (bool): Whether the department is archived or not.
+
     Returns:
-        dict: Created departement.
+        dict: Created department.
     """
     department = get_department_by_name(name, client=client)
     if department is None:
@@ -231,19 +264,53 @@ def new_department(name, color="", archived=False, client=default):
     return department
 
 
+def update_department(department, client=default):
+    """
+    Update a department.
+
+    Args:
+        department (dict): The department dict that needs to be updated.
+
+    Returns:
+        dict: The updated department.
+    """
+    department = normalize_model_parameter(department)
+    return raw.put(
+        "data/departments/%s" % (department["id"]),
+        department,
+        client=client,
+    )
+
+
+def remove_department(department, force=False, client=default):
+    """
+    Remove given department from database.
+
+    Args:
+        department (dict / ID): Department to remove.
+        force (bool): Whether to force deletion of the department.
+    """
+    department = normalize_model_parameter(department)
+    path = "data/departments/%s" % department["id"]
+    params = {}
+    if force:
+        params = {"force": True}
+    return raw.delete(path, params, client=client)
+
+
 def new_person(
-    first_name,
-    last_name,
-    email,
-    phone="",
-    role="user",
-    desktop_login="",
-    departments=[],
-    password=None,
-    active=True,
-    contract_type="open-ended",
-    client=default,
-):
+    first_name: str,
+    last_name: str,
+    email: str,
+    phone: str = "",
+    role: str = "user",
+    desktop_login: str = "",
+    departments: list[str | dict] = [],
+    password: str | None = None,
+    active: bool = True,
+    contract_type: str = "open-ended",
+    client: KitsuClient = default,
+) -> dict:
     """
     Create a new person based on given parameters. His/her password will is
     set automatically to default.
@@ -253,12 +320,13 @@ def new_person(
         last_name (str): the last name of the person.
         email (str): the email of the person.
         phone (str): the phone number of the person.
-        role (str): user, manager, admin (wich match CG artist, Supervisor
+        role (str): user, manager, admin (which match CG artist, Supervisor
                     and studio manager)
         desktop_login (str): The login the users uses to log on its computer.
         departments (list): The departments for the person.
         password (str): The password for the person.
         active (bool): Whether the person is active or not.
+
     Returns:
         dict: Created person.
     """
@@ -283,7 +351,7 @@ def new_person(
     return person
 
 
-def update_person(person, client=default):
+def update_person(person: dict, client: KitsuClient = default) -> dict:
     """
     Update a person.
 
@@ -307,7 +375,9 @@ def update_person(person, client=default):
     )
 
 
-def remove_person(person, force=False, client=default):
+def remove_person(
+    person: str, force: bool = False, client: KitsuClient = default
+) -> str:
     """
     Remove given person from database.
 
@@ -323,14 +393,14 @@ def remove_person(person, force=False, client=default):
 
 
 def new_bot(
-    name,
-    email,
-    role="user",
-    departments=[],
-    active=True,
-    expiration_date=None,
-    client=default,
-):
+    name: str,
+    email: str,
+    role: str = "user",
+    departments: list[str | dict] = [],
+    active: bool = True,
+    expiration_date: str | None = None,
+    client: KitsuClient = default,
+) -> dict:
     """
     Create a new bot based on given parameters. His access token will be in the
     return dict.
@@ -338,11 +408,12 @@ def new_bot(
     Args:
         name (str): the name of the bot.
         email (str): the email of the bot.
-        role (str): user, manager, admin (wich match CG artist, Supervisor
+        role (str): user, manager, admin (which match CG artist, Supervisor
                     and studio manager)
         departments (list): The departments for the person.
         active (bool): Whether the person is active or not.
         expiration_date (str): The expiration date for the bot.
+
     Returns:
         dict: Created bot.
     """
@@ -363,7 +434,7 @@ def new_bot(
     return bot
 
 
-def update_bot(bot, client=default):
+def update_bot(bot: dict, client: KitsuClient = default) -> dict:
     """
     Update a bot.
 
@@ -376,7 +447,9 @@ def update_bot(bot, client=default):
     return update_person(bot, client=client)
 
 
-def remove_bot(bot, force=False, client=default):
+def remove_bot(
+    bot: dict, force: bool = False, client: KitsuClient = default
+) -> str:
     """
     Remove given bot from database.
 
@@ -386,7 +459,9 @@ def remove_bot(bot, force=False, client=default):
     return remove_person(bot, force=force, client=client)
 
 
-def set_avatar(person, file_path, client=default):
+def set_avatar(
+    person: str | dict, file_path: str, client: KitsuClient = default
+) -> dict[Literal["thumbnail_path"], str]:
     """
     Upload picture and set it as avatar for given person.
 
@@ -394,6 +469,10 @@ def set_avatar(person, file_path, client=default):
         person (str / dict): The person dict or the person ID.
         file_path (str): Path where the avatar file is located on the hard
                          drive.
+
+    Returns:
+        dict: Dictionary with a key of 'thumbnail_path' and a value of the
+            path to the static image file, relative to the host url.
     """
     person = normalize_model_parameter(person)
     return raw.upload(
@@ -403,26 +482,32 @@ def set_avatar(person, file_path, client=default):
     )
 
 
-def get_presence_log(year, month, client=default):
+def get_presence_log(
+    year: int, month: int, client: KitsuClient = default
+) -> str:
     """
     Args:
-        year (int):
-        month (int):
+        year (int): The number of the year to fetch logs during.
+        month (int): The index of the month to get presence logs for. Indexed
+            from 1, e.g 1 = January, 2 = February, ...
 
     Returns:
-        The presence log table for given month and year.
+        str: The presence log table (in CSV) for given month and year.
     """
     path = "data/persons/presence-logs/%s-%s" % (year, str(month).zfill(2))
     return raw.get(path, json_response=False, client=client)
 
 
-def change_password_for_person(person, password, client=default):
+def change_password_for_person(
+    person: str | dict, password: str, client: KitsuClient = default
+) -> dict[Literal["success"], bool]:
     """
     Change the password for given person.
 
     Args:
         person (str / dict): The person dict or the person ID.
         password (str): The new password.
+
     Returns:
         dict: success or not.
     """
@@ -434,12 +519,17 @@ def change_password_for_person(person, password, client=default):
     )
 
 
-def invite_person(person, client=default):
+def invite_person(
+    person: str | dict, client: KitsuClient = default
+) -> dict[str, str]:
     """
     Sends an email to given person to invite him/her to connect to Kitsu.
 
     Args:
-        person (dict): The person to invite.
+        person (str / dict): The person to invite.
+
+    Returns:
+        dict: Response dict with 'success' and 'message' keys.
     """
     person = normalize_model_parameter(person)
     return raw.get(
@@ -449,12 +539,14 @@ def invite_person(person, client=default):
 
 
 @cache
-def get_time_spents_by_date(person, date, client=default):
+def get_time_spents_by_date(
+    person: str | dict, date: str, client: KitsuClient = default
+) -> list[dict]:
     """
     Get time spents for a person on a specific date.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
         date (str): Date in YYYY-MM-DD format.
 
     Returns:
@@ -469,12 +561,14 @@ def get_time_spents_by_date(person, date, client=default):
 
 
 @cache
-def get_week_time_spents(person, year, week, client=default):
+def get_week_time_spents(
+    person: str | dict, year: int, week: int, client: KitsuClient = default
+) -> list[dict]:
     """
     Get time spents for a person for a specific week.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
         year (int): Year.
         week (int): Week number.
 
@@ -489,12 +583,14 @@ def get_week_time_spents(person, year, week, client=default):
 
 
 @cache
-def get_year_time_spents(person, year, client=default):
+def get_year_time_spents(
+    person: str | dict, year: int, client: KitsuClient = default
+) -> list[dict]:
     """
     Get time spents for a person for a specific year.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
         year (int): Year.
 
     Returns:
@@ -508,29 +604,31 @@ def get_year_time_spents(person, year, client=default):
 
 
 @cache
-def get_day_offs(person, client=default):
+def get_day_offs(
+    person: str | dict, client: KitsuClient = default
+) -> list[dict]:
     """
     Get day offs for a person.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
 
     Returns:
         list: Day offs for the person.
     """
     person = normalize_model_parameter(person)
-    return raw.fetch_all(
-        "persons/%s/day-offs" % person["id"], client=client
-    )
+    return raw.fetch_all("persons/%s/day-offs" % person["id"], client=client)
 
 
 @cache
-def get_week_day_offs(person, year, week, client=default):
+def get_week_day_offs(
+    person: str | dict, year: int, week: int, client: KitsuClient = default
+) -> list[dict]:
     """
     Get day offs for a person for a specific week.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
         year (int): Year.
         week (int): Week number.
 
@@ -545,12 +643,14 @@ def get_week_day_offs(person, year, week, client=default):
 
 
 @cache
-def get_month_day_offs(person, year, month, client=default):
+def get_month_day_offs(
+    person: str | dict, year: int, month: int, client: KitsuClient = default
+) -> list[dict]:
     """
     Get day offs for a person for a specific month.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
         year (int): Year.
         month (int): Month number.
 
@@ -566,12 +666,14 @@ def get_month_day_offs(person, year, month, client=default):
 
 
 @cache
-def get_year_day_offs(person, year, client=default):
+def get_year_day_offs(
+    person: str | dict, year: int, client: KitsuClient = default
+) -> list[dict]:
     """
     Get day offs for a person for a specific year.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
         year (int): Year.
 
     Returns:
@@ -584,13 +686,15 @@ def get_year_day_offs(person, year, client=default):
     )
 
 
-def add_person_to_department(person, department, client=default):
+def add_person_to_department(
+    person: str | dict, department: str | dict, client: KitsuClient = default
+) -> dict:
     """
     Add a person to a department.
 
     Args:
-        person (dict / ID): The person dict or id.
-        department (dict / ID): The department dict or id.
+        person (str / dict): The person dict or id.
+        department (str / dict): The department dict or id.
 
     Returns:
         dict: Response information.
@@ -604,13 +708,15 @@ def add_person_to_department(person, department, client=default):
     )
 
 
-def remove_person_from_department(person, department, client=default):
+def remove_person_from_department(
+    person: str | dict, department: str | dict, client: KitsuClient = default
+) -> str:
     """
     Remove a person from a department.
 
     Args:
-        person (dict / ID): The person dict or id.
-        department (dict / ID): The department dict or id.
+        person (str / dict): The person dict or id.
+        department (str / dict): The department dict or id.
 
     Returns:
         Response: Request response object.
@@ -623,12 +729,14 @@ def remove_person_from_department(person, department, client=default):
     )
 
 
-def disable_two_factor_authentication(person, client=default):
+def disable_two_factor_authentication(
+    person: str | dict, client: KitsuClient = default
+) -> str:
     """
     Disable two factor authentication for a person.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
 
     Returns:
         Response: Request response object.
@@ -640,17 +748,17 @@ def disable_two_factor_authentication(person, client=default):
     )
 
 
-def clear_person_avatar(person, client=default):
+def clear_person_avatar(
+    person: str | dict, client: KitsuClient = default
+) -> str:
     """
     Clear avatar for a person.
 
     Args:
-        person (dict / ID): The person dict or id.
+        person (str / dict): The person dict or id.
 
     Returns:
         Response: Request response object.
     """
     person = normalize_model_parameter(person)
-    return raw.delete(
-        "data/persons/%s/avatar" % person["id"], client=client
-    )
+    return raw.delete("data/persons/%s/avatar" % person["id"], client=client)