papi-projects 0.3.1__tar.gz → 0.4.1__tar.gz

{papi_projects-0.3.1 → papi_projects-0.4.1}/PKG-INFO

@@ -1,21 +1,17 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: papi-projects
-Version: 0.3.1
+Version: 0.4.1
 Summary: PAPI is an API for managing projects
-License: MIT
-Author: sandyjmacdonald
-Author-email: sandyjmacdonald@gmail.com
-Requires-Python: >=3.11,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: httpx (>=0.27.2,<0.28.0)
-Requires-Dist: pendulum (>=3.0.0,<4.0.0)
-Requires-Dist: pyperclip (>=1.9.0,<2.0.0)
-Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
-Requires-Dist: tinydb (>=4.8.0,<5.0.0)
+Author-email: sandyjmacdonald <sandyjmacdonald@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
+Requires-Dist: pendulum>=3.0.0
+Requires-Dist: httpx>=0.27.2
+Requires-Dist: tinydb>=4.8.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyperclip>=1.9.0
+Requires-Dist: pandas>=2.3.3
 
 PAPI is an API for managing projects.
 
@@ -373,4 +369,3 @@ usr.user_id = "JS1"
 ```
 
 Setting the `user_id` attribute creates the possibility of a clash in user IDs, therefore the `user` module provides a means to create a basic user database with the TinyDB library. This avoids the possibility of a clash and appends and increments integer numbers to the end of the user ID if a matching one is already in the database.
-

{papi_projects-0.3.1 → papi_projects-0.4.1}/papi/__init__.py

@@ -1,18 +1,64 @@
 import os
 import logging
 from dotenv import dotenv_values
+from pathlib import Path
 
-dotenv_path = os.path.join(os.path.dirname(__file__), '.env')
-config = dotenv_values(dotenv_path)
+def load_config():
+    user_env_path = Path.home() / ".config" / "papi" / ".env"
+    config = {}
+
+    if user_env_path.exists():
+        config.update(dotenv_values(user_env_path))
+
+    for key in (
+        "TOGGL_TRACK_API_KEY",
+        "TOGGL_TRACK_PASSWORD",
+        "NOTION_API_SECRET",
+        "NOTION_CLIENTS_DB",
+        "NOTION_PROJECTS_DB",
+        "NOTION_TASKS_DB",
+        "NOTION_TEMPLATE_PAGE_ID",
+        "NOTION_WORKORDERS_DB",
+        "NOTION_TRAC_COSTS_DB",
+    ):
+        if key in os.environ:
+            config[key] = os.environ[key]
+
+    local_env_path = Path(__file__).parent / ".env"
+    if local_env_path.exists():
+        local_vals = dotenv_values(local_env_path)
+        for k, v in local_vals.items():
+            config.setdefault(k, v)
+
+    return config
+
+config = load_config()
 
 TOGGL_TRACK_API_KEY = config["TOGGL_TRACK_API_KEY"]
 TOGGL_TRACK_PASSWORD = config["TOGGL_TRACK_PASSWORD"]
-
 NOTION_API_SECRET = config["NOTION_API_SECRET"]
 NOTION_CLIENTS_DB = config["NOTION_CLIENTS_DB"]
 NOTION_PROJECTS_DB = config["NOTION_PROJECTS_DB"]
 NOTION_TASKS_DB = config["NOTION_TASKS_DB"]
 NOTION_TEMPLATE_PAGE_ID = config["NOTION_TEMPLATE_PAGE_ID"]
+NOTION_WORKORDERS_DB = config["NOTION_WORKORDERS_DB"]
+NOTION_TRAC_COSTS_DB = config["NOTION_TRAC_COSTS_DB"]
+
+required = [
+    "TOGGL_TRACK_API_KEY",
+    "TOGGL_TRACK_PASSWORD",
+    "NOTION_API_SECRET",
+    "NOTION_CLIENTS_DB",
+    "NOTION_PROJECTS_DB",
+    "NOTION_TASKS_DB",
+    "NOTION_TEMPLATE_PAGE_ID",
+    "NOTION_WORKORDERS_DB",
+    "NOTION_TRAC_COSTS_DB",
+]
+
+missing = [k for k in required if k not in config]
+if missing:
+    raise RuntimeError(f"Missing required config values: {', '.join(missing)}")
 
 def setup_logger(enable_logging: bool, log_level: str = 'INFO', log_file: str = None):
     logger = logging.getLogger('papi')
@@ -44,4 +90,4 @@ def setup_logger(enable_logging: bool, log_level: str = 'INFO', log_file: str =
         # Set a higher log level to suppress lower-level logs
         logger.setLevel(logging.WARNING)
     
-    return logger
+    return logger

{papi_projects-0.3.1 → papi_projects-0.4.1}/papi/project.py

@@ -266,6 +266,7 @@ class Project(Protocol):
             f"    user_id = {self.user_id},\n"
             f"    priority = {self.priority}\n"
             f"    status = {self.status}\n"
+            f"    workorder = {self.workorder}\n"
             f"    owner = {self.owner}\n"
             f"    notion_page_id = {self.notion_page_id}\n"
             f")"

papi_projects-0.4.1/papi/workorder.py

@@ -0,0 +1,100 @@
+import warnings
+import logging
+from typing import Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+@runtime_checkable
+class Workorder(Protocol):
+    """This class represents a workorder and all of its associated metadata.
+
+    :param id: The Workorder ID e.g. R123456.
+        Often starts with R, M, or A depending on the workorder type.
+    :type id: str, required
+    :param user_id: The ID of the user to which the workorder belongs,
+        defaults to None.
+    :type user_id: str, optional
+    :param funder: The funding source, e.g. Internal or BBSRC, defaults to None.
+    :type funder: str, optional
+    :param trac_type: TRAC type, e.g. Internal FEC, defaults to None.
+    :type trac_type: str, optional
+    :param project_location: e.g. Internal or External, defaults to None.
+    :type project_location: str, optional
+    :param costing_rate: Charity or FEC, defaults to None.
+    :type costing_rate: str, optional
+    :param payment_type: DI or DA, defaults to None.
+    :type payment_type: str, optional
+    :param hourly_rate: The hourly rate to charge, defaults to None.
+    :type hourly_rate: float, optional
+    :param notion_page_id: The internal Notion page UUID for this workorder.
+    :type notion_page_id: str, optional
+    """
+
+    def __init__(
+        self,
+        id: str = None,
+        user_id: str = None,
+        funder: str = None,
+        trac_type: str = None,
+        project_location: str = None,
+        costing_rate: str = None,
+        payment_type: str = None,
+        hourly_rate: float = None,
+        notion_page_id: str = None
+    ) -> None:
+        """Constructor method"""
+        logger.debug("Creating Workorder instance")
+        self.id = id
+        self.user_id = user_id
+        self.funder = funder
+        if trac_type is not None:
+            self.trac_type = trac_type
+            self.project_location, self.costing_rate = trac_type.split()
+        else:
+            self.project_location = project_location
+            self.costing_rate = costing_rate
+            self.trac_type = f"{project_location} {costing_rate}"
+        self.payment_type = payment_type
+        self.hourly_rate = hourly_rate
+        self.notion_page_id = notion_page_id
+        self.required_fields = [
+            "id",
+            "project_location",
+            "costing_rate",
+            "trac_type",
+            "payment_type",
+            "hourly_rate",
+        ]
+
+        logger.info(f"Workorder: '{self.id}' instance created")
+
+    def __str__(self) -> str:
+        """Machine-readable representation of class..
+
+        :return: basic Workorder() attrs.
+        :rtype: str
+        """
+        logger.debug("Calling Workorder.__str__ method")
+        return (
+            f"Workorder(\n"
+            f"    id = {self.id},\n"
+            f"    user_id = {self.user_id},\n"
+            f"    funder = {self.funder},\n"
+            f"    trac_type = {self.trac_type},\n"
+            f"    project_location = {self.project_location},\n"
+            f"    costing_rate = {self.costing_rate},\n"
+            f"    payment_type = {self.payment_type},\n"
+            f"    hourly_rate = {self.hourly_rate},\n"
+            f"    notion_page_id = {self.notion_page_id}\n"
+            f")"
+        )
+
+    def is_complete(self) -> bool:
+        """Checks whether the workorder details are complete.
+
+        :return: True/False as appropriate
+        :rtype: bool
+        """
+        logger.debug("Calling Workorder.is_complete method")
+
+        return all(getattr(self, field) is not None for field in self.required_fields)

{papi_projects-0.3.1 → papi_projects-0.4.1}/papi/wrappers.py

@@ -10,6 +10,7 @@ from pprint import pprint
 from papi.project import Project, get_project_ids, decompose_project_name
 from papi.task import Task
 from papi.user import User
+from papi.workorder import Workorder
 
 logger = logging.getLogger(__name__)
 
@@ -599,6 +600,212 @@ class NotionWrapper(Protocol):
             logger.warning("No Notion users found")
         return users
 
+    def get_trac_costs(
+        self,
+        trac_costs_db_id: str,
+        key: str,
+    ) -> dict:
+        """
+        Fetches TRAC costs give a TRAC type key.
+
+        You must pass both of `trac_costs_db_id` and `key`.
+
+        :param trac_costs_db_id: ID of the Notion TRAC Costs database to query.
+        :type trac_costs_db_id: str
+        :param key: The TRAC type key e.g. Internal Charity.
+        :return: A dictionary with the TRAC costs data.
+        :rtype: dict
+        """
+        logger.debug("Calling NotionWrapper.get_trac_costs method")
+        headers = self._headers()
+        body = {
+            "page_size": 1,
+            "filter": {
+                "property": "key",
+                "title": {"equals": key}
+            }
+        }
+        url = f"https://api.notion.com/v1/databases/{trac_costs_db_id}/query"
+        request = lambda: self._post_with_retries(
+            url, headers=headers, json=body,
+            timeout=httpx.Timeout(5.0, read=15.0),
+        )
+        try:
+            resp = request()
+            resp.raise_for_status()
+        except httpx.ReadTimeout:
+            logger.error("Notion TRAC costs lookup timed out after retries")
+            return None
+        except httpx.HTTPError as err:
+            logger.error(f"Failed to fetch TRAC costs: {err!r}")
+            return None
+        # Extract the page dict, whether from query or retrieve
+        results = resp.json().get("results", [])
+        if not results:
+            logger.warning(f"No TRAC cost found with key={key!r}")
+            return None
+        page = results[0]
+        props = page.get("properties", {})
+        rate_raw = props["Rate"]["number"]
+        try:
+            rate = float(rate_raw)
+        except (TypeError, ValueError):
+            raise ValueError(f"TRAC rate must be convertible to float, got: {rate_raw}")
+        trac_cost = {key: rate}
+
+        return trac_cost 
+
+    def get_workorder(
+        self,
+        workorders_db_id: str,
+        workorder_id: str | None = None,
+        notion_page_id: str | None = None,
+        trac_costs_db_id: str | None = None,
+    ) -> Workorder | None:
+        """
+        Fetches a single workorder, either by its workorder ID
+        or by its Notion page ID.
+
+        You must pass exactly one of `workorder_id` or `notion_page_id`.
+
+        :param workorders_db_id: ID of the Notion Workorders database to query.
+        :type workorders_db_id: str
+        :param workorder_id: The value of the "Workorder" property to match.
+        :type workorder_id: str or None
+        :param notion_page_id: The Notion page ID of the workorder to retrieve.
+        :type notion_page_id: str or None
+        :param trac_costs_db_id: ID of the Notion TRAC costs database to query.
+        :type trac_costs_db_id: str
+        :return: A Workorder instance if found, otherwise None.
+        :rtype: Workorder | None
+        """
+        logger.debug("Calling NotionWrapper.get_workorder method")
+        headers = self._headers()
+        if bool(workorder_id) == bool(notion_page_id):
+            logger.error("Must provide exactly one of workorder_id or notion_page_id")
+            return None
+        if workorder_id:
+            body = {
+                "page_size": 1,
+                "filter": {
+                    "property": "Workorder",
+                    "title": {"equals": workorder_id}
+                }
+            }
+            url = f"https://api.notion.com/v1/databases/{workorders_db_id}/query"
+            request = lambda: self._post_with_retries(
+                url, headers=headers, json=body,
+                timeout=httpx.Timeout(5.0, read=15.0),
+            )
+        else:
+            url = f"https://api.notion.com/v1/pages/{notion_page_id}"
+            request = lambda: httpx.get(
+                url, headers=headers,
+                timeout=httpx.Timeout(5.0, read=15.0),
+            )
+        try:
+            resp = request()
+            resp.raise_for_status()
+        except httpx.ReadTimeout:
+            logger.error("Notion workorder lookup timed out after retries")
+            return None
+        except httpx.HTTPError as err:
+            logger.error(f"Failed to fetch workorder: {err!r}")
+            return None
+        # Extract the page dict, whether from query or retrieve
+        if workorder_id:
+            results = resp.json().get("results", [])
+            if not results:
+                logger.warning(f"No workorder found with Workorder ID={workorder_id!r}")
+                return None
+            page = results[0]
+        else:
+            page = resp.json()
+
+        props = page.get("properties", {})
+        try:
+            notion_page_id = page["id"]
+            if props["Funder"]["select"] is not None:
+                funder = props["Funder"]["select"]["name"]
+            else:
+                funder = None
+            if props["Payment Type"]["select"] is not None:
+                payment_type = props["Payment Type"]["select"]["name"]
+            else:
+                payment_type = None
+            id = props["Workorder"]["title"][0]["plain_text"]
+            if len(props["Project Location"]["rollup"]["array"]):
+                project_location = props["Project Location"]["rollup"]["array"][0]["select"]["name"]
+            else:
+                project_location = None
+            if len(props["Costing"]["rollup"]["array"]):
+                costing_rate = props["Costing"]["rollup"]["array"][0]["select"]["name"]
+            else:
+                costing_rate = None
+            if len(props["Hourly Rate"]["rollup"]["array"]):
+                hourly_rate = props["Hourly Rate"]["rollup"]["array"][0]["number"]
+            else:
+                hourly_rate = None
+
+            workorder = Workorder(
+                id=id,
+                funder=funder,
+                project_location=project_location,
+                costing_rate=costing_rate,
+                payment_type=payment_type,
+                hourly_rate=hourly_rate,
+                notion_page_id=notion_page_id,
+            )
+        except (KeyError, IndexError) as e:
+            logger.error(f"Malformed workorder properties on page {nid!r}: {e!r}")
+            return None
+
+        # logger.info(f"Notion project loaded: {pid!r} → page {nid}")
+        return workorder 
+
+    def get_workorders(self, workorders_db_id: str) -> list:
+        """Gets the Notion workorders from the Workorders database.
+
+        :param workorders_db_id: ID of the Notion Workorders database from which to get
+        the workorders.
+        :type workorders_db_id: str
+        :return: A list of Workorder instances from Notion.
+        :rtype: list
+        """
+        logger.debug("Calling NotionWrapper.get_workorders method")
+        headers = self._headers()
+        data = {}
+        r = httpx.post(
+            f"https://api.notion.com/v1/databases/{workorders_db_id}/query",
+            headers=headers,
+            json=data,
+        )
+        r_json = r.json()
+        workorders = []
+        for w in r_json["results"]:
+            notion_page_id = w["id"]
+            if w["properties"]["Funder"]["select"] is not None:
+                funder = w["properties"]["Funder"]["select"]["name"]
+            else:
+                funder = None
+            if w["properties"]["Payment Type"]["select"] is not None:
+                payment_type = w["properties"]["Payment Type"]["select"]["name"]
+            else:
+                payment_type = None
+            id = w["properties"]["Workorder"]["title"][0]["plain_text"]
+            workorder = Workorder(
+                id=id,
+                funder=funder,
+                payment_type=payment_type,
+                notion_page_id=notion_page_id,
+            )
+        if len(workorders):
+            logger.info(f"{len(workorders)} Notion workorders found")
+        else:
+            logger.warning("No Notion workorders found")
+        return workorders
+
+
     def check_project_exists(self, project: Project, projects_db_id: str) -> Project:
         """Checks whether a Notion project containing the specified
         project ID already exists. If a name containing that ID is found,
@@ -793,6 +1000,7 @@ class NotionWrapper(Protocol):
         projects_db_id: str,
         project_id: str | None = None,
         notion_page_id: str | None = None,
+        workorders_db_id: str | None = None,
     ) -> Project | None:
         """
         Fetches a single project, either by its custom "Project ID" property
@@ -806,6 +1014,8 @@ class NotionWrapper(Protocol):
         :type project_id: str or None
         :param notion_page_id: The Notion page ID of the project to retrieve.
         :type notion_page_id: str or None
+        :param workorders_db_id: ID of the Notion Workorders database to query.
+        :type workorders_db_id: str or None
         :return: A Project instance if found, otherwise None.
         :rtype: Project | None
         """
@@ -867,13 +1077,27 @@ class NotionWrapper(Protocol):
             priority = props["Priority"]["select"]["name"]
             user_id = props["PI Code"]["rollup"]["array"][0]["rich_text"][0]["plain_text"]
             nid = page["id"]
+            if len(props["Workorder"]["relation"]):
+                workorder_page_id = props["Workorder"]["relation"][0]["id"]
+            else:
+                workorder_page_id = None
         except (KeyError, IndexError) as e:
             logger.error(f"Malformed project properties on page {nid!r}: {e!r}")
             return None
 
+        if workorders_db_id is not None and workorder_page_id is not None:
+            workorder = self.get_workorder(workorders_db_id=workorders_db_id, notion_page_id=workorder_page_id)
+            if workorder is not None:
+                workorder_id = workorder.id
+            else:
+                workorder_id = None
+        else:
+            workorder_id = None
+
         project = Project(
             id=pid,
             name=name,
+            workorder=workorder_id,
             user_id=user_id,
             owner=owner,
             status=status,
@@ -1119,4 +1343,4 @@ class NotionWrapper(Protocol):
         created = r.json()
         task.notion_page_id = created.get("id")
         logger.info(f'Added task "{task.name!r}" with ID {task.notion_page_id} to {project_id}')
-        return task
+        return task