papi-projects 0.1.3__tar.gz → 0.1.6__tar.gz

{papi_projects-0.1.3 → papi_projects-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: papi-projects
-Version: 0.1.3
+Version: 0.1.6
 Summary: PAPI is an API for managing projects
 License: MIT
 Author: sandyjmacdonald
@@ -129,3 +129,153 @@ To collate your hours worked in August 2024:
 ```
 collate-toggl-hours -s 2024-08-01 -e 2024-08-31 -o august-2024-hours.tsv
 ```
+
+## API reference
+
+## project module
+
+## Project class
+
+The `Project` class is central to the whole library. A `Project` instance can be created in a few different ways.
+
+At the most basic level, a valid `user_id` (either three letter initials or two letter initials and an integer number from 1 to 9) can be provided when instantiating the class, and the prefix and suffix will be generated.
+
+```
+from papi.project import Project
+
+proj = Project(user_id="CRD")
+```
+
+This will generate the project ID, `id` attribute using the current year, and a random four-letter suffix.
+
+```
+print(proj.id)
+print(proj.year)
+print(proj.suffix)
+```
+
+```
+P2024-CRD-FZLL
+2024
+FZLL
+```
+
+If a valid project ID has already been created, then a `Project` instance can be instantiated with the `id` attribute, and the `year`, `user_id`, and `suffix` attributes will be pulled out and set on the instance.
+
+```
+proj = Project(id="P2024-CRD-FZLL")
+
+print(proj.year)
+print(proj.user_id)
+print(proj.suffix)
+```
+
+```
+2024
+CRD
+FZLL
+```
+
+If a grant code and/or project name are available, then these can be passed in when instantiating the class.
+
+```
+proj = Project(user_id="CRD", grant_code="R12345", name="RNA-seq analysis")
+```
+
+A version 4 UUID is also generated for the project when instantiated.
+
+```
+proj = Project(user_id="CRD")
+
+print(proj.p_uuid)
+```
+
+```
+6697e457-9785-4668-b78b-72616b27aede
+```
+
+ Or if a version 4 UUID has been generated separately then it can be provided when instantiating.
+
+ ```
+ proj = Project(user_id="CRD", p_uuid="6697e457-9785-4668-b78b-72616b27aede")
+ ```
+
+## project functions
+
+A couple of functions are provided to check the validity of a project ID, to check the validity of a suffix, and to check for a valid version 4 UUID.
+
+You can check the validity of a project ID as follows:
+
+```
+from papi.project import check_project_id
+
+print(check_project_id("P2024-CRD-FZLL"))
+print(check_project_id("P2024-CRD-1234"))
+```
+
+```
+True
+False
+```
+
+You can check the validity of a project suffix as follows:
+
+```
+from papi.project import check_suffix
+
+print(check_suffix("FZLL"))
+print(check_suffix("1234"))
+```
+
+```
+True
+False
+```
+
+## user module
+
+## User class
+
+The `User` class stores attributes of a user: their name, a three-letter initial (or two-letter initial and integer number from 1 to 9), and an optional email address.
+
+The most basic way of instantiating a `User` instance is as follows:
+
+```
+from papi.user import User
+
+usr = User("Charles Robert Darwin")
+
+print(usr.user_id)
+print(usr.user_name)
+```
+
+```
+CRD
+Charles Robert Darwin
+```
+
+The first initials are converted into the `user_id` attribute.
+
+If an email address is available, then this can be provided when instantiating:
+
+```
+from papi.user import User
+
+usr = User("Charles Robert Darwin", email="cdarwin@beaglemail.com")
+
+print(usr.email)
+```
+
+```
+cdarwin@beaglemail.com
+```
+
+Because our user ID naming scheme enforces that a user ID must be unique, the `user_id` attribute should not really be set directly, although it can in theory:
+
+```
+usr = User("Charles Darwin")
+usr.user_id = "CD1"
+```
+
+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.1.3 → papi_projects-0.1.6}/README.md

