sharepoint-v1-api 0.2.2__py3-none-any.whl

sharepoint_api/SharePointList.py

@@ -0,0 +1,202 @@
+# from .SharePointAPI import SharePointAPI as SP
+from sharepoint_api.SharePointTimeRegistration import TimeRegistration
+from .SharePointListItem import SharePointListItem, SharepointSiteCase
+from typing import List
+import json
+
+
+class SharePointList:
+    """
+    Base class representing a SharePoint list.
+
+    Provides common functionality for handling list items, including
+    retrieval, addition, and serialization to JSON. Subclasses such as
+    :class:`CasesList` and :class:`TimeRegistrationList` extend this
+    class with domain‑specific behavior.
+    """
+
+    settings = None
+    _items = None
+    _fields = None
+    sharepoint_site = None
+    SPItem = SharePointListItem
+
+    CHANGE_DETECTED = False
+    SAVE_ON_CHANGE = False
+    JSON_FILENAME = None
+
+    def __init__(self, sp, sharepoint_site, settings: dict = None, items: List[SPItem] = None):
+        self.sp = sp
+        self.sharepoint_site = sharepoint_site
+        self.settings = settings
+        self.append_items(items)
+
+    def __str__(self):
+        items = ''
+        for _, _item in self.all_items.items():
+            items = items+str(_item.Title)+'\n'
+        return items
+
+    def __del__(self):
+        if self.CHANGE_DETECTED and self.SAVE_ON_CHANGE and self.JSON_FILENAME is not None:
+            print('Change was definiteley detected')
+            print('Saving items')
+            self.save_as_json(self.JSON_FILENAME)
+
+    @property
+    def all_items(self) -> dict[int, SPItem]:
+        '''
+            Get list of all SharePointListItem objects
+        '''
+        if self._items is None:
+            self._items = {}
+        return self._items
+
+    @property
+    def list_all_items(self) -> List[SPItem]:
+        '''
+            Get list of all SharePointListItem objects
+        '''
+        if self._items is None:
+            self._items = {}
+        return list(self._items.values())
+
+    @property
+    def Title(self) -> str:
+        return self.settings['Title']
+
+    @property
+    def guid(self):
+        return self.settings['Id']
+
+    def append_items(self, items):
+        """
+        Append a collection of items to the list.
+
+        Parameters
+        ----------
+        items : list or SharePointListItem
+            A list of :class:`SharePointListItem` instances or a single
+            instance to be added to the internal ``_items`` dictionary.
+        """
+        if self._items is None:
+            self._items = {}
+
+        if isinstance(items, list):
+            for item in items:
+                item._list = self
+                self._items[item.Id] = item
+
+        elif isinstance(items, self.SPItem):
+            items._list = self
+            self.all_items[items.Id] = items
+
+    def create_item(self, data):
+        self.sp.create_item(self.sharepoint_site, self, data)
+
+    def get_item_by_name(self, name):
+        """
+        Retrieve items from the list that match a given title.
+
+        Parameters
+        ----------
+        name : str
+            The title of the item to search for.
+
+        Returns
+        -------
+        dict[int, SharePointListItem]
+            A dictionary of matching items keyed by their IDs.
+        """
+        '''
+        '''
+        items = {}
+        for item_id, item in self._items.items():
+            if name == item.Title:
+                items[item_id] = item
+        return items
+
+    def get_item_by_id(self, id):
+        '''
+        '''
+        if id in self._items:
+            return self._items[id]
+        else:
+            return None
+
+    @property
+    def fields(self) -> dict:
+        """
+        Retrieve all fields from the SharePoint list.
+
+        Returns:
+            dict: Field definitions keyed by Title, cached for subsequent calls
+
+        Raises:
+            ConnectionError: If API request fails
+        """
+        if not self._fields:
+            try:
+                response = self.sp._api_get_call(
+                    f"{self.sp.sharepoint_url}/cases/{self.sharepoint_site}/_api/Web/Lists(guid'{self.guid}')/Fields"
+                )
+                response.raise_for_status()
+                self._fields = {field["Title"]: field for field in response.json().get(
+                    'd', {}).get('results', [])}
+            except Exception as e:
+                print(f"Failed to fetch fields: {str(e)}")
+                raise ConnectionError("Field retrieval failed") from e
+        return self._fields
+
+    def get_items_by_assigned_id(self, id) -> List[SPItem]:
+        '''
+        '''
+        items = {}
+        for item_id, item in self._items.items():
+            if id == item.ResponsibleId:
+                items[item_id] = item
+        return items
+
+    def save_as_json(self, file_name):
+        """
+        Serialize the list to a JSON file.
+
+        Parameters
+        ----------
+        file_name : str
+            Path to the output JSON file.
+
+        The resulting JSON contains the SharePoint site identifier, the list GUID,
+        settings, and all case items with their settings and version information.
+        """
+
+        out_dict = {
+            'sharepoint_site': self.sharepoint_site,
+            'GUID': self.guid,
+            'Settings': self.settings,
+            "cases": [{'settings': case.settings, 'versions': case._versions} for _, case in self.all_items.items()]
+        }
+
+        with open(file_name, 'w') as fp:
+            json.dump(out_dict, fp)
+
+
+class CasesList(SharePointList):
+    """
+    Specialized list representing a collection of case items.
+
+    Inherits all functionality from :class:`SharePointList` and sets the
+    ``SPItem`` attribute to :class:`SharepointSiteCase` for proper item
+    instantiation.
+    """
+    SPItem = SharepointSiteCase
+
+
+class TimeRegistrationList(SharePointList):
+    """
+    Specialized list for time‑registration entries.
+
+    Inherits from :class:`SharePointList` and sets ``SPItem`` to the
+    :class:`TimeRegistration` class.
+    """
+    SPItem = TimeRegistration

