pyticketswitch 3.0.0__py3-none-any.whl

pyticketswitch/__init__.py

@@ -0,0 +1,3 @@
+from pyticketswitch.client import Client as Client
+
+__version__ = "3.0.0"

pyticketswitch/_typing.py

@@ -0,0 +1,8 @@
+"""Shared type aliases."""
+
+from decimal import Decimal
+from typing import TypeAlias
+
+# The API returns JSON numbers, which are parsed as ``float`` by default or as
+# ``Decimal`` when the client is created with ``use_decimal=True``.
+Number: TypeAlias = float | Decimal

pyticketswitch/address.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pyticketswitch.mixins import JSONMixin
+
+
+class Address(JSONMixin):
+    """A postal address.
+
+    TODO: this is very similar the Customer object. consider combining them,
+    or subclassing one from the other, or a base class of some sort.
+
+    Attributes:
+        lines (list): list of address lines.
+        town (str): town for the address.
+        county (str): the county or region of the address.
+        country_code (str): ISO 3166-1 country code.
+        post_code (str): post or ZIP code for the address.
+        email (str): a contact email address.
+        home_phone (str): a contact home phone number.
+        work_phone (str): a contact work phone number.
+
+    """
+
+    def __init__(
+        self,
+        lines: list[str] | None = None,
+        country_code: str | None = None,
+        county: str | None = None,
+        email: str | None = None,
+        home_phone: str | None = None,
+        post_code: str | None = None,
+        town: str | None = None,
+        work_phone: str | None = None,
+    ) -> None:
+
+        self.lines = lines
+        self.town = town
+        self.county = county
+        self.country_code = country_code
+        self.post_code = post_code
+        self.email = email
+        self.home_phone = home_phone
+        self.work_phone = work_phone
+
+    @classmethod
+    def from_api_data(cls, data: dict[str, Any]) -> Address:
+        """Creates a new Address object from API data from ticketswitch.
+
+        Args:
+            data (dict): the part of the response from a ticketswitch API call
+                that concerns an address.
+
+        Returns:
+            :class:`Address <pyticketswitch.address.Address>`: a new
+            :class:`Address <pyticketswitch.address.Address>` object
+            populated with the data from the api.
+
+        """
+        lines = [
+            line
+            for line in (data.get("address_line_one"), data.get("address_line_two"))
+            if line is not None
+        ]
+
+        kwargs = {
+            "country_code": data.get("country_code"),
+            "county": data.get("county"),
+            "email": data.get("email_address"),
+            "home_phone": data.get("home_phone"),
+            "post_code": data.get("postcode"),
+            "town": data.get("town"),
+            "work_phone": data.get("work_phone"),
+            "lines": lines,
+        }
+
+        return cls(**kwargs)
+
+    def as_api_billing_address_parameters(self) -> dict[str, str | None]:
+
+        params = {
+            "billing_country_code": self.country_code,
+            "billing_postcode": self.post_code,
+            "billing_town": self.town,
+            "billing_county": self.county,
+        }
+
+        if self.lines and len(self.lines) == 1:
+            params.update(billing_address_line_one=self.lines[0])
+
+        if self.lines and len(self.lines) > 1:
+            params.update(
+                billing_address_line_one=self.lines[0],
+                billing_address_line_two=self.lines[1],
+            )
+        return params