@@ -110,4 +110,153 @@ To collate your hours worked in August 2024:
 
 ```
 collate-toggl-hours -s 2024-08-01 -e 2024-08-31 -o august-2024-hours.tsv
-```
+```
+
+## API reference
+
+## project module
+
+## Project class
+
+The `Project` class is central to the whole library. A `Project` instance can be created in a few different ways.
+
+At the most basic level, a valid `user_id` (either three letter initials or two letter initials and an integer number from 1 to 9) can be provided when instantiating the class, and the prefix and suffix will be generated.
+
+```
+from papi.project import Project
+
+proj = Project(user_id="CRD")
+```
+
+This will generate the project ID, `id` attribute using the current year, and a random four-letter suffix.
+
+```
+print(proj.id)
+print(proj.year)
+print(proj.suffix)
+```
+
+```
+P2024-CRD-FZLL
+2024
+FZLL
+```
+
+If a valid project ID has already been created, then a `Project` instance can be instantiated with the `id` attribute, and the `year`, `user_id`, and `suffix` attributes will be pulled out and set on the instance.
+
+```
+proj = Project(id="P2024-CRD-FZLL")
+
+print(proj.year)
+print(proj.user_id)
+print(proj.suffix)
+```
+
+```
+2024
+CRD
+FZLL
+```
+
+If a grant code and/or project name are available, then these can be passed in when instantiating the class.
+
+```
+proj = Project(user_id="CRD", grant_code="R12345", name="RNA-seq analysis")
+```
+
+A version 4 UUID is also generated for the project when instantiated.
+
+```
+proj = Project(user_id="CRD")
+
+print(proj.p_uuid)
+```
+
+```
+6697e457-9785-4668-b78b-72616b27aede
+```
+
+ Or if a version 4 UUID has been generated separately then it can be provided when instantiating.
+
+ ```
+ proj = Project(user_id="CRD", p_uuid="6697e457-9785-4668-b78b-72616b27aede")
+ ```
+
+## project functions
+
+A couple of functions are provided to check the validity of a project ID, to check the validity of a suffix, and to check for a valid version 4 UUID.
+
+You can check the validity of a project ID as follows:
+
+```
+from papi.project import check_project_id
+
+print(check_project_id("P2024-CRD-FZLL"))
+print(check_project_id("P2024-CRD-1234"))
+```
+
+```
+True
+False
+```
+
+You can check the validity of a project suffix as follows:
+
+```
+from papi.project import check_suffix
+
+print(check_suffix("FZLL"))
+print(check_suffix("1234"))
+```
+
+```
+True
+False
+```
+
+## user module
+
+## User class
+
+The `User` class stores attributes of a user: their name, a three-letter initial (or two-letter initial and integer number from 1 to 9), and an optional email address.
+
+The most basic way of instantiating a `User` instance is as follows:
+
+```
+from papi.user import User
+
+usr = User("Charles Robert Darwin")
+
+print(usr.user_id)
+print(usr.user_name)
+```
+
+```
+CRD
+Charles Robert Darwin
+```
+
+The first initials are converted into the `user_id` attribute.
+
+If an email address is available, then this can be provided when instantiating:
+
+```
+from papi.user import User
+
+usr = User("Charles Robert Darwin", email="cdarwin@beaglemail.com")
+
+print(usr.email)
+```
+
+```
+cdarwin@beaglemail.com
+```
+
+Because our user ID naming scheme enforces that a user ID must be unique, the `user_id` attribute should not really be set directly, although it can in theory:
+
+```
+usr = User("Charles Darwin")
+usr.user_id = "CD1"
+```
+
+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.1.6/papi/__init__.py

@@ -0,0 +1,48 @@
+import os
+import logging
+from dotenv import dotenv_values
+
+dotenv_path = os.path.join(os.path.dirname(__file__), '.env')
+config = dotenv_values(dotenv_path)
+
+ASANA_API_KEY = config["ASANA_API_KEY"]
+ASANA_PASSWORD = config["ASANA_PASSWORD"]
+
+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"]
+
+def setup_logger(enable_logging: bool, log_level: str = 'INFO', log_file: str = None):
+    logger = logging.getLogger('papi')
+    
+    if enable_logging:
+        # Convert log_level string to logging level
+        numeric_level = getattr(logging, log_level.upper(), logging.INFO)
+        logger.setLevel(numeric_level)
+        
+        # Create handler
+        if log_file:
+            handler = logging.FileHandler(log_file)
+        else:
+            handler = logging.StreamHandler()
+        
+        handler.setLevel(numeric_level)
+        
+        # Create formatter
+        formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+        handler.setFormatter(formatter)
+        
+        # Add handler to logger if not already added
+        if not logger.handlers:
+            logger.addHandler(handler)
+        
+        # Prevent propagation to root logger
+        logger.propagate = False
+    else:
+        # Set a higher log level to suppress lower-level logs
+        logger.setLevel(logging.WARNING)
+    
+    return logger

{papi_projects-0.1.3 → papi_projects-0.1.6}/papi/mocks.py

@@ -1,5 +1,7 @@
 import random
+import logging
 
+logger = logging.getLogger(__name__)
 
 def random_number(length):
     return "".join([str(random.randint(1, 9)) for i in range(length)])

{papi_projects-0.1.3 → papi_projects-0.1.6}/papi/project.py

@@ -4,11 +4,13 @@ import random
 import re
 import uuid
 import warnings
+import logging
 from typing import Protocol, runtime_checkable
 from papi.user import check_user_id
 
-THIS_YEAR = pendulum.now().year
+logger = logging.getLogger(__name__)
 
+THIS_YEAR = pendulum.now().year
 
 def check_project_id(id: str) -> bool:
     """Checks whether a project ID is correctly formed.
@@ -18,10 +20,14 @@ def check_project_id(id: str) -> bool:
     :return: True/False for whether project ID is correctly formed.
     :rtype: bool
     """
+    logger.debug("Calling check_project_id function")
     valid = False
-    pattern = re.compile(r"^P[0-9]{4}-[A-Z]{2}[A-Z0-9]{1}-[A-Z]{4}$")
+    pattern = re.compile(r"^P[0-9]{4}-[A-Z]{2}[A-Z1-9]{1}-[A-Z]{4}$")
     if pattern.match(id):
         valid = True
+        logger.info(f"Project ID '{id}' is valid")
+    else:
+        logger.info(f"Project ID '{id}' is not valid")
     return valid
 
 
@@ -33,10 +39,14 @@ def check_suffix(suffix: str) -> bool:
     :return: True/False for whether project suffix is correctly formed.
     :rtype: bool
     """
+    logger.debug("Calling check_suffix function")
     valid = False
     pattern = re.compile(r"^[A-Z]{4}$")
     if pattern.match(suffix):
         valid = True
+        logger.info(f"Project suffix '{suffix}' is valid")
+    else:
+        logger.info(f"Project suffix '{suffix}' is not valid")
     return valid
 
 
@@ -48,9 +58,12 @@ def check_uuid(p_uuid: str) -> bool:
     :return: True/False for whether the UUID is valid.
     :rtype: bool
     """
+    logger.debug("Calling check_uuid function")
     try:
         uuid_obj = uuid.UUID(p_uuid, version=4)
+        logger.info(f"Project UUID '{p_uuid}' is valid")
     except ValueError:
+        logger.error(f"Project UUID '{p_uuid}' is not valid")
         return False
     return str(uuid_obj) == p_uuid
 
@@ -94,6 +107,7 @@ class Project(Protocol):
         grant_code: str = None,
     ) -> None:
         """Constructor method"""
+        logger.debug("Creating Project instance")
         self.year = year
         self.user_id = user_id
         self.grant_code = grant_code
@@ -104,6 +118,9 @@ class Project(Protocol):
             self.generate_suffix()
         if id is not None and check_project_id(id):
             self.id = id
+            self.year = int(id[1:5])
+            self.user_id = id.split("-")[1]
+            self.suffix = id.split("-")[2]
         elif (
             isinstance(year, int)
             and check_user_id(user_id)
@@ -123,22 +140,16 @@ class Project(Protocol):
             )
         else:
             self.p_uuid = str(uuid.uuid4())
-
-    def __str__(self) -> str:
-        """Human-readable representation of class. Currently just the project ID.
-
-        :return: Project ID.
-        :rtype: str
-        """
-        return self.id
+        logger.info(f"Project '{self.id}' instance created")
 
     def __repr__(self) -> str:
-        """Machine-readable representation of class. Currently just the project ID.
+        """Machine-readable representation of class..
 
-        :return: Project ID.
+        :return: basic Project() attrs.
         :rtype: str
         """
-        return self.id
+        logger.debug("Calling Project.__repr__ method")
+        return f'Project("{self.id}", "{self.name}")'
 
     def generate_suffix(self) -> str:
         """Generates a 4-character, uppercase, alphabetical suffix for a project, and
@@ -147,6 +158,7 @@ class Project(Protocol):
         :return: Project suffix.
         :rtype: str
         """
+        logger.debug("Calling Project.generate_suffix method")
         letters = string.ascii_uppercase
         suffix = "".join(random.choice(letters) for i in range(4))
         self.suffix = suffix
@@ -158,4 +170,5 @@ class Project(Protocol):
         :return: True/False for whether the project ID is valid.
         :rtype: bool
         """
+        logger.debug("Calling Project.id_is_valid method")
         return check_project_id(self.id)

{papi_projects-0.1.3 → papi_projects-0.1.6}/papi/user.py

@@ -1,9 +1,11 @@
 import re
 import pendulum
+import logging
 from typing import Protocol, runtime_checkable
 from tinydb import TinyDB, Query
 from tinydb.operations import *
 
+logger = logging.getLogger(__name__)
 
 def user_name_to_user_id(user_name: str) -> str:
     """Generates a 3-character, uppercase, alphabetical user ID from a user name,
@@ -14,8 +16,10 @@ def user_name_to_user_id(user_name: str) -> str:
     :return: Three-character user ID.
     :rtype: str
     """
+    logger.debug("Calling user_name_to_user_id function")
     user_name_parts = user_name.split()
     user_id = "".join([word[0] for word in user_name_parts]).upper()
+    logger.info(f"User name '{user_name}' converted to user ID '{user_id}'")
     return user_id
 
 
@@ -28,8 +32,13 @@ def check_valid_email(email: str) -> bool:
     :return: True/False for whether the email is valid.
     :rtype: bool
     """
+    logger.debug("Calling check_valid_email function")
     valid_email = re.compile(r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$")
     valid = valid_email.match(email)
+    if valid:
+        logger.info(f"Email '{email}' is valid")
+    else:
+        logger.warning(f"Email '{email}' is not valid")
     return valid
 
 
@@ -43,13 +52,16 @@ def check_user_id(user_id: str) -> bool:
     :return: True/False for whether the user ID is valid.
     :rtype: bool
     """
+    logger.debug("Calling check_user_id function")
     if not isinstance(user_id, str):
+        logger.warning(f"User ID '{user_id}' is not valid")
         return False
     else:
         valid = False
         pattern = re.compile(r"^[A-Z]{2}[A-Z0-9]{1}$")
         if pattern.match(user_id):
             valid = True
+            logger.info(f"User ID '{user_id}' is valid")
         return valid
 
 
@@ -60,6 +72,8 @@ class User(Protocol):
 
     :param user_name: User name, e.g. John Smith.
     :type user_name: str
+    :param user_id: User ID, e.g. JS1.
+    :type user_id: str
     :param email: Email address, defaults to None.
     :type email: str, optional
     :raises ValueError: If the name does not consist of either 2 or 3 parts, then
@@ -68,10 +82,12 @@ class User(Protocol):
         ValueError is raised.
     """
 
-    def __init__(self, user_name: str, email: str = None):
+    def __init__(self, user_name: str = None, user_id: str = None, email: str = None):
         """Constructor method"""
-        if len(user_name.split()) == 1 or len(user_name.split()) > 3:
-            raise ValueError("Name must consist of two or three parts only")
+        logger.debug("Creating User instance")
+        if user_name is not None:
+            if len(user_name.split()) == 0 or len(user_name.split()) > 3:
+                raise ValueError("Name must consist of one to three parts only")
         self.user_name = user_name
         if email is not None:
             valid_email = check_valid_email(email)
@@ -80,8 +96,12 @@ class User(Protocol):
             self.email = email
         else:
             self.email = ""
-        self.user_id = user_name_to_user_id(user_name)
+        if user_id is None:
+            self.user_id = user_name_to_user_id(user_name)
+        else:
+            self.user_id = user_id
         self.created_at = str(pendulum.now())
+        logger.info(f"User '{self.user_id}' instance created")
 
     def to_json(self):
         """Returns a user in JSON (dictionary) form.
@@ -89,12 +109,22 @@ class User(Protocol):
         :return: JSON-formatted (i.e. dictionary) user.
         :rtype: dict
         """
+        logger.debug("Calling User.to_json method")
         return {
             "user_name": self.user_name,
             "user_id": self.user_id,
             "email": self.email,
             "created_at": self.created_at,
         }
+    
+    def __repr__(self):
+        """Machine-readable representation of class.
+
+        :return: basic User() attrs.
+        :rtype: str
+        """
+        logger.debug("Calling User.__repr__ method")
+        return f'User("{self.user_name}", "{self.user_id}", {self.email})'
 
 
 @runtime_checkable
@@ -110,6 +140,7 @@ class UserDB(Protocol):
 
     def __init__(self, db_file: str = None) -> None:
         """Constructor method"""
+        logger.debug("Creating UserDB instance")
         if db_file is not None:
             self.db = TinyDB(db_file, sort_keys=True, indent=4, separators=(",", ": "))
             self.db_file = db_file
@@ -118,6 +149,8 @@ class UserDB(Protocol):
             self.db = TinyDB(
                 self.db_file, sort_keys=True, indent=4, separators=(",", ": ")
             )
+        logger.info(f"UserDB '{self.db_file}' instance created")
+        
 
     def insert_user(self, user) -> User:
         """Inserts a user into the database, using a User instance.
@@ -128,6 +161,7 @@ class UserDB(Protocol):
         :return: ID of the inserted user.
         :rtype: int
         """
+        logger.debug("Calling UserDB.insert_user method")
         if len(user.user_name.split()) == 2:
             matches = self.check_matching_user_ids(user.user_id)
             if len(matches):
@@ -150,6 +184,7 @@ class UserDB(Protocol):
                 else:
                     user.user_id = f"{first_last_initial}1"
         self.db.insert(user.to_json())
+        logger.info(f"User ID '{useruser_id}' inserted into user database")
         return user.user_id
 
     def search_by_user_name(self, user_name: str) -> list:
@@ -161,8 +196,13 @@ class UserDB(Protocol):
         :return: A list of matching documents.
         :rtype: list
         """
+        logger.debug("Calling UserDB.search_by_user_name method")
         Users = Query()
         result = self.db.search(Users.user_name == user_name)
+        if len(result):
+            logger.info(f"{len(result)} matches for {user_name} found in user database")
+        else:
+            logger.info(f"No matches for {user_name} found in user database")
         return result
 
     def search_by_user_id(self, user_id: str) -> list:
@@ -174,8 +214,13 @@ class UserDB(Protocol):
         :return: A list of matching documents.
         :rtype: list
         """
+        logger.debug("Calling UserDB.search_by_user_id method")
         Users = Query()
         result = self.db.search(Users.user_id == user_id)
+        if len(result):
+            logger.info(f"{len(result)} matches for {user_id} found in user database")
+        else:
+            logger.info(f"No matches for {user_id} found in user database")
         return result
 
     def check_matching_user_ids(self, user_id: str) -> list:
@@ -189,6 +234,7 @@ class UserDB(Protocol):
         :return: A list of matching documents.
         :rtype: list
         """
+        logger.debug("Calling UserDB.check_matching_user_ids method")
         Users = Query()
         if user_id[-1].isnumeric() or len(user_id) == 2:
             result = self.db.search(Users.user_id.search(rf"^{user_id[0:2]}\d{{1}}"))