sharepoint_api/SharePointListItem.py

@@ -0,0 +1,196 @@
+from datetime import datetime
+# from .SharePointAPI import SharePointAPI as SP
+
+class SharePointListItem:
+    """
+    Represents a generic item in a SharePoint list.
+
+    Provides access to common fields such as ``Id``, ``Title``, ``Created`` and
+    ``Modified`` and handles lazy loading of related list data and version
+    history. Sub‑classes (e.g. :class:`SharepointSiteCase` or
+    :class:`TimeRegistration`) extend this base with domain‑specific properties.
+    """
+    ''' 
+    '''
+    settings = {}
+
+    def __init__(self, sp, sharepoint_site, list_guid, settings: dict = None, versions: list = None):
+        self.sp = sp
+        self.sharepoint_site = sharepoint_site
+        self.list_guid = list_guid
+        self._list = None
+        self._versions = versions
+        self.settings = settings
+
+    def __str__(self):
+        return self.Title
+
+    @property
+    def list(self):
+        if not self._list:
+            self._list = self.sp.get_list(self.sharepoint_site, self.list_guid)
+        return self._list
+
+    @property
+    def versions(self) -> list:
+        if not self._versions:
+            self._versions = self.sp.get_item_versions(self.sharepoint_site, self.list_guid, self.Id) 
+            if self._list is not None:
+                self._list.CHANGE_DETECTED = True
+        return self._versions    
+    
+    
+    @property
+    def Id(self) -> str:
+        """Unique identifier of the list item."""
+        return self.settings['Id']
+
+    @property
+    def Title(self) -> str:
+        """Title of the list item."""
+        return self.settings['Title']
+
+    @property
+    def Created(self) -> datetime:
+        """
+        Timestamp of when the item was created.
+
+        Returns ``None`` if the ``Created`` field is missing or null.
+        """
+        if 'Created' not in self.settings:
+            return None
+        elif self.settings['Created'] is None:
+            return None
+        else:
+            return datetime.strptime(self.settings['Created'], '%Y-%m-%dT%H:%M:%SZ')
+
+    @property
+    def Modified(self) -> datetime:
+        """
+        Timestamp of when the item was modified.
+
+        Returns ``None`` if the ``Modified`` field is missing or null.
+        """
+        if 'Modified' not in self.settings:
+            return None
+        elif self.settings['Modified'] is None:
+            return None
+        else:
+            return datetime.strptime(self.settings['Modified'], '%Y-%m-%dT%H:%M:%SZ')
+
+    def attach_item(self, file_name, file_path):
+        """
+        Attach a file to this list item.
+    
+        Parameters
+        ----------
+        file_name : str
+            The name of the file as it should appear in SharePoint.
+        file_path : str
+            Local path to the file to be uploaded.
+    
+        The method reads the file content and uses :meth:`SharePointAPI.attach_file`
+        to upload it to the corresponding SharePoint list item.
+        """
+        with open(file_path, 'r') as f:
+            file_content = f.read()
+
+    
+        self.sp.attach_file(self.sharepoint_site, self.list, self, file_name, file_content)
+
+    def versions_select_fields(self, select_fields=[]) -> list:
+        if not self._versions:
+            self._versions = self.sp.get_item_versions(self.sharepoint_site, self.list_guid, self.Id, select_fields) 
+        return self._versions
+
+    def update_fields(self, data):
+        self.sp.update_item(self.sharepoint_site,
+                            self.list_guid, self.Id, data)
+
+class SharepointSiteCase(SharePointListItem):
+    
+    @property
+    def AssignmentType(self) -> str:
+        return self.settings['AssignmentType']
+
+    @property
+    def CaseClosedTimestamp(self) -> datetime:
+        'Timestamp of when the case was closed'
+        if 'CaseClosed' not in self.settings:
+            return None
+        elif self.settings['CaseClosed'] is None:
+            return None
+        else:
+            return datetime.strptime(self.settings['CaseClosed'], '%Y-%m-%dT%H:%M:%SZ')
+
+    @property
+    def Due(self) -> datetime:
+        'Timestamp of when the case is due'
+        if 'DueDate' not in self.settings:
+            return None
+        elif self.settings['DueDate'] is None:
+            return None
+        else:
+            return datetime.strptime(self.settings['DueDate'], '%Y-%m-%dT%H:%M:%SZ')
+
+    @property
+    def Priority(self) -> str:
+        return self.settings['Priority']
+
+    @property
+    def ResponsibleId(self) -> str:
+        return self.settings['AssignedToId']
+
+    @property
+    def Status(self) -> str:
+        return self.settings['Status']
+
+    @property
+    def SolvedInTime(self) -> bool:
+        'Bool indicating whether work was solved in time'
+        solved_in_time = False
+        if self.Due:
+            if not self.CaseClosedTimestamp:
+                solved_in_time = True
+            elif self.CaseClosedTimestamp <= self.Due:
+                solved_in_time = True
+        else:
+            solved_in_time = True
+        
+        return solved_in_time
+
+    @property
+    def WorkBegunTimestamp(self) -> datetime:
+        'Timestamp of when work was started on the case'
+        if 'WorkBegun' not in self.settings:
+            return None
+        elif self.settings['WorkBegun'] is None:
+            return None
+        else:
+            return datetime.strptime(self.settings['WorkBegun'], '%Y-%m-%dT%H:%M:%SZ')
+
+    @property
+    def DeadlineWorkTimestamp(self) -> datetime:
+        'Timestamp of when work should start on the case'
+        if 'DeadlineWork' not in self.settings:
+            return None
+        elif self.settings['DeadlineWork'] is None:
+            return None
+        else:
+            return datetime.strptime(self.settings['DeadlineWork'], '%Y-%m-%dT%H:%M:%SZ')
+
+    @property
+    def ReactedInTime(self) -> bool:
+        'Bool indicating whether work was started in time'
+        reacted_in_time = False
+        if self.DeadlineWorkTimestamp:
+            if not self.WorkBegunTimestamp:
+                reacted_in_time = True
+            elif self.WorkBegunTimestamp <= self.DeadlineWorkTimestamp:
+                reacted_in_time = True
+        else:
+            reacted_in_time = True
+        return reacted_in_time
+
+    
+        

