Skip to content

Endpoints adapters (Domains)

Endpoints are grouped under tags which represent a domain exposed by the API.

Calendar API exposes 3 domains:

  • Holidays: Holidays related operations
  • Bdays: Business Days related operations
  • Tagged Calendar: Both of them merged, every day tagged with its kind. This is the whole calendar

In the client side, the domains are represented as Resource adapters

BaseMixin

BaseMixin(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Mixin Base class for resource-interaction with Calendar API.

Attributes:

  • resource_name (str) –

    Resource canonical name

  • model_type (ModelT) –

    Default model class of an endpoint

  • endpoints (dict) –

    A mapping of operation keys and endpoint URLS. Each operation has a unique key in the dict

Methods:

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • json_from_response_or_raise –

    Extract the json payload from the Response.

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload

HolidaysResource

HolidaysResource(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Methods:

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • is_holiday –

    Verify if the provided date is a Holiday. If True, also returns the description of that Holiday and its type.

  • json_from_response_or_raise –

    Extract the json payload from the Response.

  • year –

    Get the holidays of a year

  • years –

    Get the holidays of many years

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

is_holiday

is_holiday(date: date) -> HolidayCheckResult

Verify if the provided date is a Holiday. If True, also returns the description of that Holiday and its type.

Parameters:

Returns:

Source code in pycalendar_api/domains/holidays.py
65
66
67
68
69
70
71
72
73
74
def is_holiday(self, date: datetime.date) -> HolidayCheckResult:
    """Verify if the provided date is a Holiday. If True, also returns the description of that Holiday and its type.

    Args:
        date (datetime.date): A date

    Returns:
        HolidayCheckResult: Result of the verification
    """
    return self._fetch(self._is_holiday_call(date))

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload

year

Get the holidays of a year

Parameters:

  • year

    (int) –

    the Year

  • holiday_type

    (`CalHolidayType`, default: None ) –

    Optional filter on holiday type. See CalHolidayType

Returns:

  • list[Holiday] –

    list[Holiday]: Ordered list of holidays of one year

Source code in pycalendar_api/domains/holidays.py
41
42
43
44
45
46
47
48
49
50
51
def year(self, year: int, *, holiday_type: CalHolidayType=None) -> list[Holiday]:
    """Get the holidays of a year

    Args:
        year (int): the Year
        holiday_type (`CalHolidayType`): Optional filter on holiday type. See `CalHolidayType`

    Returns:
        list[Holiday]: Ordered list of holidays of one year
    """
    return self._fetch(self._year_call(year, holiday_type=holiday_type))

years

Get the holidays of many years

Parameters:

  • years

    (Iterable[int]) –

    Iterable of years as int

  • holiday_type

    (`CalHolidayType`, default: None ) –

    Optional filter on holiday type. See CalHolidayType

Returns:

  • list[Holiday] –

    list[Holiday]: Ordered list of holidays spanning many years

Source code in pycalendar_api/domains/holidays.py
53
54
55
56
57
58
59
60
61
62
63
def years(self, years: Iterable[int], *, holiday_type: CalHolidayType=None) -> list[Holiday]:
    """Get the holidays of many years

    Args:
        years (Iterable[int]): Iterable of years as int
        holiday_type (`CalHolidayType`): Optional filter on holiday type. See `CalHolidayType`

    Returns:
        list[Holiday]: Ordered list of holidays spanning many years
    """
    return self._fetch(self._years_call(years, holiday_type=holiday_type))

BDaysResource

BDaysResource(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Methods:

  • bdays_of –

    Get the Business days of a year.

  • between –

    Get the Business days between 2 dates

  • count –

    Count the business days (inclusive) between 2 dates

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • json_from_response_or_raise –

    Extract the json payload from the Response.

  • next_date –

    Returns the next Business day following the provided date

  • previous_date –

    Returns the previous Business day before the provided date

  • span –

    Get the Start/End dates of periods (Quarters, Semesters, Months) in the form of ]Start, End] (Open-Close Interval).

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

bdays_of

bdays_of(year: int, month: int = None) -> DateSeries

Get the Business days of a year.

Parameters:

  • year

    (int) –

    the year

  • month

    (int, default: None ) –

    If provided returns the business days of that month

Returns:

  • DateSeries ( DateSeries ) –

    Ordered Set of dates. The collection is under DateSeries.serie

Source code in pycalendar_api/domains/bdays.py
81
82
83
84
85
86
87
88
89
90
91
def bdays_of(self, year: int, month: int=None) -> DateSeries:
    """Get the Business days of a year.

    Args:
        year (int): the year
        month (int, optional): If provided returns the business days of that month

    Returns:
        DateSeries: Ordered Set of dates. The collection is under `DateSeries.serie`
    """
    return self._fetch(self._bdays_of_call(year, month))

between

between(start: date, end: date) -> DateSeries

Get the Business days between 2 dates

Parameters:

Returns:

  • DateSeries ( DateSeries ) –

    Ordered Set of dates. The collection is under DateSeries.serie

Source code in pycalendar_api/domains/bdays.py
69
70
71
72
73
74
75
76
77
78
79
def between(self, start: datetime.date, end: datetime.date) -> DateSeries:
    """Get the Business days between 2 dates

    Args:
        start (datetime.date): Start date
        end (datetime.date): End date

    Returns:
        DateSeries: Ordered Set of dates. The collection is under `DateSeries.serie`
    """
    return self._fetch(self._between_call(start, end))

count

count(start: date, end: date) -> DaysCount

Count the business days (inclusive) between 2 dates

Parameters:

Returns:

  • DaysCount ( DaysCount ) –

    Days count datastruct

Source code in pycalendar_api/domains/bdays.py
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def count(self, start: datetime.date, end: datetime.date) -> DaysCount:
    """Count the business days (inclusive) between 2 dates

    Args:
        start (datetime.date): Start date
        end (datetime.date): End date

    Returns:
        DaysCount: Days count datastruct
    """
    return self._fetch(self._count_call(start, end))

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload

next_date

next_date(date: date) -> NextDate

Returns the next Business day following the provided date

Parameters:

Returns:

  • NextDate ( NextDate ) –

    Contains the requested date and the next open date

Source code in pycalendar_api/domains/bdays.py
105
106
107
108
109
110
111
112
113
114
def next_date(self, date: datetime.date) -> NextDate:
    """Returns the `next` Business day following the provided date

    Args:
        date (datetime.date): A date

    Returns:
        NextDate: Contains the requested date and the next open date
    """
    return self._fetch(self._next_date_call(date))

previous_date

previous_date(date: date) -> PreviousDate

Returns the previous Business day before the provided date

Parameters:

Returns:

  • PreviousDate ( PreviousDate ) –

    Contains the requested date and the previous open date

Source code in pycalendar_api/domains/bdays.py
116
117
118
119
120
121
122
123
124
125
def previous_date(self, date: datetime.date) -> PreviousDate:
    """Returns the `previous` Business day before the provided date

    Args:
        date (datetime.date): A date

    Returns:
        PreviousDate: Contains the requested date and the previous open date
    """
    return self._fetch(self._previous_date_call(date))

span

span(year: int, *, month: int = None, quarter: int = None, semester: int = None) -> CalSpan

Get the Start/End dates of periods (Quarters, Semesters, Months) in the form of ]Start, End] (Open-Close Interval).

  • Start: The last Open Business day of the previous period

  • End: The last Open Business day of the period

