Implement masterdata and gender options Fixes #110

churchtools_api/churchtools_api.py

@@ -12,8 +12,16 @@
 
 logger = logging.getLogger(__name__)
 
-class ChurchToolsApi(ChurchToolsApiPersons, ChurchToolsApiEvents, ChurchToolsApiGroups,
-                     ChurchToolsApiSongs, ChurchToolsApiFiles, ChurchToolsApiCalendar, ChurchToolsApiResources):
+
+class ChurchToolsApi(
+    ChurchToolsApiPersons,
+    ChurchToolsApiEvents,
+    ChurchToolsApiGroups,
+    ChurchToolsApiSongs,
+    ChurchToolsApiFiles,
+    ChurchToolsApiCalendar,
+    ChurchToolsApiResources,
+):
     """Main class used to combine all api functions
 
     Args:
@@ -265,3 +273,32 @@ def get_tags(self, type='songs'):
         else:
             logger.warning(
                 "%s Something went wrong fetching Song-tags: %s",response.status_code, response.content)
+
+    def get_options(self) -> dict:
+        """Helper function which returns all configurable option fields from CT.
+        e.g. common use is sexId
+
+        Returns:
+            dict of options - named by "name" from original list response
+        """
+
+        url = self.domain + "/api/dbfields"
+        headers = {"accept": "application/json"}
+        params = {
+            "include[]": "options",
+        }
+        response = self.session.get(url=url, params=params, headers=headers)
+
+        if response.status_code == 200:
+            response_content = json.loads(response.content)
+            response_data = response_content["data"].copy()
+
+            logger.debug("SongTags load successful {}".format(response_content))
+            response_dict = {item["name"]: item for item in response_data}
+            return response_dict
+        else:
+            logger.warning(
+                "%s Something went wrong fetching Song-tags: %s",
+                response.status_code,
+                response.content,
+            )

churchtools_api/persons.py

@@ -5,6 +5,7 @@
 
 logger = logging.getLogger(__name__)
 
+
 class ChurchToolsApiPersons(ChurchToolsApiAbstract):
     """ Part definition of ChurchToolsApi which focuses on persons
 
@@ -15,23 +16,29 @@ class ChurchToolsApiPersons(ChurchToolsApiAbstract):
     def __init__(self):
         super()
 
-    def get_persons(self, **kwargs):
+    def get_persons(self, **kwargs) -> list[dict]:
         """
-        Function to get list of all or a person from CT
-        :param kwargs: optional keywords as listed
-        :keyword ids: list: of a ids filter
-        :keyword returnAsDict: bool: true if should return a dict instead of list
-        :return: list of user dicts
-        :rtype: list[dict]
+        Function to get list of all or a person from CT.
+
+        Arguments:
+            kwargs: optional keywords as listed
+
+        Kwargs:
+            ids: list: of a ids filter
+            returnAsDict: bool: true if should return a dict instead of list
+
+        Permissions:
+            some fields e.g. sexId require "security level person" with at least level 2 (administer persons is not sufficient)
+
+        Returns:
+            list of user dicts
         """
-        url = self.domain + '/api/persons'
-        params = {"limit":50} #increases default pagination size
-        if 'ids' in kwargs.keys():
-            params['ids[]'] = kwargs['ids']
-
-        headers = {
-            'accept': 'application/json'
-        }
+        url = self.domain + "/api/persons"
+        params = {"limit": 50}  # increases default pagination size
+        if "ids" in kwargs.keys():
+            params["ids[]"] = kwargs["ids"]
+
+        headers = {"accept": "application/json"}
         response = self.session.get(url=url, headers=headers, params=params)
 
         if response.status_code == 200:
@@ -50,7 +57,7 @@ def get_persons(self, **kwargs):
             )
             response_data = [response_data] if isinstance(response_data, dict) else response_data
 
-            if 'returnAsDict' in kwargs and not 'serviceId' in kwargs:
+            if 'returnAsDict' in kwargs and 'serviceId' not in kwargs:
                 if kwargs['returnAsDict']:
                     result = {}
                     for item in response_data:
@@ -64,3 +71,32 @@ def get_persons(self, **kwargs):
                 "Persons requested failed: {}".format(
                     response.status_code))
             return None
+
+    def get_persons_masterdata(
+        self, resultClass: str = None, returnAsDict: bool = False, **kwargs
+    ) -> dict[list[dict]]:
+        """
+        Function to get the Masterdata of the persons module
+        This information is required to map some IDs to specific items
+
+        Returns:
+            dict of lists of masterdata items each with list of dict items used as configuration
+        """
+        url = self.domain + "/api/person/masterdata"
+
+        headers = {"accept": "application/json"}
+        response = self.session.get(url=url, headers=headers)
+
+        if response.status_code == 200:
+            response_content = json.loads(response.content)
+            response_data = response_content["data"].copy()
+            logger.debug("Person Masterdata load successful {}".format(response_data))
+
+            return response_data
+        else:
+            logger.warning(
+                "%s Something went wrong fetching person metadata: %s",
+                response.status_code,
+                response.content,
+            )
+            return None