sharepoint_api/SharePointLists.py

@@ -0,0 +1,59 @@
+from .SharePointList import SharePointList, CasesList
+from typing import List
+
+class SharePointLists:
+
+    _lists = None
+
+    def __init__(self, lists):
+        self._lists = lists
+
+    def __str__(self):
+        lists = ''
+        for _list in self.all_lists:
+            lists = lists+str(_list.Title)+'\n'
+        return lists
+
+    @property
+    def all_lists(self) -> List[SharePointList]:
+        '''
+            Get list of all SharePointList objects
+        '''
+        if self._lists is None:
+            self._lists = []
+        return self._lists
+
+    @property
+    def all_list_titles(self) -> str:
+        '''
+            Get list of all SharePointList objects
+        '''
+        
+        return [_list.Title for _list in self.all_lists]
+
+
+    def get_list(self, key, SPListType: SharePointList=SharePointList) -> SharePointList:
+        '''
+            Get SharePointList by:
+                - Index: int
+                - List title: str
+        '''
+        if isinstance(key, int):
+            return self.all_lists[key]
+        elif isinstance(key, str):
+            for list_object in self.all_lists:
+                if list_object.Title == key:
+                    return list_object
+            raise KeyError("No list with title '{0}'".format(key))
+        raise KeyError
+
+    def get_cases_list(self, key) -> CasesList:
+        '''
+            Get SharePointList by:
+                - Index: int
+                - List title: str
+        '''
+
+        list_object = self.get_list(key, SPListType=CasesList)
+
+        return CasesList(list_object.sharepoint_site, list_object.settings)

