From 8cd66cb34ba7d37445dd093431021922daeb7091 Mon Sep 17 00:00:00 2001 From: bensteUEM Date: Fri, 4 Oct 2024 19:45:17 +0200 Subject: [PATCH] updated documentation and logging of get_bookings - Fixes #107 --- churchtools_api/resources.py | 29 +++++++++---------- tests/test_churchtools_api_resources.py | 38 ++++++++++++++++++------- 2 files changed, 42 insertions(+), 25 deletions(-) diff --git a/churchtools_api/resources.py b/churchtools_api/resources.py index 36a5f3e..5c859ca 100644 --- a/churchtools_api/resources.py +++ b/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,11 +82,9 @@ 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") @@ -93,8 +92,8 @@ def get_bookings(self, **kwargs) -> list[dict]: 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 diff --git a/tests/test_churchtools_api_resources.py b/tests/test_churchtools_api_resources.py index 9864667..411ceb5 100644 --- a/tests/test_churchtools_api_resources.py +++ b/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"""