Parameters:

  • year

    (int) –

    Span of a year

  • month

    (int, default: None ) –

    Span of a month, 1 <= month <= 12

  • quarter

    (int, default: None ) –

    Span of a quarter, 1 <= quarter <= 4

  • semester

    (int, default: None ) –

    Span of a semester, 1 <= semester <= 2

Returns:

  • CalSpan ( CalSpan ) –

    Span interval of the requested period

Raises:

Source code in pycalendar_api/domains/bdays.py
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def span(self, year: int, *, month: int=None, quarter: int=None, semester: int=None) -> CalSpan:
    """Get the Start/End dates of periods (Quarters, Semesters, Months) in the form of ]`Start`, `End`] (Open-Close Interval).

    - `Start`: The last Open Business day of the previous period

    - `End`: The last Open Business day of the period

    Args:
        year (int): Span of a year
        month (int, optional): Span of a month, 1 <= month <= 12
        quarter (int, optional): Span of a quarter, 1 <= quarter <= 4
        semester (int, optional): Span of a semester, 1 <= semester <= 2

    Returns:
        CalSpan: Span interval of the requested period

    Raises:
        CalendarAPIParamError: Only one of the periods must be provided.
    """
    return self._fetch(self._span_call(year, month=month, quarter=quarter, semester=semester))

TaggedCalendarResource

