diff --git a/src/pyventim/public.py b/src/pyventim/public.py index bf76e48..66f6392 100644 --- a/src/pyventim/public.py +++ b/src/pyventim/public.py @@ -1,8 +1,7 @@ """Module for the public Eventim-API wrapper.""" from typing import Dict, List, Literal, Any -from datetime import datetime, date, time - +import datetime import requests @@ -21,6 +20,14 @@ def __init__(self, session: requests.Session = None) -> None: ) def validate_required_parameters(self, **kwargs) -> bool: + """Validates if all required parameters are present + + Raises: + ValueError: Raised if missing query parameters. + + Returns: + bool: True if valid + """ if ( "search_term" not in kwargs and "categories" not in kwargs @@ -33,6 +40,18 @@ def validate_required_parameters(self, **kwargs) -> bool: return True def validate_page_parameter(self, page: int) -> bool: + """Validates the page parameter + + Args: + page (int): Page parameter to check. + + Raises: + ValueError: Raised if page is not a positive and not zero integer. + + + Returns: + bool: True if valid + """ if page: if not isinstance(page, int): raise ValueError("page must be a positive integer!") @@ -43,6 +62,17 @@ def validate_page_parameter(self, page: int) -> bool: return True def validate_sort_parameter(self, sort: str) -> bool: + """Validates the sort parameter based on a known set of values + + Args: + sort (str): Sort parameter to check + + Raises: + ValueError: Raised if sort is not of a predefined value. + + Returns: + bool: True if valid + """ _allowed_values = [ "DateAsc", "DateDesc", @@ -61,6 +91,17 @@ def validate_sort_parameter(self, sort: str) -> bool: return True def validate_search_term_parameter(self, search_term: str) -> bool: + """Validates if the search_term is valid + + Args: + search_term (str): Search_term to check + + Raises: + ValueError: Raised if the search_term is not a valid value. + + Returns: + bool: True if valid + """ if search_term: if not isinstance(search_term, str): raise ValueError("search_term must have atleast two characters!") @@ -69,6 +110,17 @@ def validate_search_term_parameter(self, search_term: str) -> bool: return True def validate_categories_parameter(self, categories: List[str]) -> bool: + """Validates if the categories parameter is valid + + Args: + categories (List[str]): List of categories to check + + Raises: + ValueError: Raised if the categories are not of type List[str] + + Returns: + bool: True if valid + """ if categories: if not isinstance(categories, List): raise ValueError("categories must be a list of strings!") @@ -80,6 +132,17 @@ def validate_categories_parameter(self, categories: List[str]) -> bool: return True def validate_city_ids_parameter(self, city_ids: List[int]) -> bool: + """Validates if the city_ids parameter is valid + + Args: + city_ids (List[int]): List of city_ids to check + + Raises: + ValueError: Raised if the city_ids are not of type List[int] + + Returns: + bool: True if vaild + """ if city_ids: if not isinstance(city_ids, List): raise ValueError("city_ids must be a list of integers!") @@ -90,31 +153,86 @@ def validate_city_ids_parameter(self, city_ids: List[int]) -> bool: return True - def validate_date_from_parameter(self, date_from) -> bool: + def validate_date_from_parameter(self, date_from: datetime.date) -> bool: + """Validates if the date_from parameter is valid. + + Args: + date_from (datetime.date): Value to check. + + Raises: + ValueError: Raised if not a valid value. + + Returns: + bool: True if valid + """ if date_from: - if not isinstance(date_from, date): + if not isinstance(date_from, datetime.date): raise ValueError("date_from must be of type datetime.date!") return True - def validate_date_to_parameter(self, date_to) -> bool: + def validate_date_to_parameter(self, date_to: datetime.date) -> bool: + """Validates if the date_to parameter is valid. + + Args: + date_to (datetime.date): Value to check. + + Raises: + ValueError: Raised if not a valid value. + + Returns: + bool: True if valid + """ if date_to: - if not isinstance(date_to, date): + if not isinstance(date_to, datetime.date): raise ValueError("date_to must be of type datetime.date!") return True - def validate_time_from_parameter(self, time_from) -> bool: + def validate_time_from_parameter(self, time_from: datetime.time) -> bool: + """Validates if the time_from parameter is valid. + + Args: + time_from (datetime.time): Value to check. + + Raises: + ValueError: Raised if not a valid value. + + Returns: + bool: True if valid + """ if time_from: - if not isinstance(time_from, time): + if not isinstance(time_from, datetime.time): raise ValueError("time_from must be of type datetime.time!") return True - def validate_time_to_parameter(self, time_to) -> bool: + def validate_time_to_parameter(self, time_to: datetime.time) -> bool: + """Validates if the time_to parameter is valid. + + Args: + time_to (datetime.time): Value to check. + + Raises: + ValueError: Raised if not a valid value. + + Returns: + bool: True if valid + """ if time_to: - if not isinstance(time_to, time): + if not isinstance(time_to, datetime.time): raise ValueError("time_to must be of type datetime.time!") return True - def validate_in_stock_parameter(self, in_stock) -> bool: + def validate_in_stock_parameter(self, in_stock: bool) -> bool: + """Validates if the in_stock parameter is true. + + Args: + in_stock (bool): Value to check + + Raises: + ValueError: Raised if not a valid value + + Returns: + bool: True if valid + """ if in_stock: if not isinstance(in_stock, bool): raise ValueError("in_stock must be of type bool!") @@ -184,6 +302,16 @@ def explore_attractions( "DateAsc", "DateDesc", "NameAsc", "NameDesc", "Rating", "Recommendation" ] = "DateAsc", ) -> Dict: + """This requests attractions (such as artists, musicals, festivals) via the public Eventim API + + Args: + search_term (str): Search_term to query the endpoint + page (int, optional): Page to fetch. Defaults to 1. + sort (Literal[ "DateAsc", "DateDesc", "NameAsc", "NameDesc", "Rating", "Recommendation" ], optional): Sorting options. Defaults to "DateAsc". + + Returns: + Dict: Returns a result in form of json. + """ params: Dict[str, Any] = self.build_query_parameters( search_term=search_term, page=page, sort=sort ) @@ -193,7 +321,7 @@ def explore_attractions( r.raise_for_status() return r.json() - def explore_content( + def explore_content( # pylint: disable=C0116 self, search_term: str, page: int = 1, @@ -201,6 +329,7 @@ def explore_content( "DateAsc", "DateDesc", "NameAsc", "NameDesc", "Rating", "Recommendation" ] = "DateAsc", ) -> Dict: + """Cant be validated at the moment. Returns no meaning full output.""" # Refactor if this returns any meaning full output: # https://github.com/kggx/pyventim/issues/6 params: Dict[str, Any] = self.build_query_parameters( @@ -221,6 +350,16 @@ def explore_locations( "DateAsc", "DateDesc", "NameAsc", "NameDesc", "Rating", "Recommendation" ] = "DateAsc", ) -> Dict: + """This requests locations (arenas, bars, clubs, etc...) via the public Eventim API. + + Args: + search_term (str): Search_term to query the endpoint + page (int, optional): Page to fetch. Defaults to 1. + sort (Literal[ "DateAsc", "DateDesc", "NameAsc", "NameDesc", "Rating", "Recommendation" ], optional): Sorting sptions. Defaults to "DateAsc". + + Returns: + Dict: Returns a result in form of json + """ params: Dict[str, Any] = self.build_query_parameters( search_term=search_term, page=page, sort=sort ) @@ -246,6 +385,30 @@ def explore_product_groups( ] = "DateAsc", in_stock: bool = True, ) -> Dict: + # pylint: disable=C0301 + """This requests product groups (Musicals, Tours, etc..) via the public Eventim API. + Notes: + - Atleast one of the following must be present: search_term, categories or city_ids. + - date_from and date_to are handled match agains the startDate of an event. + For example: date_from: 2024-01-01 / date_to: 2024-01-02 returns events starting between 2024-01-01 and 2024-01-02 + - time_from and time_to are handled match agains the startDate of an event. + For example: time_from: 11:00am / time_to: 12:00am only returns events starting between 11:00am and 12:00am + + Args: + search_term (str, optional): Search_term to query the endpoint. Defaults to None. + categories (List["str"], optional): Categories to query the endpoint. Defaults to None. + city_ids (List[int], optional): City Ids to query the endpoint. Defaults to None. + date_from (datetime.date, optional): Event start date. Defaults to None. + date_to (datetime.date, optional): Event end date. Defaults to None. + time_from (datetime.time, optional): Event begin time. Defaults to None. + time_to (datetime.time, optional): Event end time. Defaults to None. + page (int, optional): Page to fetch. Defaults to 1. + sort (Literal[ "DateAsc", "DateDesc", "NameAsc", "NameDesc", "Rating", "Recommendation" ], optional): Sorting options. Defaults to "DateAsc". + in_stock (bool, optional): Only show in stock product groups. Defaults to True. + + Returns: + Dict: Returns a result in form of json + """ params: Dict[str, Any] = self.build_query_parameters( search_term=search_term, categories=categories, @@ -258,7 +421,6 @@ def explore_product_groups( sort=sort, in_stock=in_stock, ) - r: requests.Response = self.session.get( f"{self.endpoint}/v2/productGroups", params=params )