sharepoint_api/SharePointTimeRegistration.py

@@ -0,0 +1,53 @@
+from datetime import datetime
+
+from sharepoint_api.SharePointListItem import SharePointListItem
+# from .SharePointAPI import SharePointAPI as SP
+
+class TimeRegistration(SharePointListItem):
+    """
+    Represents a time‑registration entry associated with a SharePoint list item.
+
+    Extends :class:`SharePointListItem` with fields specific to time tracking,
+    such as ``Hours``, ``DoneBy`` and related timestamps. Provides lazy loading of the
+    ``DoneBy`` user via the :meth:`SharePointAPI.get_users` call.
+    """
+
+    _DoneBy = None
+
+    @property
+    def Created(self) -> datetime:
+        'Timestamp of when the item was created'
+        if 'DoneDate' not in self.settings:
+            return None
+        elif self.settings['DoneDate'] is None:
+            return None
+        else:
+            return datetime.strptime(self.settings['DoneDate'], '%Y-%m-%dT%H:%M:%SZ')
+    
+    @property
+    def Hours(self) -> str:
+        return self.settings['Hours']
+
+    @property
+    def DoneById(self) -> str:
+        return self.settings['DoneById']
+
+    @property
+    def DoneBy(self) -> str:
+        if not self._DoneBy:
+            user_list = self.sp.get_users(self.sharepoint_site)
+            self._DoneBy = user_list.get_user_by_id(self.DoneById)
+        return self._DoneBy
+    
+    @property
+    def DoneUsername(self) -> str:
+        return self.DoneBy.UserName
+
+    @property
+    def CaseId(self) -> str:
+        return self.settings['CaseId']
+    
+    @property
+    def WorkPackageId(self) -> str:
+        return self.settings['WorkPackageId']
+    

sharepoint_api/SharePointUser.py

@@ -0,0 +1,33 @@
+class SharePointUser:
+
+    settings = None
+    _users = None
+    sharepoint_site = None
+
+    def __init__(self, settings: dict = None):
+        self.settings = settings
+
+    @property
+    def Id(self):
+        if self.settings is None:
+            return None
+        return self.settings['Id']
+
+    @property
+    def Title(self):
+        if self.settings is None:
+            return None
+        return self.settings['Title']
+
+    @property
+    def UserName(self):
+        if self.settings is None:
+            return None
+        return self.settings['Email'].split('@')[0].lower()
+
+    @property
+    def Email(self):
+        if self.settings is None:
+            return None
+        return self.settings['Email']    
+

sharepoint_api/SharePointUserList.py

@@ -0,0 +1,36 @@
+class SharePointUserList:
+    """
+    Container for SharePoint user objects.
+
+    Holds a list of :class:`SharePointUser` instances retrieved from a
+    SharePoint site and provides helper methods to look up users by
+    username or ID. The ``sharepoint_site`` attribute records the site
+    from which the users were fetched.
+    """
+
+    _users = []
+    sharepoint_site = ''
+
+    def __init__(self, sharepoint_site, users):
+        self._users = users
+        self.sharepoint_site = sharepoint_site
+
+    def __str__(self):
+        n_users = len(self._users)
+        if n_users == 1:
+            return 'A list of 1 user'
+
+        return f'A list of {n_users} users'
+    
+    def get_user_by_username(self, name):
+        for user in self._users:
+            if name == user.UserName:
+                return user
+        return
+
+    def get_user_by_id(self, user_id):
+        for user in self._users:
+            if user_id == user.Id:
+                return user
+        return
+

sharepoint_api/__init__.py

@@ -0,0 +1,21 @@
+"""sharepoint_api package
+
+Provides a high‑level Python client for interacting with SharePoint sites via the
+`SharePointAPI` class. The package includes helpers for working with lists,
+list items, users, and time registrations.
+
+Typical usage:
+
+```python
+from sharepoint_api import SharePointAPI
+
+creds = {
+    "username": "my_user",
+    "password": "my_pass",
+    "sharepoint_url": "https://my.sharepoint.com"
+}
+api = SharePointAPI._compact_init(creds)
+```
+"""
+
+from .SharePointAPI import SharePointAPI