TaggedCalendarResource(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Methods:

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • json_from_response_or_raise –

    Extract the json payload from the Response.

  • month –

    Get one month of the tagged calendar laid out in ISO weeks (Monday → Sunday), with the days counts by kind.

  • year –

    Get the full calendar of a year, month by month, where every day is tagged

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload

month

month(year: int, month: int) -> TaggedMonth

Get one month of the tagged calendar laid out in ISO weeks (Monday → Sunday), with the days counts by kind.

Parameters:

  • year

    (int) –

    the Year (2000 → 2040)

  • month

    (int) –

    the Month (1 → 12)

Returns:

  • TaggedMonth ( TaggedMonth ) –

    The weeks of the month and the days counts by kind

Source code in pycalendar_api/domains/tagged.py
37
38
39
40
41
42
43
44
45
46
47
def month(self, year: int, month: int) -> TaggedMonth:
    """Get one month of the tagged calendar laid out in ISO weeks (Monday → Sunday), with the days counts by kind.

    Args:
        year (int): the Year (2000 → 2040)
        month (int): the Month (1 → 12)

    Returns:
        TaggedMonth: The weeks of the month and the days counts by kind
    """
    return self._fetch(self._month_call(year, month))

year

year(year: int) -> TaggedYear

Get the full calendar of a year, month by month, where every day is tagged BUSINESS, WEEKEND or HOLIDAY (with its type, status and description).

Parameters:

  • year

    (int) –

    the Year (2000 → 2040)

Returns:

  • TaggedYear ( TaggedYear ) –

    The months of the year and the days counts by kind

Source code in pycalendar_api/domains/tagged.py
25
26
27
28
29
30
31
32
33
34
35
def year(self, year: int) -> TaggedYear:
    """Get the full calendar of a year, month by month, where every day is tagged
    `BUSINESS`, `WEEKEND` or `HOLIDAY` (with its type, status and description).

    Args:
        year (int): the Year (2000 → 2040)

    Returns:
        TaggedYear: The months of the year and the days counts by kind
    """
    return self._fetch(self._year_call(year))

HealthsResource

HealthsResource(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Methods:

  • api –

    Check the health of the API. Serves as a heartbeat for integrations.

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • json_from_response_or_raise –

    Extract the json payload from the Response.

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

api

api() -> ApiHealth

Check the health of the API. Serves as a heartbeat for integrations.

Returns:

  • ApiHealth ( ApiHealth ) –

    Health Status of the API

Source code in pycalendar_api/domains/health.py
21
22
23
24
25
26
27
def api(self) -> ApiHealth:
    """Check the health of the API. Serves as a heartbeat for integrations.

    Returns:
        ApiHealth: Health Status of the API
    """
    return self._fetch(self._api_call())

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload

Async resources

AsyncCalendarApi uses the async counterparts of the resources above. They share the same requests (ApiCall) and the same models.

ApiCall dataclass

ApiCall(url: str, params: dict = dict(), model_type: ModelT = None, many: bool = False)

Description of a GET request to the API and how to deserialize its response.

Built once by the resource operations and executed by either the sync or the async client.

Attributes:

  • url (str) –

    Endpoint URL, relative to the client base_url or absolute

  • params (dict) –

    Query parameters

  • model_type (ModelT) –

    Model class used for deserialization

  • many (bool) –

    The response is a list of model_type

AsyncHolidaysResource

AsyncHolidaysResource(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Async version of HolidaysResource. Same operations, to be awaited.

Methods:

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • is_holiday –

    Verify if the provided date is a Holiday. See HolidaysResource.is_holiday

  • json_from_response_or_raise –

    Extract the json payload from the Response.

  • year –

    Get the holidays of a year. See HolidaysResource.year

  • years –

    Get the holidays of many years. See HolidaysResource.years

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

is_holiday async

is_holiday(date: date) -> HolidayCheckResult

Verify if the provided date is a Holiday. See HolidaysResource.is_holiday

Source code in pycalendar_api/domains/holidays.py
88
89
90
async def is_holiday(self, date: datetime.date) -> HolidayCheckResult:
    """Verify if the provided date is a Holiday. See `HolidaysResource.is_holiday`"""
    return await self._fetch(self._is_holiday_call(date))

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload

year async

year(year: int, *, holiday_type: CalHolidayType = None) -> list[Holiday]

Get the holidays of a year. See HolidaysResource.year

Source code in pycalendar_api/domains/holidays.py
80
81
82
async def year(self, year: int, *, holiday_type: CalHolidayType=None) -> list[Holiday]:
    """Get the holidays of a year. See `HolidaysResource.year`"""
    return await self._fetch(self._year_call(year, holiday_type=holiday_type))

years async

years(years: Iterable[int], *, holiday_type: CalHolidayType = None) -> list[Holiday]

Get the holidays of many years. See HolidaysResource.years

Source code in pycalendar_api/domains/holidays.py
84
85
86
async def years(self, years: Iterable[int], *, holiday_type: CalHolidayType=None) -> list[Holiday]:
    """Get the holidays of many years. See `HolidaysResource.years`"""
    return await self._fetch(self._years_call(years, holiday_type=holiday_type))

AsyncBDaysResource

AsyncBDaysResource(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Async version of BDaysResource. Same operations, to be awaited.

Methods:

  • bdays_of –

    Get the Business days of a year or a month. See BDaysResource.bdays_of

  • between –

    Get the Business days between 2 dates. See BDaysResource.between

  • count –

    Count the business days (inclusive) between 2 dates. See BDaysResource.count

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • json_from_response_or_raise –

    Extract the json payload from the Response.

  • next_date –

    Returns the next Business day following the provided date. See BDaysResource.next_date

  • previous_date –

    Returns the previous Business day before the provided date. See BDaysResource.previous_date

  • span –

    Get the Start/End dates of periods. See BDaysResource.span

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

bdays_of async

bdays_of(year: int, month: int = None) -> DateSeries

Get the Business days of a year or a month. See BDaysResource.bdays_of

Source code in pycalendar_api/domains/bdays.py
157
158
159
async def bdays_of(self, year: int, month: int=None) -> DateSeries:
    """Get the Business days of a year or a month. See `BDaysResource.bdays_of`"""
    return await self._fetch(self._bdays_of_call(year, month))

between async

between(start: date, end: date) -> DateSeries

Get the Business days between 2 dates. See BDaysResource.between

Source code in pycalendar_api/domains/bdays.py
153
154
155
async def between(self, start: datetime.date, end: datetime.date) -> DateSeries:
    """Get the Business days between 2 dates. See `BDaysResource.between`"""
    return await self._fetch(self._between_call(start, end))

count async

count(start: date, end: date) -> DaysCount

Count the business days (inclusive) between 2 dates. See BDaysResource.count

Source code in pycalendar_api/domains/bdays.py
161
162
163
async def count(self, start: datetime.date, end: datetime.date) -> DaysCount:
    """Count the business days (inclusive) between 2 dates. See `BDaysResource.count`"""
    return await self._fetch(self._count_call(start, end))

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload

next_date async

next_date(date: date) -> NextDate

Returns the next Business day following the provided date. See BDaysResource.next_date

Source code in pycalendar_api/domains/bdays.py
165
166
167
async def next_date(self, date: datetime.date) -> NextDate:
    """Returns the `next` Business day following the provided date. See `BDaysResource.next_date`"""
    return await self._fetch(self._next_date_call(date))

previous_date async

previous_date(date: date) -> PreviousDate

Returns the previous Business day before the provided date. See BDaysResource.previous_date

Source code in pycalendar_api/domains/bdays.py
169
170
171
async def previous_date(self, date: datetime.date) -> PreviousDate:
    """Returns the `previous` Business day before the provided date. See `BDaysResource.previous_date`"""
    return await self._fetch(self._previous_date_call(date))

span async

span(year: int, *, month: int = None, quarter: int = None, semester: int = None) -> CalSpan

Get the Start/End dates of periods. See BDaysResource.span

Raises:

Source code in pycalendar_api/domains/bdays.py
174
175
176
177
178
179
180
async def span(self, year: int, *, month: int=None, quarter: int=None, semester: int=None) -> CalSpan:
    """Get the Start/End dates of periods. See `BDaysResource.span`

    Raises:
        CalendarAPIParamError: Only one of the periods must be provided.
    """
    return await self._fetch(self._span_call(year, month=month, quarter=quarter, semester=semester))

AsyncTaggedCalendarResource

AsyncTaggedCalendarResource(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Async version of TaggedCalendarResource. Same operations, to be awaited.

Methods:

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • json_from_response_or_raise –

    Extract the json payload from the Response.

  • month –

    Get one month of the tagged calendar. See TaggedCalendarResource.month

  • year –

    Get the full tagged calendar of a year. See TaggedCalendarResource.year

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload

month async

month(year: int, month: int) -> TaggedMonth

Get one month of the tagged calendar. See TaggedCalendarResource.month

Source code in pycalendar_api/domains/tagged.py
57
58
59
async def month(self, year: int, month: int) -> TaggedMonth:
    """Get one month of the tagged calendar. See `TaggedCalendarResource.month`"""
    return await self._fetch(self._month_call(year, month))

year async

year(year: int) -> TaggedYear

Get the full tagged calendar of a year. See TaggedCalendarResource.year

Source code in pycalendar_api/domains/tagged.py
53
54
55
async def year(self, year: int) -> TaggedYear:
    """Get the full tagged calendar of a year. See `TaggedCalendarResource.year`"""
    return await self._fetch(self._year_call(year))

AsyncHealthsResource

AsyncHealthsResource(client: Client | AsyncClient, endpoints: dict = None, **kwargs)

Async version of HealthsResource

Methods:

  • api –

    Check the health of the API. See HealthsResource.api

  • endpoint_by_operation –

    Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)

  • host_url –

    Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

  • json_from_response_or_raise –

    Extract the json payload from the Response.

Source code in pycalendar_api/domains/base.py
47
48
49
50
51
52
53
54
def __init__(self, client: Client | AsyncClient, endpoints: dict = None, **kwargs):
    self.client: Client | AsyncClient = client
    if endpoints:
        self.endpoints = endpoints

    if self.endpoints is _UNSET:
        msg = f"endpoint not defined for the resource {self.resource_name}. {self.endpoints=}"
        raise CalendarAPIClientError(msg)

api async

api() -> ApiHealth

Check the health of the API. See HealthsResource.api

Source code in pycalendar_api/domains/health.py
33
34
35
async def api(self) -> ApiHealth:
    """Check the health of the API. See `HealthsResource.api`"""
    return await self._fetch(self._api_call())

endpoint_by_operation

endpoint_by_operation(method: str) -> str

Retrieve the endpoint URL from the deined method key in URLS (self.endpoints) the key is in the form of {self.resource_name}:{method}.

Parameters:

  • method

    (str) –

    Operation key

Returns:

  • str ( str ) –

    Endpoint URL

Raises:

Source code in pycalendar_api/domains/base.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def endpoint_by_operation(self, method: str) -> str:
    """Retrieve the endpoint URL from the deined method key in URLS (self.endpoints)
    the key is in the form of {self.resource_name}:{method}.

    Args:
        method (str): Operation key

    Returns:
        str: Endpoint URL

    Raises:
        CalendarAPIParamError: Method not defined
    """
    try:
        return self.endpoints[self._endpoint_key(method)]
    except KeyError as err:
        msg = f"{method} not defined in self.endpoints de key={err}.\n{self.endpoints=}"
        raise CalendarAPIParamError(msg)

host_url

host_url() -> str

Returns the host url from the client. self.client.base_url contains the /api/v1 path to ease the definition of operation keys.

Source code in pycalendar_api/domains/base.py
75
76
77
78
def host_url(self) -> str:
    """Returns the host url from the client. `self.client.base_url` contains the `/api/v1` path to ease the definition of operation keys.
    """
    return str(self.client.base_url.join("/")).rstrip("/")

json_from_response_or_raise staticmethod

json_from_response_or_raise(response: Response, *, error_key: str = 'detail') -> dict

Extract the json payload from the Response.

Parameters:

  • response

    (Response) –

    httpx Response

  • error_key

    ((str, detail), default: 'detail' ) –

    Error key name in the Json body

Returns:

  • dict ( dict ) –

    Json extracted from the response

Raises:

Source code in pycalendar_api/domains/base.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
@staticmethod
def json_from_response_or_raise(response: Response, *, error_key: str = "detail") -> dict:
    """Extract the json payload from the Response.

    Args:
        response (Response): httpx Response
        error_key (str, 'detail'): Error key name in the Json body

    Returns:
        dict: Json extracted from the response

    Raises:
        CalendarAPIAuthError: If the HTTP response status is 401 or 403
        CalendarAPIClientError: If the HTTP response status is >= 400 or the body is not a valid Json
    """
    try:
        payload = response.json()
    except ValueError:
        payload = None

    if response.status_code >= 400:
        message = payload.get(error_key) if isinstance(payload, dict) else None
        exc_class = CalendarAPIAuthError if response.status_code in (401, 403) else CalendarAPIClientError
        raise exc_class(message or default_message(response, error_key))

    if payload is None:
        raise CalendarAPIClientError(default_message(response, error_key))

    return payload