updated documentation and logging of get_bookings - Fixes #107

churchtools_api/resources.py

@@ -5,6 +5,7 @@
 
 logger = logging.getLogger(__name__)
 
+
 class ChurchToolsApiResources(ChurchToolsApiAbstract):
     """Part definition of ChurchToolsApi which focuses on resources.
 
@@ -48,22 +49,22 @@ def get_resource_masterdata(self, result_type: str) -> dict:
             return
 
     def get_bookings(self, **kwargs) -> list[dict]:
-        """_summary_
+        """Access to all Resource bookings in churchtools based on a combination of Keyword Arguments.
 
         Arguments:
             kwargs - see list below - some combination limits do apply
 
         KwArgs:
-            booking_id: only one booking by id (use standalone only)
-            resources_ids:list[int] - required if not booking_id
-            status_ids: filter by list of stats ids to consider (requires resource_ids)
-            _from: date range to consider (use only with _to! - might have a bug in API - Support Ticket 130123)
-            _to: date range to consider (use only with _from! - might have a bug in API - Support Ticket 130123)
-            appointment_id: get resources for one specific calendar_appointment only (use together with _to and _from for performance reasons)
+            booking_id: int: only one booking by id (use standalone only)
+            resources_ids:list[int]: required if not booking_id
+            status_ids: list[int]: filter by list of stats ids to consider (requires resource_ids)
+            _from: datetime: date range to consider (use only with _to! - might have a bug in API - Support Ticket 130123)
+            _to: datetime: date range to consider (use only with _from! - might have a bug in API - Support Ticket 130123)
+            appointment_id: int: get resources for one specific calendar_appointment only (use together with _to and _from for performance reasons)
         """
         url = self.domain + "/api/bookings"
         headers = {"accept": "application/json"}
-        params = {"limit":50} #increases default pagination size
+        params = {"limit": 50}  # increases default pagination size
 
         # at least one of the following arguments is required
         required_kwargs = ["booking_id", "resource_ids"]
@@ -81,20 +82,18 @@ def get_bookings(self, **kwargs) -> list[dict]:
             if status_ids := kwargs.get("status_ids"):
                 params["status_ids[]"] = status_ids
             if "_from" in kwargs or "_to" in kwargs:
-                if ("_from" in kwargs and "_to" not in kwargs) or (
-                    "_from" not in kwargs and "_to" in kwargs
-                ):
-                    logger.warning(
-                        "See ChurchTools support ticket 130123 - might have unexpected behaviour if to and from are used standalone"
+                if "_from" not in kwargs or "_to" not in kwargs:
+                    logger.info(
+                        "missing _from or _to defaults to first or last day of current month"
                     )
                 if _from := kwargs.get("_from"):
                     params["from"] = _from.strftime("%Y-%m-%d")
                 if _to := kwargs.get("_to"):
                     params["to"] = _to.strftime("%Y-%m-%d")
             if appointment_id := kwargs.get("appointment_id"):
                 if "from" not in params:
-                    logger.info(
-                        "Performance and stability issues - use appointment_id param together with to and from for faster results and definite time range"
+                    logger.warning(
+                        "using appointment ID without date range might be incomplete if current month differs"
                     )
                 params["appointment_id"] = appointment_id
 

tests/test_churchtools_api_resources.py

@@ -15,6 +15,7 @@
         log_directory.mkdir(parents=True)
     logging.config.dictConfig(config=logging_config)
 
+
 class Test_churchtools_api_resources(TestsChurchToolsApiAbstract):
     def test_get_resource_masterdata_resourceTypes(self):
         """Check resourceTypes can be retrieved.
@@ -113,6 +114,7 @@ def test_get_booking_from_to_date_without_resource_id(self, caplog):
     def test_get_booking_from_date(self, caplog):
         """IMPORTANT - This test method and the parameters used depend on the target system!
         the hard coded sample exists on ELKW1610.KRZ.TOOLS"""
+        caplog.set_level(logging.INFO)
         RESOURCE_ID_SAMPLES = [8, 20]
         SAMPLE_DATES = {
             "_from": datetime(year=2024, month=9, day=21),
@@ -132,16 +134,18 @@ def test_get_booking_from_date(self, caplog):
             [SAMPLE_DATES["_from"] <= compare_date for compare_date in result_dates]
         )
 
-        expected_response = "See ChurchTools support ticket 130123 - might have unexpected behaviour if to and from are used standalone"
+        expected_response = (
+            "missing _from or _to defaults to first or last day of current month"
+        )
         assert expected_response in caplog.messages
 
     def test_get_booking_to_date(self, caplog):
         """IMPORTANT - This test method and the parameters used depend on the target system!
         the hard coded sample exists on ELKW1610.KRZ.TOOLS"""
+        caplog.set_level(logging.INFO)
         RESOURCE_ID_SAMPLES = [8, 20]
         SAMPLE_DATES = {
-            "_from": datetime(year=2024, month=9, day=21),
-            "_to": datetime(year=2024, month=9, day=30),
+            "_to": datetime.now() + timedelta(days=30),
         }
 
         result = self.api.get_bookings(
@@ -157,7 +161,9 @@ def test_get_booking_to_date(self, caplog):
             [SAMPLE_DATES["_to"] >= compare_date for compare_date in result_dates]
         )
 
-        expected_response = "See ChurchTools support ticket 130123 - might have unexpected behaviour if to and from are used standalone"
+        expected_response = (
+            "missing _from or _to defaults to first or last day of current month"
+        )
         assert expected_response in caplog.messages
 
     def test_get_booking_from_to_date(self, caplog):
@@ -194,19 +200,31 @@ def test_get_booking_from_to_date(self, caplog):
     def test_get_booking_appointment_id(self, caplog):
         """IMPORTANT - This test method and the parameters used depend on the target system!
         the hard coded sample exists on ELKW1610.KRZ.TOOLS"""
-        caplog.set_level(logging.INFO)
+        caplog.set_level(logging.WARNING)
 
         RESOURCE_ID_SAMPLES = [16]
-        SAMPLE_APPOINTMENT_ID = 327883  # 22.9 GH
+        SAMPLE_DATES = {
+            "_from": datetime(year=2024, month=9, day=21),
+            "_to": datetime(year=2024, month=9, day=30),
+        }
+        SAMPLE_APPOINTMENT_ID = 327883  # 22.9.2024 GH
         result = self.api.get_bookings(
-            appointment_id=SAMPLE_APPOINTMENT_ID, resource_ids=RESOURCE_ID_SAMPLES
+            appointment_id=SAMPLE_APPOINTMENT_ID,
+            resource_ids=RESOURCE_ID_SAMPLES,
+            _from=SAMPLE_DATES["_from"],
+            _to=SAMPLE_DATES["_to"],
         )
-        expected_log_message = "Performance and stability issues - use appointment_id param together with to and from for faster results and definite time range"
-        assert expected_log_message in caplog.messages
-        assert len(result) == 1
+
         assert result[0]["base"]["caption"] == "Zentral-Gottesdienst im Gemeindehaus"
         assert result[0]["base"]["resource"]["id"] in set(RESOURCE_ID_SAMPLES)
 
+        result = self.api.get_bookings(
+            appointment_id=SAMPLE_APPOINTMENT_ID, resource_ids=RESOURCE_ID_SAMPLES
+        )
+        expected_log_message = "using appointment ID without date range might be incomplete if current month differs"
+        assert expected_log_message in caplog.messages
+        assert len(result) == 0
+
     def test_get_booking_appointment_id_daterange(self):
         """IMPORTANT - This test method and the parameters used depend on the target system!
         the hard coded sample exists on ELKW1610.KRZ.TOOLS"""