pyticketswitch/availability.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import datetime
+from typing import TYPE_CHECKING, Any, cast
+
+from pyticketswitch.currency import CurrencyMeta
+from pyticketswitch.misc import MONTH_NUMBERS
+from pyticketswitch.mixins import JSONMixin
+
+if TYPE_CHECKING:
+    from pyticketswitch._typing import Number
+
+
+class AvailabilityMeta(CurrencyMeta):
+    """Meta data about an availability response
+
+    Attributes:
+        contiguous_seat_selection_only (bool): indicates that the backend
+            system will only allow seats to be selected that are in a
+            contiguous line.
+        valid_quantities (list): list of valid number of tickets available for
+            selection.
+        max_bundle_size (int): maximum bundle size for this event. If it is
+            `None` then there is no maximum size.
+        currencies (dict): dictionary of
+            :class:`Currency <pyticketswitch.currency.Currency>`) objects
+            indexed on currency code.
+        default_currency_code (str): unless other wise specified all prices in
+            the related response will be in this currency.
+        desired_currency_code (str):
+            the currency that the user account is expecting. Useful for
+            conversions.
+        backend_is_broken (bool): indicates that the backend system is presently
+            marked as broken.
+        backend_is_down (bool): indicates that we are not currently able to
+            contact the backend system.
+        backend_throttle_failed (bool): indicates that your call was throttled
+            and failed to get a slot inside a viable timeframe. When true this
+            indicates that the backend system is under heavy load.
+        source_code (str): the code for the backend system
+        must_select_whole_seat_block (bool): indicates that the backend
+            system will only allow seats to be selected if you select all the
+            seats in the seat_block.
+
+    """
+
+    def __init__(
+        self,
+        contiguous_seat_selection_only: bool = True,
+        currency: str | None = None,
+        valid_quantities: list[int] | None = None,
+        max_bundle_size: int | None = None,
+        backend_is_down: bool | None = False,
+        backend_is_broken: bool | None = False,
+        backend_throttle_failed: bool | None = False,
+        source_code: str | None = None,
+        must_select_whole_seat_block: bool | None = False,
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        self.contiguous_seat_selection_only = contiguous_seat_selection_only
+        self.currency = currency
+        self.max_bundle_size = max_bundle_size
+        self.valid_quantities = valid_quantities
+        self.backend_is_broken = backend_is_broken
+        self.backend_is_down = backend_is_down
+        self.backend_throttle_failed = backend_throttle_failed
+        self.source_code = source_code
+        self.must_select_whole_seat_block = must_select_whole_seat_block
+        super().__init__(*args, **kwargs)
+
+    @classmethod
+    def from_api_data(cls, data: dict[str, Any]) -> AvailabilityMeta:
+        """Creates a new AvailabilityMeta object from API data from ticketswitch.
+
+        Args:
+            data (dict): the whole response from the availability call.
+
+        Returns:
+            :class:`AvailabilityMeta <pyticketswitch.availability.AvailabilityMeta>`:
+            a new
+            :class:`AvailabilityMeta <pyticketswitch.availability.AvailabilityMeta>`
+            object populated with the data from the api.
+
+        """
+        inst = super().from_api_data(data)
+
+        inst.valid_quantities = data.get("valid_quantities")
+        inst.max_bundle_size = data.get("max_bundle_size")
+        inst.contiguous_seat_selection_only = data.get(
+            "contiguous_seat_selection_only", True
+        )
+        inst.backend_is_broken = data.get("backend_is_broken")
+        inst.backend_is_down = data.get("backend_is_down")
+        inst.backend_throttle_failed = data.get("backend_throttle_failed")
+        inst.source_code = data.get("source_code")
+        inst.must_select_whole_seat_block = data.get("must_select_whole_seat_block")
+
+        return inst
+
+
+class AvailabilityDetails(JSONMixin):
+    """Details about the available tickets of a performance.
+
+    Attributes:
+        ticket_type_code (str): identifier of the ticket type.
+        ticket_type_description (str): human readable description of the ticket
+            type.
+        price_band_code (str): identifier of the price band.
+        price_band_description (str): human readable description of the price
+            band.
+        seatprice (float): price of an individual seat.
+        surcharge (float): additional charges per seat.
+        full_seatprice (float): the non-offer price of an individual seat.
+        full_surcharge (float): the non-offer additional charges per seat.
+        currency (str): the currency of the prices.
+        first_date (datetime.date): the first date this
+            combination of ticket type and price band is available from.
+        last_date (datetime.date): the latest date this
+            combination of ticket type and price band is available from.
+        valid_quantities (list): list of valid number of tickets available for
+            selection.
+        cached_number_available (int): the maximum number of consecutive
+            tickets available.
+        discount_code (str): the identifier for the discount.
+        discount_desc (str): a human readable description for the discount.
+        discount_semantic_type (str): a mapping of the code to a meaning
+            e.g. standard (adult) or child
+
+    """
+
+    def __init__(
+        self,
+        ticket_type: str | None = None,
+        price_band: str | None = None,
+        ticket_type_description: str | None = None,
+        price_band_description: str | None = None,
+        seatprice: Number | None = None,
+        surcharge: Number | None = None,
+        full_seatprice: Number | None = None,
+        full_surcharge: Number | None = None,
+        currency: str | None = None,
+        first_date: datetime.date | None = None,
+        percentage_saving: Number | None = None,
+        absolute_saving: Number | None = None,
+        last_date: datetime.date | None = None,
+        calendar_masks: dict[int, dict[int, int]] | None = None,
+        weekday_mask: int | None = None,
+        valid_quantities: list[int] | None = None,
+        cached_number_available: int | None = None,
+        discount_code: str | None = None,
+        discount_desc: str | None = None,
+        discount_semantic_type: str | None = None,
+        suffixed_price_band_code: str | None = None,
+        combined_tax_component: Number | None = None,
+    ) -> None:
+
+        self.ticket_type = ticket_type
+        self.ticket_type_description = ticket_type_description
+        self.price_band = price_band
+        self.price_band_description = price_band_description
+        self.seatprice = seatprice
+        self.surcharge = surcharge
+        self.full_seatprice = full_seatprice
+        self.full_surcharge = full_surcharge
+        self.percentage_saving = percentage_saving
+        self.absolute_saving = absolute_saving
+        self.currency = currency
+        self.first_date = first_date
+        self.last_date = last_date
+        self._calendar_masks = calendar_masks
+        self._weekday_mask = weekday_mask
+        self.weekday_list = None
+        self.valid_quantities = valid_quantities
+        self.cached_number_available = cached_number_available
+        self.discount_code = discount_code
+        self.discount_desc = discount_desc
+        self.discount_semantic_type = discount_semantic_type
+        self.suffixed_price_band_code = suffixed_price_band_code
+        self.combined_tax_component = combined_tax_component
+
+    @classmethod
+    def from_api_data(cls, data: dict[str, Any]) -> list[AvailabilityDetails]:
+        """Creates AvailabilityDetails from API data from ticketswitch.
+
+        Args:
+            data (dict): the part of the response from a ticketswitch API call
+                that concerns availability details.
+
+        Returns:
+            list: a list of
+            :class:`AvailabilityDetails <pyticketswitch.availability.AvailabilityDetails>`
+            objects populated with the data from the api.
+
+        """
+        details = []
+
+        for ticket_type in data.get("ticket_type", []):
+            kwargs = {
+                "ticket_type": ticket_type.get("ticket_type_code"),
+                "ticket_type_description": ticket_type.get("ticket_type_desc"),
+            }
+
+            for price_band in ticket_type.get("price_band", []):
+                kwargs.update(
+                    price_band=price_band.get("price_band_code"),
+                    price_band_description=price_band.get("price_band_desc"),
+                )
+
+                raw_details_list = price_band.get("avail_detail", [{}])
+
+                for raw_details in raw_details_list:
+                    kwargs["seatprice"] = raw_details.get("seatprice", 0.0)
+                    kwargs["full_seatprice"] = raw_details.get("full_seatprice", 0.0)
+                    kwargs["surcharge"] = raw_details.get("surcharge", 0.0)
+                    kwargs["full_surcharge"] = raw_details.get("full_surcharge", 0.0)
+                    kwargs["combined_tax_component"] = raw_details.get(
+                        "combined_tax_component", 0.0
+                    )
+                    kwargs["percentage_saving"] = raw_details.get(
+                        "percentage_saving", 0.0
+                    )
+                    kwargs["absolute_saving"] = raw_details.get("absolute_saving", 0.0)
+                    kwargs["currency"] = raw_details.get("avail_currency_code")
+                    kwargs["discount_code"] = raw_details.get("discount_code")
+                    kwargs["discount_desc"] = raw_details.get("discount_desc")
+                    kwargs["discount_semantic_type"] = raw_details.get(
+                        "discount_semantic_type"
+                    )
+                    kwargs["suffixed_price_band_code"] = raw_details.get(
+                        "suffixed_price_band_code"
+                    )
+
+                    available_dates = raw_details.get("available_dates", {})
+                    if "first_yyyymmdd" in available_dates:
+                        try:
+                            first = datetime.datetime.strptime(
+                                available_dates["first_yyyymmdd"], "%Y%m%d"
+                            )
+                            kwargs["first_date"] = first.date()
+                        except ValueError:
+                            pass
+
+                    if "last_yyyymmdd" in available_dates:
+                        try:
+                            last = datetime.datetime.strptime(
+                                available_dates["last_yyyymmdd"], "%Y%m%d"
+                            )
+                            kwargs["last_date"] = last.date()
+                        except ValueError:
+                            pass
+
+                    kwargs["calendar_masks"] = {
+                        int(year[5:]): {
+                            MONTH_NUMBERS[month[:3]]: mask
+                            for month, mask in month_masks.items()
+                        }
+                        for year, month_masks in available_dates.items()
+                        if year.startswith("year_")
+                    }
+
+                    if "available_weekdays_bitmask" in raw_details:
+                        kwargs["weekday_mask"] = raw_details[
+                            "available_weekdays_bitmask"
+                        ]
+
+                    if "valid_quantities" in raw_details:
+                        kwargs["valid_quantities"] = raw_details["valid_quantities"]
+
+                    kwargs["cached_number_available"] = raw_details.get(
+                        "cached_number_available"
+                    )
+
+                    avail_details = AvailabilityDetails(**kwargs)
+
+                    if avail_details._weekday_mask:
+                        weekday_list = []
+                        for day in range(7):
+                            weekday_list.append(avail_details.on_weekday(day))
+                        avail_details.weekday_list = weekday_list
+                    details.append(avail_details)
+
+        return sorted(
+            details, key=lambda x: (x.ticket_type_description, x.combined_price())
+        )
+
+    def is_available(
+        self, year: int, month: int | None = None, day: int | None = None
+    ) -> bool:
+        """Check availablity on a given year/month/day.
+
+        Args:
+            year (int): the year to check. For example, 2005, 2016, 2222, etc
+            month (int): (optional) the month to check. 1 == jan, 12 == dec, etc
+            day (int): (optional) the day of the month, zero indexed.
+
+        Returns:
+            bool: :obj:`True` when availble inside the given parameters, other
+            wise :obj:`False`.
+
+        Raises:
+            ValueError: when a day is specified but not the month.
+            AssertionError: when the calendar masks data is missing.
+
+        """
+        if day and not month:
+            raise ValueError("a month must be specified to specify a day")
+
+        if self._calendar_masks is None:
+            raise AssertionError("calendar_masks data missing")
+
+        if year not in self._calendar_masks:
+            return False
+
+        year_data = self._calendar_masks[year]
+
+        if month and month not in year_data:
+            return False
+
+        if not day or not month:
+            return True
+
+        month_mask = year_data[month]
+
+        # the month mask is a 32 bit int where the right most bit is the first
+        # day of the month. To find if we have availability on a specfic day,
+        # we bit shift the mask by the zero indexed day and AND it by 1. If the
+        # result is a 1 then this combo of ticket type and price band is
+        # available on that day, otherwise it is not.
+        return bool(month_mask >> day - 1 & 1)
+
+    def on_weekday(self, day: int) -> bool:
+        """
+        Check if this combination of ticket_type and price band is available
+        on a given day of the week, where 0 is monday and sunday is 6.
+
+        .. note:: the api uses sunday as day 0 where as python uses monday.
+                  I've made a concious decision here to use the python numbers
+                  to keep it consistant with anything written against this.
+                  (also sunday as day 0 is silly)
+
+        Args:
+            day: the day of the week zero indexed from monday.
+
+        Returns:
+            bool: :obj:`True` when available on the given day of the week,
+            otherwise :obj:`False`.
+
+        Raises:
+            AssertionError: when the weekday mask data is missing.
+
+        """
+        if self._weekday_mask is None:
+            raise AssertionError("weekday_mask data missing")
+
+        adjusted_day = day + 1 if day < 6 else 0
+
+        return bool(self._weekday_mask >> adjusted_day & 1)
+
+    def combined_price(self) -> Number:
+        if self.seatprice is None:
+            raise AssertionError("seatprice data missing")
+        if self.surcharge is None:
+            raise AssertionError("surcharge data missing")
+
+        # both prices come from the same JSON parse so are the same type
+        return cast("Any", self.seatprice) + self.surcharge
+
+    def combined_full_price(self) -> Number:
+        if self.full_seatprice is None:
+            raise AssertionError("full_seatprice data missing")
+        if self.full_surcharge is None:
+            raise AssertionError("full_surcharge data missing")
+
+        return cast("Any", self.full_seatprice) + self.full_surcharge

pyticketswitch/bundle.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pyticketswitch.debitor import Debitor
+from pyticketswitch.mixins import JSONMixin
+from pyticketswitch.order import Order
+from pyticketswitch.purchase_result import PurchaseResult
+
+if TYPE_CHECKING:
+    from pyticketswitch._typing import Number
+    from pyticketswitch.event import Event
+
+
+class Bundle(JSONMixin):
+    """A collection of orders into the same backend system
+
+    Attributes:
+        source_code (str): the identifier of the backend system.
+        orders (list): the orders.
+        description (str): description of the backend system.
+        total_seatprice (float): the total cost of the seats/tickets in the
+            bundle.
+        total_surcharge (float): the total additional charges for the bundle.
+        total_send_cost (float): the total postage fee for the bundle.
+        total (float): the total amount of money required to purchase this
+            bundle.
+        currency_code (str): the currency that the prices are in.
+        debitor (:class:`Debitor <pyticketswitch.debitor.Debitor>`):
+            information about an external debitor that will be used to take
+            payment for this bundle. When you are selling on credit, or the
+            source system is taking payment, this will be :obj:`None`.
+        terms_and_conditions (str): supplier terms and conditions. Only
+            availabile when requested with the optional ``source_info`` flag.
+        purchase_result (:class:`PurchaseResult <pyticketswitch.purchase_result.
+            PurchaseResult>`): the result of the purchase attempt for the bundle
+        send_cost_tax_component (float): tax of send cost.
+        total_combined_tax_component (float): total tax.
+        total_surcharge_tax_sub_component (float): total surcharge tax.
+
+    """
+
+    def __init__(
+        self,
+        source_code: str | None,
+        orders: list[Order] | None = None,
+        description: str | None = None,
+        total_seatprice: Number | None = None,
+        total_surcharge: Number | None = None,
+        total_send_cost: Number | None = None,
+        total: Number | None = None,
+        currency_code: str | None = None,
+        debitor: Debitor | None = None,
+        terms_and_conditions: str | None = None,
+        purchase_result: PurchaseResult | None = None,
+        send_cost_tax_component: Number | None = None,
+        total_combined_tax_component: Number | None = None,
+        total_surcharge_tax_sub_component: Number | None = None,
+    ) -> None:
+        self.source_code = source_code
+        self.orders = orders
+        self.description = description
+        self.total_seatprice = total_seatprice
+        self.total_surcharge = total_surcharge
+        self.total_send_cost = total_send_cost
+        self.total = total
+        self.currency_code = currency_code
+        self.debitor = debitor
+        self.terms_and_conditions = terms_and_conditions
+        self.purchase_result = purchase_result
+        self.send_cost_tax_component = send_cost_tax_component
+        self.total_combined_tax_component = total_combined_tax_component
+        self.total_surcharge_tax_sub_component = total_surcharge_tax_sub_component
+
+    @classmethod
+    def from_api_data(cls, data: dict[str, Any]) -> Bundle:
+        """Creates a new Bundle object from API data from ticketswitch.
+
+        Args:
+            data (dict): the part of the response from a ticketswitch API call
+                that concerns a bundle.
+
+        Returns:
+            :class:`Bundle <pyticketswitch.bundle.Bundle>`: a new
+            :class:`Bundle <pyticketswitch.bundle.Bundle>` object
+            populated with the data from the api.
+
+        """
+
+        kwargs = {
+            "source_code": data.get("bundle_source_code"),
+            "description": data.get("bundle_source_desc"),
+            "currency_code": data.get("currency_code"),
+            "terms_and_conditions": data.get("source_t_and_c"),
+        }
+
+        raw_orders = data.get("order")
+        if raw_orders:
+            orders = [Order.from_api_data(order) for order in raw_orders]
+            kwargs.update(orders=orders)
+
+        # Below we are explicital checking for not None because we want to
+        # differentiate between situtations where a value is 0 and a value is
+        # missing from the response.
+        total_seatprice = data.get("bundle_total_seatprice")
+        if total_seatprice is not None:
+            kwargs.update(total_seatprice=total_seatprice)
+
+        total_surcharge = data.get("bundle_total_surcharge")
+        if total_surcharge is not None:
+            kwargs.update(total_surcharge=total_surcharge)
+
+        total_send_cost = data.get("bundle_total_send_cost")
+        if total_send_cost is not None:
+            kwargs.update(total_send_cost=total_send_cost)
+
+        total = data.get("bundle_total_cost")
+        if total is not None:
+            kwargs.update(total=total)
+
+        raw_debitor = data.get("debitor")
+        if raw_debitor:
+            debitor = Debitor.from_api_data(raw_debitor)
+            kwargs.update(debitor=debitor)
+
+        raw_purchase_result = data.get("purchase_result")
+        if raw_purchase_result:
+            purchase_result = PurchaseResult.from_api_data(raw_purchase_result)
+            kwargs.update(purchase_result=purchase_result)
+
+        total = data.get("bundle_total_cost")
+        if total is not None:
+            kwargs.update(total=total)
+
+        send_cost_tax_component = data.get("bundle_send_cost_tax_component")
+        if send_cost_tax_component is not None:
+            kwargs.update(send_cost_tax_component=send_cost_tax_component)
+
+        total_combined_tax_component = data.get("bundle_total_combined_tax_component")
+        if total_combined_tax_component is not None:
+            kwargs.update(total_combined_tax_component=total_combined_tax_component)
+
+        total_surcharge_tax_sub_component = data.get(
+            "bundle_total_surcharge_tax_sub_component"
+        )
+        if total_surcharge_tax_sub_component is not None:
+            kwargs.update(
+                total_surcharge_tax_sub_component=total_surcharge_tax_sub_component
+            )
+
+        return cls(**kwargs)
+
+    def get_events(self) -> list[Event]:
+        """Get the events in the bundle.
+
+        Returns:
+            list: list of :class:`Event <pyticketswitch.event.Event>` objects.
+        """
+        if not self.orders:
+            return []
+        return [order.event for order in self.orders if order.event and order.event.id]
+
+    def get_event_ids(self) -> set[str]:
+        """Get the event ids of the events in the bundle.
+
+        Returns:
+            set: set of events IDs (str).
+
+        """
+        return {event.id for event in self.get_events()}
+
+    def is_purchased(self) -> bool:
+        """Check if this bundle was successfully purchased.
+
+        Returns:
+            bool: if the bundle is purchased or not.
+        """
+        if self.purchase_result:
+            return bool(self.purchase_result.success)
+        return False
+
+    def __repr__(self) -> str:
+        return f"<Bundle {self.source_code}>"