Developer Interface

This part of the documentation covers all the interfaces of Pyticketswitch

Ticketswitch Client

class pyticketswitch.client.Client(user, password, url='https://api.ticketswitch.com', sub_user=None, language=None, tracking_id=None, use_decimal=False, **kwargs)[source]

Client wraps the ticketswitch f13 API.

Client contains auth details and provides helper methods for calling the f13 endpoints.

user

user id used to connect to the api.

Type:str
password

Password for the user used to connect to the api.

Type:str
url

Root url for the API. Defaults to https://api.ticketswitch.com.

Type:str, optional
sub_user

the sub user is used to indicate a specific agent of the holder of the main users account requests is being made for. For example a travel agent might hold the main account but an agent in the london office might specify london as their sub user, whereas an agent in belfast might specify belfast or even something more specific. Defaults to None

Type:str, optional
language

prefered IETF language tag. When available this will translate text to the specified language. When None language defaults to user’s preference. Defaults to None.

Type:str, optional
tracking_id

a tracking ID to use with requests

Type:str, optional
use_decimal

parse JSON numbers as decimal. Default is False but this use is deprecated and decimals are recommended.

Type:bool
**kwargs

Additional arbitrary key word arguments to keep with the object.

add_optional_kwargs(params, availability=False, availability_with_performances=False, extra_info=False, reviews=False, media=False, cost_range=False, best_value_offer=False, max_saving_offer=False, min_cost_offer=False, top_price_offer=False, no_singles_data=False, cost_range_details=False, source_info=False, tracking_id=None, **kwargs)[source]

Adds additional arguments to the requests.

All client methods will take several optional arguments that will extend the data returned with addtional information about the returned objects.

Generally these are applicable to objects that return events, however some arguments will also augment performances, cost ranges, and availability details.

See the main F13 documentation for more details.

Parameters:
  • params (dict) – The parameters dictionary into which any additional paramters will be added
  • availability (bool) – Includes general information about availability of events and performances.
  • availability_with_performances (bool) – Includes detailed information about avilability of events and includes performance information.
  • extra_info (bool) – Includes additional event textual content. Defaults to False.
  • reviews (bool) – Includes event reviews when available. Defaults to False.
  • media (bool) – Includes any media assets associated with an event. Defaults to False.
  • cost_range (bool) – Include price range estimates. Defaults to False.
  • best_value_offer (bool) – requires cost_range. Includes the offer with the highest percentage saving in cost range information. Defaults to False.
  • max_saving_offer (bool) – requires cost_range. Includes the offer with the highest absolute saving in cost range information. Defaults to False.
  • min_cost_offer (bool) – requires cost_range. Includes the offer with the lowest cost in cost range information. Defaults to False.
  • top_price_offer (bool) – requires cost_range. Includes the offer with the highest cost in cost range information. Defaults to False.
  • no_singles_data (bool) – requires cost_range. This returns another cost range object that excludes availability with only one consecutive seat available. Defaults to False.
  • cost_range_details (bool) – Cost range information for each available price band. Defaults to False.
  • source_info (bool) – includes information on the source system. defaults to false.
  • tracking_id (string) – Add custom tracking id to the request
  • **kwargs – Additional or override parameters to send with the request.
cleanup_session(session)[source]

Cleans up sessions so that we don’t leave open sockets.

If you want to add support for persistent connections, then you should noop this method so it does nothing.

Parameters:session (requests.Session) – the http session to clean up.
get_addons(token=None, number_of_seats=None, discounts=None, seats=None, send_codes=None, ticket_type_code=None, performance_id=None, price_band_code=None, item_numbers_to_remove=None, **kwargs)[source]

Retrieve a list of add-on events from the API.

Wraps /f13/add_ons.v1

Parameters:
  • token (string) – trolley token from a previous trolley call.
  • number_of_seats (int) – trolley with number of seats added.
  • discounts (list) – list containing discount codes for each requested seat.
  • seats (list) – trolley with added list of seat IDs.
  • send_codes (dict) – send codes indexed on backend source code.
  • ticket_type_code – (string): trolley with tickets of ticket type added.
  • performance_id – (string): trolley with tickets from the specified performance added.
  • price_band_code – (string): trolley with tickets from a specified price band added.
  • item_numbers_to_remove – (list): trolley with a list of item numbers removed.
  • **kwargs – arbitrary additional raw keyword arguments to add to the parameters.
Returns:

a list of Events of add-on events

Return type:

list, EventMeta

Raises:
  • InvalidParametersError – when there is an issue with the provided parameters.
  • InvalidResponse – when the response is in an unexpected format.
get_auth()[source]

Get the authentication parameter for the raw request

This method is intended to be overwritten if required.

Returns:
the authentication parameter
accepted by the requests module
Return type:requests.auth.AuthBase
get_auth_params(**kwargs)[source]

Get the authentication parameters for inclusion in requests.

This method is deprecated - please use get_extra_params instead.

This this method is intended to be overwritten if additional/alternative auth params need to be provided

Returns:auth params that passed to requests
Return type:dict
get_availability(performance_id, number_of_seats=None, discounts=False, example_seats=False, seat_blocks=False, user_commission=False, **kwargs)[source]

Fetch available tickets and prices for a given performance

Wraps /f13/availability.v1

Parameters:
  • performance_id (string) – identifier of the target performance.
  • number_of_seats (int) – number of seats that we after, Defaults to None.
  • discounts (bool) – request all discount options for all price bands in response. Defaults to False.
  • example_seats (bool) – request example seats for seated events. Defaults to False.
  • seat_blocks (bool) – request seating information if available. Defaults to False.
  • user_commission (bool) – request user commission for each price band/discount. Defaults to False
  • **kwargs – see add_optional_kwargs for more info.

Note

setting discounts or the user_commission arguments to True will increase the response time of your request.

Returns:

a list of TicketTypes and and meta data about the response.

Return type:

list, AvailabilityMeta

Raises:
  • BackendBrokenError – when the backend system is responding but may be under heavy load
  • BackendDownError – when the backend system is not responding
  • BackendThrottleError – when your call got throttled and timed out while waiting for a response.
  • InvalidResponse – when the response is in an unexpected format.
get_discounts(performance_id, ticket_type_code, price_band_code, user_commission=False)[source]

Fetch available discounts for a ticket_type/price band combination

Wraps /f13/discounts.v1

Parameters:
  • performance_id (string) – identifier of the target performance.
  • ticket_type_code (string) – code for the target ticket type.
  • price_band_code (string) – code for the target price band.
  • user_commission (bool) – if True then return the user_commission, otherwise do not return the user_commission. Defaults to False.
Returns:

a list of Discounts and information about the currencies of the prices in the response.

Return type:

list, CurrencyMeta

Raises:

InvalidResponse – when the response is in an unexpected format.

get_event(event_id, **kwargs)[source]

Get a specific event by id

Helper method to avoid having to do something like this lots of times:

>>> client.get_events(['6IF'])['6IF']
<Event 6IF:Matthew Bourne's Nutcracker TEST>

Instead this interface is much less stuttery:

>>> client.get_event('6IF')
<Event 6IF:Matthew Bourne's Nutcracker TEST>
Parameters:
Returns:

the target event and meta information about the event.

will return None if the event does not exist.

Return type:

Event, EventMeta

get_events(event_ids, with_addons=False, with_upsells=False, **kwargs)[source]

Get events with the given id’s

Wraps /f13/events_by_id.v1

Parameters:
  • event_ids (list) – list of event IDs
  • with_addons (bool) – include add-on events
  • with_upsells (bool) – include upsell events
  • **kwargs – see add_optional_kwargs for more info.
Returns:

Events indexed by event ID and meta information for those events.

Return type:

dict, EventMeta

Raises:

InvalidResponse – when the response is in an unexpected format

get_extra_params()[source]

Get additional parameters for inclusion in requests.

This method is intended to be overwritten if additional/alternative parameters need to be provided in the query string or POST body.

Returns:parameters that will be included in the request
Return type:dict
get_headers(headers)[source]

Generate common headers to send with all requests

Returns:key value map of headers
Return type:dict
get_months(event_id, **kwargs)[source]

Returns a summary of availability accross months.

Wraps /f13/months.v1

Parameters:
Returns:

Months ordered chronologically

Return type:

list

Raises:

InvalidResponse – when the response is in an unexpected format

get_performance(performance_id, **kwargs)[source]

Get a specific performance by id

Helper method to avoid having to do something like this lots of times:

>>> client.get_performances(['6IF-B1H'])['6IF-B1H']
<Performance 6IF-B1H: 2017-06-02T19:30:00+01:00>

Instead this interface is much less stuttery:

>>> client.get_performance('6IF-B1H')
<Performance 6IF-B1H: 2017-06-02T19:30:00+01:00>
Parameters:
  • performance_id (str) – ID of the performance to retrieve
  • **kwargs – see add_optional_kwargs for more info.
Returns:

the target Performance and meta information about the performance.

will return None if the performance does not exist.

Return type:

Performance, PerformanceMeta

get_performances(performance_ids, **kwargs)[source]

Get performances with the given ID’s

Wraps /f13/performances_by_id.v1

Parameters:
Returns:

Performances indexed by performance ID and meta information about the performances.

Return type:

dict, PerformanceMeta

Raises:

InvalidResponse – when the response is in an unexpected format.

get_send_methods(performance_id, **kwargs)[source]

Fetch available delivery methods for a given performance

Wraps /f13/send_methods.v1

Parameters:
  • performance_id (string) – identifier of the target performance.
  • **kwargs – see add_optional_kwargs for more info.
Returns:

a list of SendMethods and information about the currencies of the prices in the response

Return type:

list, CurrencyMeta

Raises:

InvalidResponse – when the response is in an unexpected format.

get_session()[source]

Get the requests.Session instance to use to make HTTP requests

By default this method will create a new session for each request. This replicates the default behaviour of the requests library: https://github.com/kennethreitz/requests/blob/ead8fba84b12e7496c65272a07de47d553aa0ca0/requests/api.py#L57-L58

A common modification to this class would be to overload this method to provide a single session instance across all calls to take advantage of keep-alive.

Note

remember to also overload cleanup_session as well or you connections/session might be unexpectedly killed.

get_status(transaction_uuid=None, transaction_id=None, customer=False, external_sale_page=False, **kwargs)[source]

Get the status of reservation, purchase or transaction.

Note

The transaction_id field is for backwards compatability with the old XML API. You can use either transaction_id or transaction_uuid, however please use the transaction_uuid as transaction_id will be deprecated shortly.

Wraps /f13/status.v1

Parameters:
  • transaction_uuid (str) – identifier for the transaction.
  • transaction_id (str) – identifier for the old transaction ids. Note: one of these two must be set.
  • customer (bool) – include customer information if available. Defaults to False.
  • external_sale_page (bool) – include the saved html of the sale/confirmation page if you asked us to save it for you. Defaults to None
  • **kwargs – arbitary keyword parameters to pass directly to the API.
Returns:

the current status of the transaction and acompanying meta information.

Return type:

Status, CurrencyMeta

get_tracking_params(custom_tracking_id=None)[source]

Return current request’s session tracking id or custom tracking id passed

get_trolley(token=None, number_of_seats=None, discounts=None, seats=None, send_codes=None, ticket_type_code=None, performance_id=None, price_band_code=None, item_numbers_to_remove=None, raise_on_unavailable_order=False, **kwargs)[source]

Retrieve the contents of a trolley from the API.

Wraps /f13/trolley.v1

Parameters:
  • token (string) – trolley token from a previous trolley call.
  • number_of_seats (int) – number of seats to add to the trolley.
  • discounts (list) – list containing discount codes for each requested seat.
  • seats (list) – list of seat IDs.
  • send_codes (dict) – send codes indexed on backend source code.
  • ticket_type_code (string) – code of ticket type to add to the trolley.
  • performance_id (string) – id of the performance to add to the trolley.
  • price_band_code (string) – code of price band to add to the trolley.
  • item_numbers_to_remove (list) – list of item numbers to remove from trolley.
  • raise_on_unavailable_order (bool) – When set to True this method will raise an exception when the API was not able to add an order to the trolley as it was unavailable.
  • **kwargs – arbitary additional raw keyword arguments to add the parameters.
Returns:

the contents of the trolley and meta data associated with the trolley.

Return type:

Trolley, CurrencyMeta

Raises:
  • InvalidParametersError – when there is an issue with the provided parameters.
  • OrderUnavailableError – when raise_on_unavailable_order is set to True and the requested addition to a trolley was unavailable.
get_upsells(token=None, number_of_seats=None, discounts=None, seats=None, send_codes=None, ticket_type_code=None, performance_id=None, price_band_code=None, item_numbers_to_remove=None, **kwargs)[source]

Retrieve a list of upsell events related to a trolley from the API.

Upsell events are related to a main event but can be purchased separately. This call accepts a trolley token or any combination of parameters to create a valid trolley, but does not alter any existing trolley (it is idempotent).

Wraps /f13/upsells.v1

Parameters:
  • token (string) – trolley token from a previous trolley call.
  • number_of_seats (int) – trolley with number of seats added.
  • discounts (list) – list containing discount codes for each requested seat.
  • seats (list) – trolley with added list of seat IDs.
  • send_codes (dict) – send codes indexed on backend source code.
  • ticket_type_code – (string): trolley with tickets of ticket type added.
  • performance_id – (string): trolley with tickets from the specified performance added.
  • price_band_code – (string): trolley with tickets from a specified price band added.
  • item_numbers_to_remove – (list): trolley with a list of item numbers removed.
  • **kwargs – arbitary additional raw keyword arguments to add the parameters.
Returns:

a list of Events of related upsell events

Return type:

list, EventMeta

Raises:
  • InvalidParametersError – when there is an issue with the provided parameters.
  • InvalidResponse – when the response is in an unexpected format.
get_url(end_point)[source]

Get the url for a given endpoint

Parameters:end_point (str) – the target api end point, for example events.v1 or performances.v1
Returns:the full url for the given endpoint, contains the base url and endpoint
Return type:str
get_user_agent()[source]

Get the user agent for the raw request

This method is intended to be overwritten by subclasses that want a custom User-Agent header for the requests

Returns:str: the user agent string
list_events(keywords=None, start_date=None, end_date=None, country_code=None, city_code=None, latitude=None, longitude=None, radius=None, include_dead=False, sort_order=None, page=0, page_length=0, **kwargs)[source]

List events with the given parameters

Wraps /f13/events.v1

Called with out arguments this method will return all live events available to the user.

Parameters:
  • keywords (list) – list of keyword strings. For example: keywords=['sadlers', 'nutcracker']. Defaults to None.
  • start_date (datetime.datetime) – only show events that have a performance after this date. Defaults to None.
  • end_date (datetime.datetime) – only show events that have a performance before this date. Defaults to None.
  • country_code (string) – only show events in this country. the country is specified by it’s ISO 3166-1 country code. Defaults to None.
  • city_code – (string): specified by the internal city code. As a rule of thumb this is the lowercase city name followed by a hyphen followed by the ISO 3166-1 country code. For example: london-uk, new_york-us, berlin-de. Defaults to None.
  • latitude (float) – only show events near this latitude. valid only in combination with longitude and radius. Defaults to None.
  • longitude (float) – only show events near this longitude. valid only in combination with latitude and radius. Defaults to None.
  • radius (float) – only show events inside this radius relative to the provided coordinates (latitude & longitude above). Units are kilometers. Defaults to None.
  • include_dead (bool) – when true results will include all events even if they are dead (are unavailable to purchase from). Defaults to False.
  • sort_order (string) – order the returned events by the specified metric. See sorting search results. Defaults to None
  • page (int) – the page of a paginated response.
  • page_length (int) – how many performances are returned per page.
  • **kwargs – see add_optional_kwargs for more info.
Returns:

a list of Events objects and meta information for those events.

Return type:

list, EventMeta

Raises:
  • InvalidGeoParameters – when latitude, longitude, or radius is specified without the rest of the required geographic parameters.
  • InvalidResponse – when the response is in an unexpected format
list_performances(event_id, start_date=None, end_date=None, page_length=0, page=0, **kwargs)[source]

List performances for a specified event

Wraps /f13/performances.v1

Parameters:
  • event_id (str) – identifier for the event.
  • start_date (datetime.datetime) – list performances only if they occur after this date.
  • end_date (datetime.datetime) – list performances only if they occur before this date.
  • page (int) – the page of a paginated response.
  • page_length (int) – how many performances are returned per page.
  • **kwargs – see add_optional_kwargs for more info.
Returns:

A list of Performances for the given event and meta information about the performances.

Return type:

list, PerformanceMeta

Raises:

InvalidResponse – when the response is in an unexpected format

make_purchase(transaction_uuid, customer, payment_method=None, send_confirmation_email=True, agent_reference=None, **kwargs)[source]

Purchase tickets for an existing reservation.

Wraps /f13/purchase.v1

Parameters:
  • transaction_uuid (str) – the identifier of the existing reservation/transaction
  • customerCustomer <pyticketswitch.customer.Customer> information.
  • payment_method – the customer’s payment details. Can be CardDetails or RedirectionDetails.
  • send_confirmation_email (bool) – on a successful purchase, when this parameter is True, then we will send the customer a confirmation email. If you would prefer to send your own confirmation email then you can set this parameter to False.
  • agent_reference (str) – an optional custom transaction reference to be stored in the Ingresso platform
  • **kwargs – arbitrary keyword arguments to send with the request.
Returns:

Status, Callout: the current status of the transaction and/or a potential callout to redirect the customer to.

This method should only ever return either a status or a callout, never both.

If this method generates a Callout then the customer should be redirected to the specified third party payment provider.

See Handling callouts for more information.

make_request(endpoint, params, method='get', headers={}, timeout=None)[source]

Makes actual requests to the API

Parameters:
  • endpoint (str) – target API endpoint
  • params (dict) – parameters to provide to requests
  • method (str) – HTTP method to make the request with valid values are post and get. Defaults to get.
  • headers (dict) – headers to include with the request
  • timeout (int) – timeout to include with the request. Defaults to None.
Returns:

The body of the response after deserialising from JSON

Return type:

str

Raises:
  • AuthenticationError – When authentication details provided are invalid
  • InvalidResponseError – When the status code of the response is not 200
  • APIError – When any other explict errors are returned from the API
make_reservation(token=None, number_of_seats=None, discounts=None, seats=None, send_codes=None, ticket_type_code=None, performance_id=None, price_band_code=None, item_numbers_to_remove=None, raise_on_unavailable_order=False, **kwargs)[source]

Attempt to reserve all the items in the given trolley

Wraps /f13/reserve.v1

This method will take all the same arguments as get_trolley. You can either build a trolley via the get_trolley method and pass the returned trolley token into the reservation call, or alternatively you can provide the trolley parameters directly to this method.

Note

If you are interested in bundling multiple orders into a single purchase then see the Bundling documentation for more details.

Parameters:
  • token (string) – trolley token from a previous trolley call.
  • number_of_seats (int) – number of seats to add to the trolley.
  • discounts (list) – list containing discount codes for each requested seat.
  • seats (list) – list of seat id’s.
  • send_codes (dict) – send codes indexed on backend source code.
  • ticket_type_code – (string): code of ticket type to add to the trolley.
  • performance_id – (string): id of the performance to add to the trolley.
  • price_band_code – (string): code of price band to add to the trolley
  • item_numbers_to_remove – (list): list of item numbers to remove from trolley.
  • raise_on_unavailable_order (bool) – When set to True this method will raise an exception when the API was not able to add an order to the trolley as it was unavailable.
  • **kwargs – arbitary additional raw keyword arguments to add the parameters.
Returns:

Information about the reservation and meta data asscociated with the reservation.

Return type:

Reservation, CurrencyMeta

Raises:
  • InvalidParametersError – when there is an issue with the provided parameters.
  • OrderUnavailableError – when raise_on_unavailable_order is set to True and the requested addition to a trolley was unavailable.
next_callout(this_token, next_token, returned_data, **kwargs)[source]

Gets the next callout in a callout chain.

Wraps /f13/callback.v1

At the end of the callout chain the call will return the status of the transaction.

See Handling callouts for more information.

Parameters:
  • this_token (str) – the token for the current redirect.
  • next_token (str) – the token for the potential next redirect.
  • returned_data (dict) – dictionary of query string paramters appended to your return url.
  • **kwargs – arbitary keyword arguments to send with the request.
Returns:

Status, Callout: the current status of the transaction and/or a potential callout to redirect the customer to.

This method should only ever return either a status or a callout, never both.

release_reservation(transaction_uuid, **kwargs)[source]

Release an existing reservation.

Wraps /f13/release.v1

Parameters:
  • transaction_uuid (str) – the identifier of the reservaiton.
  • **kwargs – arbitary additional raw keyword arguments to add the parameters.
Returns:

True if the reservation was successfully released otherwise False.

Return type:

bool

test()[source]

Test the connection

Wraps /f13/test.v1

will return the running user on sucess and will raise an exception if the authentication details are invalid.

This call is not required, but may be useful for validating auth credentials, or checking on the health of the ticketswitch API.

Returns:details about the user calling the API
Return type:pyticketswitch.user.User

Core

The follow are the core business objects.

class pyticketswitch.event.Event(id_, status=None, event_type=None, source=None, source_code=None, venue=None, description=None, postcode=None, classes=None, filters=None, upsell_list=None, city=None, city_code=None, country=None, country_code=None, latitude=None, longitude=None, needs_departure_date=False, needs_duration=False, addon_events=None, upsell_events=None, needs_performance=False, has_performances=False, is_seated=False, show_performance_time=False, min_running_time=None, max_running_time=None, cost_range=None, no_singles_cost_range=None, cost_range_details=None, content=None, event_info_html=None, event_info=None, venue_addr_html=None, venue_addr=None, venue_info=None, venue_info_html=None, media=None, reviews=None, critic_review_percent=None, availability_details=None, component_events=None, valid_quantities=None, fields=None, raw=None, is_add_on=None, area_code=None, venue_code=None, venue_is_enforced=None, lingo_code=None)[source]

Describes a product in the ticketswitch system.

id

the identifier for the event.

Type:str
status

status of the event.

Type:str
description

human readable name for the event.

Type:str
source

the backend system from wich the event originates.

Type:str
source_code

the internal code for the backend system.

Type:str
event_type

the type of the event.

Type:str
venue

a human readable description of the venue.

Type:str
classes

a dictionary of class descriptions that the event belongs to keyed on class identifier.

Type:dict
filters

a list of filters that the event belongs to.

Type:list
postcode

venue post code.

Type:str
city

human readable venue city.

Type:str
city_code

venue city code

Type:str
country

human readable country name.

Type:str
country_code

ISO 3166-1 country code.

Type:str
latitude

latitude of the venue.

Type:float
longitude

longitude of the venue.

Type:float
max_running_time

maximum running time of a performance in minutes.

Type:int
min_running_time

minimum running time of a performance in minutes.

Type:int
show_performance_time

indicates that the performance time for this event is relevant and should be shown.

Type:bool
has_performances

indicates that the event has performances.

Type:bool
is_seated

indicates the event is seated.

Type:bool
needs_departure_date

indicates that ticket purchases for this event will require a departure date.

Type:bool
needs_duration

indicates that ticket purchases for this event will require a duration.

Type:bool
needs_performance

indicates that you should ask your customer what date/time they want to attend this event on. See Events that don’t need performance selection for more information.

Type:bool
upsell_list

list of event id’s.

Type:list
cost_range

pricing summary from cached availability. Only present when requested.

Type:CostRange
no_singles_cost_range

pricining summary from cached availability. Only present when requested.

Type:CostRange
cost_range_details

summary pricing information broken down by availability. This is cached data. Only present when requested.

Type:CostRangeDetails
content

dictionary of Content objects indexed on content name. Only present when requested.

Type:dict
fields

dictionary of Field objects indexed on field name. Only present when requested.

Type:dict
event_info

event info in plain text. Only present when requested.

Type:str
event_info_html

event info as HTML. Only present when requested.

Type:str
venue_addr

venue address in plain text. Only present when requested.

Type:str
venue_addr_html

venue address as HTML. Only present when requested.

Type:str
venue_info

venue info in plain text. Only present when requested.

Type:str
venue_info_html

venue info as HTML. Only present when requested.

Type:str
media

dictionary of Media objects indexed on media name. Only present when requested.

Type:dict
reviews

list of Reviews objects. Only present when requested.

Type:list
critic_review_percent

summary of critic review star rating. rated from 1 (lowest) to 5 (highest).

Type:float
availability_details

summary of availability details from cached data. Only present when requested.

Type:AvailabilityDetails
component_events

list of Events objects that comprise a meta event.

Type:list
valid_quantities

list of valid quanities available for purchase. from cached data, only available when requested by get_events or get_event.

Type:list
raw

the raw data used to generate the object.

Type:dict
is_addon

indicates that the event is an addon.

Type:bool
area_code

the internal code for the area. This is for internal use only.

Type:str
venue_code

the internal code for the venue. This is for internal use only.

Type:str
venue_is_enforced

indicates if the venue is enforced. This is for internal use only.

Type:bool
lingo_code

a code for the type of event, e.g. theatre or attraction. This is for internal use only.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod class_dict_from_api_data(data)[source]

Creates a dict of Event data from a raw ticketswitch API call

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a event.
Returns:a new dict populated with the data from the api for creating an Event object
Return type:dict
classmethod from_api_data(data)[source]

Creates a new Event object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a event.
Returns:a new Event object populated with the data from the api.
Return type:Event
classmethod from_events_by_id_api_data(data)[source]

Creates a new Event object from API data from the events_by_id call.

Parameters:data (dict) – the part of the response from the ticketswitch events_by_id API call containing events and other data.
Returns:a new Event object populated with the data from the API.
Return type:Event
class pyticketswitch.month.Month(month, year, description=None, dates_bitmask=None, weekday_bitmask=None, cost_range=None, no_singles_cost_range=None)[source]

Availability summary data for a given month

month

number of the month, jan == 1, feb == 2, dec == 12, etc.

Type:int
year

year of the month. eg. 2014, 2015, 2016.

Type:int
description

the human readable description of the month.

Type:str
cost_range

pricing summary, may also include offers.

Type:CostRange
no_singles_cost_range

pricing summary when no leaving single seats, may also include offers.

Type:CostRange
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

is_available(day)[source]

Indicates if the event has availability on a given day.

the dates bitmask 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.

Parameters:day (int) – the day of the month.
Returns:True there is availability on the given day. Otherwise False.
Return type:bool
on_weekday(day)[source]

Indicates if the event has availability on a given day of the week.

Check if the month has shows 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 consistent with anything written against this. (also a sunday day 0 is silly).

FIXME: this is copied directly from the AvailabilityDetails class. Perhaps worth breaking this out to common base or mixin class?

Parameters:day (int) – the day of the week. monday = 0, tuesday = 1, sunday = 6.
Returns:True there is availability on the given day. Otherwise False.
Return type:bool
class pyticketswitch.performance.Performance(id_, event_id, date_time=None, date_description=None, time_description=None, has_pool_seats=False, is_limited=False, cached_max_seats=None, cost_range=None, no_singles_cost_range=None, is_ghost=False, name=None, running_time=None, availability_details=None)[source]

Describes and occurance of an Event.

The performance will have either a date_time or a name.

Note

The date_time field is a timezone aware datetime and it is localised for the venue and not the user.

id

identifier for the performance.

Type:str
event_id

identifier for the event.

Type:str
date_time

the localised date and time for the performance.

Type:datetime.datetime
date_description

a human readable description of the date of the performance.

Type:str
time_description

a human readable description of the time of the performance.

Type:str
has_pool_seats

the performance has pool seats available.

Type:bool
is_limited

the performance has limited availability.

Type:bool
cached_max_seats

the maximum number of seats available to book in a single order. This value is cached and may not be accurate.

Type:int
cost_range

pricing summary, may also include offers.

Type:CostRange
no_singles_cost_range

pricing summary when no leaving single seats, may also include offers.

Type:CostRange
is_ghost

the performance is a ghost performance and is nolonger available.

Type:bool
name

the name of the performance.

Type:str
running_time

the number of minutes the performance is expected to run for.

Type:int
availability_details

summerised availability data for the performance. This data is cached from previous availability calls and may not be accurate.

Type:AvailabilityDetails
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Performance object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a performance.
Returns:a new Performance object populated with the data from the api.
Return type:Performance
class pyticketswitch.ticket_type.TicketType(code=None, description=None, price_bands=None)[source]

Describes a collection of tickets.

Generally this represents a part of house in a venue, but may have other meanings in contexts outside theater and music.

code

identifier for the ticket type.

Type:str
description

human readable description of the ticket type.

Type:str
price_bands

list of PriceBands objects wich further subdivided available tickets/seats by price.

Type:list
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new PriceBand object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a price band.
Returns:a new PriceBand object populated with the data from the api.
Return type:PriceBand
get_seats()[source]

Get seats in the ticket type.

Returns:list of Seats objects.
Return type:list
class pyticketswitch.price_band.PriceBand(code, default_discount, description=None, cost_range=None, no_singles_cost_range=None, example_seats=None, example_seats_are_real=True, seat_blocks=None, user_commission=None, discounts=None, allows_leaving_single_seats=None, availability=None, seatprice=None, surcharge=None, non_offer_seatprice=None, non_offer_surcharge=None, percentage_saving=0, absolute_saving=0)[source]

Describes a set of tickets with the same ticket type and price.

code

the price band identifier.

Type:str
default_discount

this is the discount that will be assumed if no other discount is specified at reservation time. It holds the prices for the price band.

Type:Discount
allows_leaving_single_seats

indicates if this price band will allow customers to leave a single seat with no neighbours. Values are ‘always’, ‘never’, or ‘if_necessary’.

Type:str
description

human readable description of the price band if available.

Type:str
cost_range

summary data for the price band including offers.

Type:CostRange
no_singles_cost_range

summary data for the price band including offers.

Type:CostRange
example_seats

list of Seats that can be used as examples of what the user might get when they reserved tickets in this price band.

Type:list
example_seats_are_real

when True this field indicates that the example seats are in fact real seats and will be the ones we attempt to reserve at the reservation stage. When False these seats merely examples retrieved from cached data, and have likely already been purchased.

Type:bool
seat_blocks

list of SeatBlocks. When available this are the contiguous seats that are available for purchase. SeatBlocks contain Seats.

Type:list
user_commission

the commission payable to the user on the sale of tickets in this price band. Only available when requested.

Type:Commission
gross_commission

the gross commission payable. This is not generally available.

Type:Commission
availability

the number of tickets/seats available in this price band.

Type:int
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

combined_price()

Returns the combined seatprice and surcharge.

This method assumes that we have both a seatprice and surcharge. In the situation where are missing either a seatprice or a surcharge then we don’t have all the information to be able provide this information.

Returns:the combined seatprice and surcharge
Return type:float
Raises:AssertionError – It might seem like the obvious thing to do would be to assume the missing data was in fact zero and simply allow the addition to continue. However that would be somewhat dangerous when we are talking about prices, and it’s better to actually raise an exception to indicate that there was a problem with the objects data, than to inform a customer that the tickets are free or have no booking fees
classmethod from_api_data(data)[source]

Creates a new PriceBand object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a price band.
Returns:a new PriceBand object populated with the data from the api.
Return type:PriceBand
get_seats()[source]

Get all seats in child seat blocks

Returns:list of Seats.
Return type:list
non_offer_combined_price()

Returns the combined non offer seatprice and surcharge.

This method assumes that we have both a seatprice and surcharge. In the situation where are missing either a seatprice or a surcharge then we don’t have all the information to be able provide this information.

Returns:the combined seatprice and surcharge
Return type:float
Raises:AssertionError – It might seem like the obvious thing to do would be to assume the missing data was in fact zero and simply allow the addition to continue. However that would be somewhat dangerous when we are talking about prices, and it’s better to actually raise an exception to indicate that there was a problem with the objects data, than to inform a customer that the tickets are free or have no booking fees
class pyticketswitch.discount.Discount(code, description=None, price_band_code=None, availability=None, is_offer=False, percentage_saving=0, absolute_saving=0, gross_commission=None, user_commission=None, disallowed_seat_nos=None, *args, **kwargs)[source]

Represents a set of prices for a price band.

code

the identifier for the discount.

Type:str
description

a human readable description for the discount.

Type:str
price_band_code

identifier for the related price band.

Type:str
is_offer

indicates that the discount is an offer.

Type:bool
availability

the number tickets available with this discount.

Type:int
percentage_saving

the amount saved compared to when this discount is not on offer, as a percentage or the non offer price.

Type:float
absolute_saving

the amount saved compared to when this discount is not on offer.

Type:float
gross_commission (

class: Commission <pyticketswitch.commission.Commission>): predicted commission to be shared between ingresso and the partner.

user_commission

predicted commission for the partner.

Type:Commission
disallowed_seat_nos

a list of seat numbers, that this discount code cannot be specified for.

Type:list
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

combined_price()

Returns the combined seatprice and surcharge.

This method assumes that we have both a seatprice and surcharge. In the situation where are missing either a seatprice or a surcharge then we don’t have all the information to be able provide this information.

Returns:the combined seatprice and surcharge
Return type:float
Raises:AssertionError – It might seem like the obvious thing to do would be to assume the missing data was in fact zero and simply allow the addition to continue. However that would be somewhat dangerous when we are talking about prices, and it’s better to actually raise an exception to indicate that there was a problem with the objects data, than to inform a customer that the tickets are free or have no booking fees
classmethod from_api_data(data)[source]

Creates a new Discount object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a discount.
Returns:a new Discount object populated with the data from the api.
Return type:Discount
non_offer_combined_price()

Returns the combined non offer seatprice and surcharge.

This method assumes that we have both a seatprice and surcharge. In the situation where are missing either a seatprice or a surcharge then we don’t have all the information to be able provide this information.

Returns:the combined seatprice and surcharge
Return type:float
Raises:AssertionError – It might seem like the obvious thing to do would be to assume the missing data was in fact zero and simply allow the addition to continue. However that would be somewhat dangerous when we are talking about prices, and it’s better to actually raise an exception to indicate that there was a problem with the objects data, than to inform a customer that the tickets are free or have no booking fees
class pyticketswitch.send_method.SendMethod(code, cost=None, description=None, typ=None, permitted_countries=None, can_generate_self_print=False, self_print_voucher_url=None, final_comment=None)[source]

Describes a method of sending tickets to a customer.

code

identifier for the send method.

Type:str
cost

additional cost to the customer for this send method.

Type:float
description

human readable description of the send method.

Type:str
type

indicates the type of the send method.

Type:str
can_generate_self_print

indicates if the send method can self print a voucher

Type:bool
self_print_voucher_url

url for the client to download their voucher from

Type:str
final_comment

comment about dispatching tickets

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new SendMethod object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a send method.
Returns:a new SendMethod object populated with the data from the api.
Return type:SendMethod
class pyticketswitch.trolley.Trolley(token=None, transaction_uuid=None, transaction_id=None, bundles=None, discarded_orders=None, minutes_left=None, order_count=None, purchase_result=None, input_contained_unavailable_order=False)[source]

Describes a collection of products that are being purchased.

token

a token that represents the current state of the trolley.

Type:str
transaction_uuid

unique identifier for this trolley. Only present after reservation.

Type:str
transaction_id

unique identifier for this trolley. Only present after purchase. This supposed to be an identifer that is easily readable/recognisable by a human being.

Type:str
bundles

list of Bundles objects that break down the items to be purchased by their source systems.

Type:list
discarded_orders

list of Orders objects that were in the trolley in the past but have been removed.

Type:list
minutes_left

the number of minutes left before a reservation expires.

Type:float
order_count

the number of orders in the trolley.

Type:int
purchase_result

the result of the purchase attempt when available.

Type:PurchaseResult
input_contained_unavailable_order

indicates that the call used to create or modify this trolley object included at least one order that was not available.

Type:bool
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Trolley object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a trolley.
Returns:a new Trolley object populated with the data from the api.
Return type:Trolley
get_bundle(source_code)[source]

Find a bundle with a specific source code

Parameters:source_code (str) – the source code for the target bundle.
Returns:the bundle with the requested source code.

When no bundle with that source code is present returns None.

Return type:Bundle
get_event_ids()[source]

Get the event ids of the events in the trolley.

Returns:set of events IDs (str).
Return type:set
get_events()[source]

Get the events in the trolley.

Returns:list of Event objects.
Return type:list
get_item(item_number)[source]

Find an order with the given item number

Parameters:item_number (int) – the item number of the target order
Returns:the order with the specified
Return type:Order
get_orders()[source]

Get all orders in all bundles in a trolley

Returns:orders from all bundles in the the trolley
Return type:list
class pyticketswitch.reservation.Reservation(unreserved_orders=None, input_contained_unavailable_order=False, *args, **kwargs)[source]

Describes some tickets currently being held for purchase

status

the currency status of the transaction.

Type:str
reserved_at

the date and time when the transaction was reserved.

Type:datetime.datetime
purchased_at

the date and time when the transaction was purchased.

Type:datetime.datetime
trolley

the contents of the transactions trolley.

Type:Trolley
external_sale_page

the page that was rendered to the customer after the transaction was completed. This is only available if it was passed into the API at purchase time.

Type:str
languages

list of IETF language tags relevant to the transaction.

Type:list
remote_site

the remote site the transaction was reserved and purchased under.

Type:str
reserve_user

the user that was used to reserve the transaction.

Type:User
unreserved_orders

list of Orders <pyticketswitch.order.Order>` that failed to reserve.

Type:list
prefilled_address

some address information that should be used to prefill any customer address fields. This is primarily used on B2B accounts.

Type:Address
needs_payment_card

When True indicates that this reservation will require CardDetails as the payment method at purchase time.

Type:bool
needs_email_address

When True indicates that the customer needs to provide a valid email address at purchase time.

Type:bool
needs_agent_reference

When True indicates that an agent reference should be provided at purchase time.

Type:bool
can_edit_address

When False indicates that the prefilled customer address provided by prefilled_address should not be edited.

Type:bool
allowed_countries

list of Countries that are acceptable for the customers postal address to be from.

Type:list
minutes_left

the number of minutes left before a reservation expires.

Type:float
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Reservation object from ticketswitch API data.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a reservation.
Returns:a new Reservation object populated with the data from the api.
Return type:Reservation
class pyticketswitch.status.Status(status=None, reserved_at=None, trolley=None, purchased_at=None, external_sale_page=None, languages=None, remote_site=None, reserve_user=None, prefilled_address=None, needs_payment_card=False, needs_email_address=False, needs_agent_reference=False, can_edit_address=False, allowed_countries=None, minutes_left=None, supports_billing_address=False, accepted_cards=None, pending_callout=None, customer=None, purchase_result=None)[source]

Describes the current state of a transaction

status

the current status of the transaction.

Type:str
reserved_at

the date and time when the transaction was reserved.

Type:datetime.datetime
purchased_at

the date and time when the transaction was purchased.

Type:datetime.datetime
trolley

the contents of the transactions trolley.

Type:Trolley
external_sale_page

the page that was rendered to the customer after the transaction was completed. This is only available if it was passed into the API at purchase time.

Type:str
languages

list of IETF language tags relevant to the transaction.

Type:list
remote_site

the remote site the transaction was reserved and purchased under.

Type:str
unreserved_orders

list of Orders <pyticketswitch.order.Order>` that failed to reserve.

Type:list
prefilled_address

some address information that should be used to prefill any customer address fields. This is primarily used on B2B accounts.

Type:Address
needs_payment_card

When True indicates that this reservation will require CardDetails as the payment method at purchase time.

Type:bool
needs_email_address

When True indicates that the customer needs to provide a valid email address at purchase time.

Type:bool
needs_agent_reference

When True indicates that an agent reference should be provided at purchase time.

Type:bool
can_edit_address

When False indicates that the prefilled customer address provided by prefilled_address should not be edited.

Type:bool
allowed_countries

list of Countries that are acceptable for the customers postal address to be from.

Type:list
minutes_left

the number of minutes left before a reservation expires.

Type:float
supports_billing_address

this transaction will support supplying a secondary billing address that is differnet to the customer address.

Type:bool
accepted_cards

acceptable debit/credit card types when API takes card details from the customer.

Type:list
pending_callout

if the transaction is mid purchase then this will hold information about how to reenter the purchase process.

Type:Callout
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Status object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a transactions state.
Returns:a new Status object populated with the data from the api.
Return type:Status

Bundles and Orders

Trolley objects, contain Bundle objects, which in turn contain Order objects, which contain TicketOrder objects. These objects describe the products being purchased and the current state of those purchases within the purchase process.

class pyticketswitch.bundle.Bundle(source_code, orders=None, description=None, total_seatprice=None, total_surcharge=None, total_send_cost=None, total=None, currency_code=None, debitor=None, terms_and_conditions=None, purchase_result=None)[source]

A collection of orders into the same backend system

source_code

the identifier of the backend system.

Type:str
orders

the orders.

Type:list
description

description of the backend system.

Type:str
total_seatprice

the total cost of the seats/tickets in the bundle.

Type:float
total_surcharge

the total additional charges for the bundle.

Type:float
total_send_cost

the total postage fee for the bundle.

Type:float
total

the total amount of money required to purchase this bundle.

Type:float
currency_code

the currency that the prices are in.

Type:str
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 None.

Type:Debitor
terms_and_conditions

supplier terms and conditions. Only availabile when requested with the optional source_info flag.

Type:str
purchase_result (

class:PurchaseResult <pyticketswitch.purchase_result. PurchaseResult>): the result of the purchase attempt for the bundle

as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Bundle object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a bundle.
Returns:a new Bundle object populated with the data from the api.
Return type:Bundle
get_event_ids()[source]

Get the event ids of the events in the bundle.

Returns:set of events IDs (str).
Return type:set
get_events()[source]

Get the events in the bundle.

Returns:list of Event objects.
Return type:list
is_purchased()[source]

Check if this bundle was successfully purchased.

Returns:if the bundle is purchased or not.
Return type:bool
class pyticketswitch.order.Order(item, event=None, performance=None, price_band_code=None, price_band_description=None, ticket_type_code=None, ticket_type_description=None, ticket_orders=None, number_of_seats=None, total_seatprice=None, total_surcharge=None, seat_request_status=None, requested_seat_ids=None, backend_purchase_reference=None, send_method=None, gross_commission=None, user_commission=None)[source]

Describes tickets for a specific event/performance.

item

the item number within the trolley. If an order is removed from the trolley it will retain it’s item number.

Type:int
event

the event the order is for.

Type:Event
performance

the performance the order is for.

Type:Performance
price_band_code

the price band identifier.

Type:str
price_band_description

the optional description for the price band

Type:str
ticket_type_code

the ticket type identifier.

Type:str
ticket_type_description

description of the ticket type.

Type:str
ticket_orders

list of TicketOrders that provide information on the specific tickets in the order.

Type:list
number_of_seats

total number of seats/tickets in the order.

Type:int
total_seatprice

total seat price of the order.

Type:float
total_surcharge

total additional surcharges for the order.

Type:float
seat_request_status

the status of requested seats. Will be filled after the order has been reserved, and None before.

Type:str
requested_seats

list of Seats requested at reservation time.

Type:list
backend_purchase_reference

a reference from the source supplier for this order. This is generally empty until the order has been successfully purchased.

Type:str
send_method

method of ticket delivery. Only present when requested.

Type:SendMethod
gross_commission (

class: Commission <pyticketswitch.commission.Commission>): predicted commission to be shared between ingresso and the partner.

user_commission (

class: Commission <pyticketswitch.commission.Commission>): predicted commission for the partner.

as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Order object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a order.
Returns:a new Order object populated with the data from the api.
Return type:Order
get_seat_ids()[source]

Get all seat ids from all TicketOrders

Returns:list of seat ids.
Return type:list
get_seats()[source]

Get all seats from all TicketOrder children.

Returns:list of Seats <pyticketswitch.seat.Seat>.
Return type:list
unique_seat_text()[source]

Get the unique seat text for all seats in an order

Returns:string combining all seat texts for the order
Return type:string
class pyticketswitch.order.TicketOrder(code, seats=None, number_of_seats=None, description=None, seatprice=None, surcharge=None, total_seatprice=None, total_surcharge=None)[source]

Describes a set of identical priced tickets.

code

the discount code.

Type:str
seats

list of seat IDs.

Type:list
number_of_seats

number of seats of this type the ticket order represents.

Type:int
description

the discount description.

Type:str
seatprice

price of individual seat in this ticket order.

Type:float
surcharge

additional surcharge added per seat in this ticket order.

Type:float
total_seatprice

seatprice for all tickets in the ticket order.

Type:float
total_surcharge

surcharge for all tickets in the ticket order.

Type:float
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

combined_price()[source]

Returns the combined seatprice and surcharge.

This method assumes that we have both a seatprice and surcharge. In the situation where are missing either a seatprice or a surcharge then we don’t have all the information to be able provide this information.

Returns:the ticket order seatprice and surcharge
Return type:float
Raises:AssertionError – It might seem like the obvious thing to do would be to assume the missing data was in fact zero and simply allow the addition to continue. However that would be somewhat dangerous when we are talking about prices, and it’s better to actually raise an exception to indicate that there was a problem with the objects data, than to inform a customer that the tickets are free or have no booking fees
classmethod from_api_data(data)[source]

Creates a new TicketOrder object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a ticket order.
Returns:a new TicketOrder object populated with the data from the api.
Return type:TicketOrder
total_combined_price()[source]

Returns the combined total seatprice and surcharge.

This method assumes that we have both a seatprice and surcharge. In the situation where are missing either a seatprice or a surcharge then we don’t have all the information to be able provide this information.

Returns:the ticket order total seatprice and total surcharge
Return type:float
Raises:AssertionError – It might seem like the obvious thing to do would be to assume the missing data was in fact zero and simply allow the addition to continue. However that would be somewhat dangerous when we are talking about prices, and it’s better to actually raise an exception to indicate that there was a problem with the objects data, than to inform a customer that the tickets are free or have no booking fees

Pricing

Any call that returns a price should also contain a description of the currency that price is in. In some cases a Currency object will be part of the object containing the price, otherwise the Client method will return a CurrencyMeta object that describes the currency for the whole response.

Event and Performance can provide estimates on the prices available ahead of actually calling Client.get_availability(). These results will be generated from cached data and should not be considered 100% accurate.

class pyticketswitch.currency.Currency(code, factor=None, places=None, number=None, pre_symbol=None, post_symbol=None)[source]

Information about the currency prices are described in.

This information can be used to create human readable prices.

code

ISO 4217 currency code.

Type:str
places

precision of decimal numbers.

Type:int
pre_symbol

a symbol to place before the digits of a price.

Type:str
post_symbol

a symbol to place after the digits of a price.

Type:str
factor

arbitary scale factor, can be used to roughly convert from one currency to another.

Type:int
number

internal identifier.

Type:int
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Convert data from the API into a native object.

Parameters:data (dict) – API data describing a currency.
Returns:the currency.
Return type:Currency
price_as_string(price)[source]

Generates a human readble string for a price.

Parameters:price (float) – a price
Returns:the price with the correct number of places with pre and post symbols attached
Return type:str

Example

>>> from pyticketswitch.currency import Currency
>>> usd = Currency('usd', pre_symbol='$', places=2)
>>> usd.price_as_string(5)
u'$5.00'
>>> usd.price_as_string(12.34567)
u'$12.34'
class pyticketswitch.cost_range.CostRange(valid_quantities=None, max_surcharge=None, max_seatprice=None, min_surcharge=None, min_seatprice=None, allows_singles=True, currency=None, best_value_offer=None, max_saving_offer=None, min_cost_offer=None, top_price_offer=None)[source]

CostRange gives summarized pricing for events and performances.

This information is returned from cached data collected when making actual calls to the backend system, and should not be considered accurate.

valid_quantities

list of valid quanities available for purchase.

Type:list
min_seatprice

the minimum cost per seat the customer might be expected to pay.

Type:float
max_seatprice

the maximum cost per seat the customer might be expected to pay.

Type:float
min_surcharge

the minimum surcharge per seat the customer might be expected to pay.

Type:float
max_surcharge

the maximum surcharge per seat the customer might be expected to pay.

Type:float
currency

currency the cost range and offer prices are in.

Type:str
best_value_offer

offer with the highest percentage saving.

Type:Offer
max_saving_offer

offer with the highest absolute saving.

Type:Offer
min_cost_offer

offer with the lowest cost.

Type:Offer
top_price_offer

offer with the top price.

Type:Offer
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new CostRange object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a cost range.
Returns:a new CostRange object populated with the data from the api.
Return type:CostRange
class pyticketswitch.cost_range.CostRangeDetails(ticket_type_code, price_band_code, cost_range, ticket_type_description=None, price_band_description=None, cost_range_no_singles=None, **kwargs)[source]

Summarizes pricing by ticket types and price bands for an event/performance

This information is returned from cached data collected when making actual calls to the backend system, and should not be considered accurate.

ticket_type_code

identifier for the ticket type.

Type:str
price_band_code

identifier for the price band.

Type:str
cost_range

summary of pricing distribution for this ticket type/price band.

Type:CostRange
cost_range_no_singles

summary of pricing distribution for this ticket type/price band when not leaving any singles.

Type:CostRange
ticket_type_description

description of the ticket type.

Type:str
price_band_description

description of the price band.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

class pyticketswitch.offer.Offer(seatprice=None, surcharge=None, original_seatprice=None, original_surcharge=None, absolute_saving=None, percentage_saving=None)[source]

Describes a reduction in price.

seatprice

the price per seat/ticket.

Type:float
surcharge

the additional charges per seat/ticket.

Type:float
original_seatprice

the original price per seat/ticket.

Type:float
original_surcharge

the original additional charges per seat/ticket.

Type:float
absolute_saving

the amount of money saved by this offer.

Type:float
percentage_saving

the amount of money saved by this offer, as a percentage of the original price.

Type:float
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Offer object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns an offer.
Returns:a new Offer object populated with the data from the api.
Return type:Offer

Event Details

These are additional details that are directly related to Event

class pyticketswitch.card_type.CardType(code=None, description=None)[source]

Type of card that will be accepted during the payment process

code

identifier for the card type.

Type:str
description

human readable description of the card type.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

class pyticketswitch.field.Field(name, label, data)[source]

Describes a custom field for an event

name

the name of the field.

Type:str
label

human readble name of the field.

Type:str
data

the field data.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Field object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a field.
Returns:a new Field object populated with the data from the api.
Return type:Field
class pyticketswitch.media.Media(caption=None, caption_html=None, name=None, url=None, secure=None, width=0, height=0)[source]

Describes some event media asset

caption

caption in plain text describing the asset.

Type:str
caption_html

caption as html describing the asset.

Type:str
name

name of the asset.

Type:str
url

url for the asset.

Type:str
secure

indicates if the assert url is secure or not.

Type:bool
width

width of the asset in pixels. Only present on the video

Type:int
height

height of the asset in pixels. Only present on the video asset.

Type:int
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Media object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a media asset.
Returns:a new Media object populated with the data from the api.
Return type:Media
class pyticketswitch.review.Review(body=None, date_time=None, star_rating=None, lang=None, title=None, is_user=False, author=None, url=None)[source]

User or Critic evaluation of an event.

body

review test.

Type:str
date_time

date and time of the review.

Type:datetime.datetime
star_rating

rating on a scale of 1-5, with 1 being the lowest rating and 5 being the highest rating.

Type:int
language

the IETF language tag for the review.

Type:str
title

a review title if available.

Type:str
is_user

the review was made by a user not a critic.

Type:bool
author

the authors name.

Type:str
url

the original url.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Review object from ticketswitch API data.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a review.
Returns:a new Review object populated with the data from the api.
Return type:Review

Seats

class pyticketswitch.seat.SeatBlock(length, seats=None)[source]

Describes a set of contiguous seats.

length

the number of seats in the block.

Type:int
seats

list of Seats in the block.

Type:list
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(block, row_id=None, separator='', restricted_view_seats=None, seats_by_text_message=None)[source]

Creates a new SeatBlock object from API data from ticketswitch.

Parameters:
  • block (list) – the part of the response from a ticketswitch API call that concerns a seat block.
  • row_id (str) – the component of the seat ID corresponding to the row
  • separator (str) – the string separating row and column in the id
  • restricted_view_seats (list) – seat IDs that have restricted view
  • seats_by_text_message (dict) – a mapping of seat text messages to seat IDs
Returns:

a new SeatBlock object populated with the data from the api.

Return type:

SeatBlock

class pyticketswitch.seat.Seat(id_=None, column=None, row=None, is_restricted=False, seat_text_code=None, seat_text=None, separator=None, barcode=None)[source]

Describes a seat in a venue.

id

the identifier for the seat.

Type:str
column

the column of the seat.

Type:str
row

the row of the seat.

Type:str
separator

characters that should be used to seperate the column and row when presenting seat information.

Type:str
is_restricted

indicates that the seat has a restricted view.

Type:bool
seat_text_code

code indicating text that should be displayed with the seat when preseting seat information.

Type:str
seat_text

readable explanation of the seats description

Type:str
barcode

barcode specific to this seat. Only available when supported by the backend system.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Seat object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a seat.
Returns:a new Seat object populated with the data from the api.
Return type:Seat

Payment Details

class pyticketswitch.payment_methods.PaymentMethod[source]

Abstract base class for payment methods

as_api_parameters()[source]

Generate keyword arguments suitable for consumption by the ticketswitch API

Returns:dictionary of keyword parameters to pass to the API call.
Return type:dict
class pyticketswitch.payment_methods.CardDetails(card_number, expiry_month=None, expiry_year=None, start_month=None, start_year=None, ccv2=None, issue_number=None, billing_address=None, return_url=None, return_token=None, user_agent=None, accept=None, remote_site=None)[source]

Credit card details

This should never be returned by the API and is only used for supplying card details to the purchase call.

Implements PaymentMethod.

card_number

the long credit card number.

Type:str
expiry_month

the month the card expires in. Defaults to None.

Type:int
expiry_year

the year the card expires in. defaults to None.

Type:int
start_month

the month the card expires in. Defaults to None.

Type:int
start_year

the year the card expires in. None.

Type:int
ccv2

credit card security code. Defaults to None.

Type:str
issue_number

issue number of the card. Defaults to None.

Type:str
billing_address

used when the customer wishes to use an alternate billing address. when not specified the customer address will be used.

Type:Address
return_url

some card debitors may decide that they need to redirect the user to a third party for verification (for example 3d secure). These parties need a location to return a customer to. When available, it’s recomended to provide it. In the situation where a return url is required but not provided, then the payment will fail.

Type:str
return_token

a unique token that can be used by you to identify when a card debitor returns to you.

Type:str
user_agent

the customer’s browser’s User-Agent header. only nessicary when providing a return url.

Type:str
accept

the customer’s browser’s Accept header.

Type:str
remote_site

the remote site’s domain. must match the domain of the return_url.

Type:str
as_api_parameters()[source]

Generates a dictionary of parameters to be passed back to the API.

Returns:a set of parameters describing the card details to the API.
Return type:dict
class pyticketswitch.payment_methods.CiderDetails(data, system_codes)[source]

For use with multiple payment tokens and details

Can be used to provide payment tokens and details directly to the API at purchase time, avoiding a callout/callback cycle.

Implements PaymentMethod.

data

dictionary of payment tokens and details

Type:dict
system_codes

a list of systems for which payment is being made

Type:list
as_api_parameters()[source]

Generate API keyword args for these details.

Returns:the cider debitor details in the format the API can use.
Return type:dict
class pyticketswitch.payment_methods.RedirectionDetails(token, url, user_agent, accept, remote_site)[source]

Information that specifies where a customer will be returned to after being redirected to an external payment provider.

Implements PaymentMethod.

token

a unique token that can be used by you to identify when this callout returns to your website.

Type:str
url

the URL that the payment provider should redirect back to on success/failure of the customers payment.

Type:str
user_agent

the customer’s browser’s User-Agent header.

Type:str
accept

the customer’s browser’s Accept header.

Type:str
remote_site

the remote site’s domain must match the domain of the return_url.

Type:str
as_api_parameters()[source]

Generate API keyword args for these details.

Returns:the redirection details in a format the API will understand.
Return type:dict
class pyticketswitch.payment_methods.StripeDetails(tokens)[source]

For use with self generated stripe tokens

Can be used to provide stripe tokens directly to the API at purchase time avoiding a callout/callback cycle.

Implements PaymentMethod.

tokens

dictionary of stripe card tokens indexed on bundle source code. If there are multiple bundles in the trolley, then a unique stripe token must be provided for each of the bundles you wish to purchase with stripe.

Type:dict
as_api_parameters()[source]

Generate API keyword args for these details.

Returns:the stripe details in a format the API will understand.
Return type:dict

Callouts

class pyticketswitch.callout.Callout(code=None, description=None, total=None, typ=None, destination=None, parameters=None, integration_data=None, debitor=None, currency_code=None, return_token=None)[source]

Information about a redirection required by a 3rd party the payment provider.

code

the identifier for the source system of the bundle this callout will be paying for.

Type:str
description

the human readable description for the source system.

total

the total amount of money that will be payable.

Type:float
type

the HTTP method that should be used to send the customer to the destination.

Type:str
destination

the destination url to send your user to.

Type:str
parameters

dictionary of key value pairs that the 3rd party is expecting as query string parameters or form parameters.

Type:collections.OrderedDict
html

a blob of HTML that can be rendered to produce either the required redirect or the form to continue with the transaction.

Type:str
integration_data

data relevant to the debitor that the customer will be redirected to. This may provide a opertunity to integrate directly. Consult documentation for more details.

Type:dict
debitor

the debitor information that can be used for a front end integration.

Type:Debitor
return_token

return token specified in the last purchase or callback call.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Callout object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a callout.
Returns:a new Callout object populated with the data from the api.
Return type:Callout
class pyticketswitch.callout.Integration(typ, amount=None, base_amount=None, currency=None, data=None)[source]

Information to use when integrating payment methods into clients.

type

the debitor type.

Type:str
amount

the amount to be debited.

Type:float
amount_base

the precise amount. see currency for places.

Type:int
currency

the currency code.

Type:str
data

debitor specific information.

Type:dict
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Integration object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns the integration.
Returns:a new Integration object populated with the data from the api.
Return type:Integration

Meta Objects

class pyticketswitch.event.EventMeta(page_length=None, page_number=None, pages_remaining=None, total_results=None, results_remaining=None, *args, **kwargs)[source]

Meta information about a set of events

currencies

dictionary of Currency) objects indexed on currency code.

Type:dict
default_currency_code

unless other wise specified all prices in the related response will be in this currency.

Type:str
desired_currency_code

the currency that the user account is expecting. Useful for conversions.

Type:str
page_length

the number of items per page.

Type:int
page_number

the current page.

Type:int
pages_remaining

the number of pages remaining.

Type:int
results_remaining

the total number of remaining results after the current page.

Type:int
total_results

the total number of results.

Type:int
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data, result_key=None, *args, **kwargs)

Convert data from the API into a native object.

Parameters:data (dict) – API data describing the currencies of a related object.
Returns:
the
currency meta data.
Return type:CurrencyMeta
get_currency(code=None)

Get the Currency object for the given code.

Parameters:code (str, optional) – ISO 4217 currency code.
Returns:The currency for the given code.

If no code is specified, return the default currency as specified by CurrencyMeta.default_currency_code.

If no default currency is specified return None.

Return type:Currency
get_desired_currency()

Get the Currency object for the desired currency.

Returns:The currency for the desired currency.

If no desired currency is specified return None.

Return type:Currency
is_paginated()

Indicates that the response is paginated

Returns:True when the response is omitting results due to pagination otherwise :obj:False
Return type:bool
class pyticketswitch.performance.PerformanceMeta(auto_select=False, has_names=False, *args, **kwargs)[source]

PerformanceMeta contains meta information about a list of Performances.

auto_select

indicates that the performance list will contain only one performance and this performance should be automatically selected for the customer. See Events that don’t need performance selection for more information.

Type:bool
has_names

(bool): indicates that the related performances have names

as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new PerformanceMeta object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns some performance meta data.
Returns:a new PerformanceMeta object populated with the data from the api.
Return type:PerformanceMeta
get_currency(code=None)

Get the Currency object for the given code.

Parameters:code (str, optional) – ISO 4217 currency code.
Returns:The currency for the given code.

If no code is specified, return the default currency as specified by CurrencyMeta.default_currency_code.

If no default currency is specified return None.

Return type:Currency
get_desired_currency()

Get the Currency object for the desired currency.

Returns:The currency for the desired currency.

If no desired currency is specified return None.

Return type:Currency
is_paginated()

Indicates that the response is paginated

Returns:True when the response is omitting results due to pagination otherwise :obj:False
Return type:bool
class pyticketswitch.availability.AvailabilityMeta(contiguous_seat_selection_only=True, currency=None, valid_quantities=None, max_bundle_size=None, backend_is_down=False, backend_is_broken=False, backend_throttle_failed=False, *args, **kwargs)[source]

Meta data about an availability response

contiguous_seat_selection_only

indicates that the backend system will only allow seats to be selected that are in a contiguous line.

Type:bool
valid_quantities

list of valid number of tickets available for selection.

Type:list
max_bundle_size

maximum bundle size for this event. If it is None then there is no maximum size.

Type:int
currencies

dictionary of Currency) objects indexed on currency code.

Type:dict
default_currency_code

unless other wise specified all prices in the related response will be in this currency.

Type:str
desired_currency_code

the currency that the user account is expecting. Useful for conversions.

Type:str
backend_is_broken

indicates that the backend system is presently marked as broken.

Type:bool
backend_is_down

indicates that we are not currently able to contact the backend system.

Type:bool
backend_throttle_failed

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.

Type:bool
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new AvailabilityMeta object from API data from ticketswitch.

Parameters:data (dict) – the whole response from the availability call.
Returns:a new AvailabilityMeta object populated with the data from the api.
Return type:AvailabilityMeta
get_currency(code=None)

Get the Currency object for the given code.

Parameters:code (str, optional) – ISO 4217 currency code.
Returns:The currency for the given code.

If no code is specified, return the default currency as specified by CurrencyMeta.default_currency_code.

If no default currency is specified return None.

Return type:Currency
get_desired_currency()

Get the Currency object for the desired currency.

Returns:The currency for the desired currency.

If no desired currency is specified return None.

Return type:Currency
class pyticketswitch.currency.CurrencyMeta(currencies, default_currency_code=None, desired_currency_code=None)[source]

Currency information for another object.

currencies

Currency) objects indexed on currency code.

Type:dict
default_currency_code

unless other wise specified all prices in the related response will be in this currency.

Type:str
desired_currency_code

the currency that the user account is expecting. Useful for conversions.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Convert data from the API into a native object.

Parameters:data (dict) – API data describing the currencies of a related object.
Returns:
the
currency meta data.
Return type:CurrencyMeta
get_currency(code=None)[source]

Get the Currency object for the given code.

Parameters:code (str, optional) – ISO 4217 currency code.
Returns:The currency for the given code.

If no code is specified, return the default currency as specified by CurrencyMeta.default_currency_code.

If no default currency is specified return None.

Return type:Currency
get_desired_currency()[source]

Get the Currency object for the desired currency.

Returns:The currency for the desired currency.

If no desired currency is specified return None.

Return type:Currency
class pyticketswitch.performance.PerformanceMeta(auto_select=False, has_names=False, *args, **kwargs)[source]

PerformanceMeta contains meta information about a list of Performances.

auto_select

indicates that the performance list will contain only one performance and this performance should be automatically selected for the customer. See Events that don’t need performance selection for more information.

Type:bool
has_names

(bool): indicates that the related performances have names

as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new PerformanceMeta object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns some performance meta data.
Returns:a new PerformanceMeta object populated with the data from the api.
Return type:PerformanceMeta
get_currency(code=None)

Get the Currency object for the given code.

Parameters:code (str, optional) – ISO 4217 currency code.
Returns:The currency for the given code.

If no code is specified, return the default currency as specified by CurrencyMeta.default_currency_code.

If no default currency is specified return None.

Return type:Currency
get_desired_currency()

Get the Currency object for the desired currency.

Returns:The currency for the desired currency.

If no desired currency is specified return None.

Return type:Currency
is_paginated()

Indicates that the response is paginated

Returns:True when the response is omitting results due to pagination otherwise :obj:False
Return type:bool

Utilities

pyticketswitch.utils.bitmask_to_boolean_list(mask)[source]

Convert a bitmask to boolean list

Parameters:mask (int) – the mask returned by the API
Returns:list of booleans.
Return type:list
pyticketswitch.utils.bitmask_to_numbered_list(mask)[source]

Convert a bitmask to a numbered list

Parameters:mask (int) – the mask returned by the API
Returns:list of integers
Return type:list
pyticketswitch.utils.date_range_str(start_date, end_date)[source]

Convert a set of dates to string readable by the API

Parameters:
Returns:

a date range in the format of “YYYYMMDD:YYYYMMDD”.

Missing either or both dates is acceptable and will return “YYYYMMDD:”, “:YYYYMMDD”, “:”.

Return type:

str

Raises:

InvalidParametersError – when a start_date or end_date is specified and it is not a datetime.date object.

pyticketswitch.utils.deprecated(func)[source]

Mark a function as deprecated and raise a warning

This decorator is used to mark functions as deprecated. It will result in a warning being emitted when the function is called.

Parameters:func – the function to be wrapped
Returns:the wrapped function that raises a warning
pyticketswitch.utils.deprecation_warning(message, stacklevel=2)[source]
pyticketswitch.utils.filter_none_from_parameters(params)[source]

Removes parameters whos value is :obj:None

Parameters:params (dict) – dictionary of parameters to be passed to the API.
Returns:the original parameters with any parameters whos value was None removed.
Return type:dict
pyticketswitch.utils.get_price(data, key)[source]

Extracts a price as a float from some data

Parameters:
  • data (dict) – the data containing the price
  • key (str) – the key of the target price.
Returns:

the price as a float.

When the dictionary is missing the requested key, returns None

Return type:

float

pyticketswitch.utils.isostr_to_datetime(date_str)[source]

Convert an iso datetime string to a datetime.datetime object.

Parameters:date_str (str) – the string to convert.
Returns:
the python representation of the date
and time.
Return type:datetime.datetime
Raises:ValueError – when the date_str is empty or None.
pyticketswitch.utils.specific_dates_from_api_data(dates)[source]
pyticketswitch.utils.yyyymmdd_to_date(date_str)[source]

Convert a YYYYMMDDD formated date to python datetime.date object.

Parameters:date_str (str) – the string to convert.
Returns:the python representation of the date.
Return type:datetime.date
Raises:ValueError – when the date_str is empty or None.

Mixins

class pyticketswitch.mixins.JSONMixin[source]

Adds json encoding functionality to objects.

__dict__ = dict_proxy({'__module__': 'pyticketswitch.mixins', '__jsondict__': <function __jsondict__>, 'as_dict_for_json': <function as_dict_for_json>, '__dict__': <attribute '__dict__' of 'JSONMixin' objects>, '__weakref__': <attribute '__weakref__' of 'JSONMixin' objects>, '__doc__': 'Adds json encoding functionality to objects.', 'as_json': <function as_json>})
__jsondict__(hide_none=True, hide_empty=True)[source]
__module__ = 'pyticketswitch.mixins'
__weakref__

list of weak references to the object (if defined)

as_dict_for_json(hide_none=True, hide_empty=True)[source]

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)[source]

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

class pyticketswitch.mixins.PaginationMixin(page_length=None, page_number=None, pages_remaining=None, total_results=None, results_remaining=None, *args, **kwargs)[source]

Adds pagination information to a responses meta data.

page_length

the number of items per page.

Type:int
page_number

the current page.

Type:int
pages_remaining

the number of pages remaining.

Type:int
results_remaining

the total number of remaining results after the current page.

Type:int
total_results

the total number of results.

Type:int
__dict__ = dict_proxy({'__module__': 'pyticketswitch.mixins', 'from_api_data': <classmethod object>, '__weakref__': <attribute '__weakref__' of 'PaginationMixin' objects>, '__dict__': <attribute '__dict__' of 'PaginationMixin' objects>, 'is_paginated': <function is_paginated>, '__doc__': 'Adds pagination information to a responses meta data.\n\n Attributes:\n page_length (int): the number of items per page.\n page_number (int): the current page.\n pages_remaining (int): the number of pages remaining.\n results_remaining (int): the total number of remaining results after\n the current page.\n total_results (int): the total number of results.\n\n ', '__init__': <function __init__>})
__init__(page_length=None, page_number=None, pages_remaining=None, total_results=None, results_remaining=None, *args, **kwargs)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'pyticketswitch.mixins'
__weakref__

list of weak references to the object (if defined)

classmethod from_api_data(data, result_key=None, *args, **kwargs)[source]
is_paginated()[source]

Indicates that the response is paginated

Returns:True when the response is omitting results due to pagination otherwise :obj:False
Return type:bool
class pyticketswitch.mixins.SeatPricingMixin(seatprice=None, surcharge=None, non_offer_seatprice=None, non_offer_surcharge=None, *args, **kwargs)[source]

Adds seat pricing to an object

seatprice

the price per seat/ticket.

Type:float
surcharge

additional charges per seat/ticket.

Type:float
non_offer_seatprice

the original price per seat/ticket when not on offer.

Type:float
non_offer_surcharge

the original additional charges per seat/ticket when not on offer.

Type:float
__dict__ = dict_proxy({'kwargs_from_api_data': <staticmethod object>, '__module__': 'pyticketswitch.mixins', '__dict__': <attribute '__dict__' of 'SeatPricingMixin' objects>, 'combined_price': <function combined_price>, '__weakref__': <attribute '__weakref__' of 'SeatPricingMixin' objects>, 'non_offer_combined_price': <function non_offer_combined_price>, '__init__': <function __init__>, '__doc__': 'Adds seat pricing to an object\n\n Attributes:\n seatprice (float): the price per seat/ticket.\n surcharge (float): additional charges per seat/ticket.\n non_offer_seatprice (float): the original price per seat/ticket when\n not on offer.\n non_offer_surcharge (float): the original additional charges per\n seat/ticket when not on offer.\n '})
__init__(seatprice=None, surcharge=None, non_offer_seatprice=None, non_offer_surcharge=None, *args, **kwargs)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

__module__ = 'pyticketswitch.mixins'
__weakref__

list of weak references to the object (if defined)

combined_price()[source]

Returns the combined seatprice and surcharge.

This method assumes that we have both a seatprice and surcharge. In the situation where are missing either a seatprice or a surcharge then we don’t have all the information to be able provide this information.

Returns:the combined seatprice and surcharge
Return type:float
Raises:AssertionError – It might seem like the obvious thing to do would be to assume the missing data was in fact zero and simply allow the addition to continue. However that would be somewhat dangerous when we are talking about prices, and it’s better to actually raise an exception to indicate that there was a problem with the objects data, than to inform a customer that the tickets are free or have no booking fees
static kwargs_from_api_data(data)[source]
non_offer_combined_price()[source]

Returns the combined non offer seatprice and surcharge.

This method assumes that we have both a seatprice and surcharge. In the situation where are missing either a seatprice or a surcharge then we don’t have all the information to be able provide this information.

Returns:the combined seatprice and surcharge
Return type:float
Raises:AssertionError – It might seem like the obvious thing to do would be to assume the missing data was in fact zero and simply allow the addition to continue. However that would be somewhat dangerous when we are talking about prices, and it’s better to actually raise an exception to indicate that there was a problem with the objects data, than to inform a customer that the tickets are free or have no booking fees

Exceptions

exception pyticketswitch.exceptions.APIError(msg, code=None, response=None, *args, **kwargs)[source]
exception pyticketswitch.exceptions.AuthenticationError(msg, code=None, response=None, *args, **kwargs)[source]
exception pyticketswitch.exceptions.BackendBrokenError[source]
exception pyticketswitch.exceptions.BackendDownError[source]
exception pyticketswitch.exceptions.BackendError[source]
exception pyticketswitch.exceptions.BackendThrottleError[source]
exception pyticketswitch.exceptions.CallbackGoneError(msg, code=None, response=None, *args, **kwargs)[source]
exception pyticketswitch.exceptions.IntegrityError(message, data, *args)[source]
exception pyticketswitch.exceptions.InvalidGeoParameters[source]
exception pyticketswitch.exceptions.InvalidParametersError[source]
exception pyticketswitch.exceptions.InvalidResponseError[source]
exception pyticketswitch.exceptions.OrderUnavailableError(msg, reservation=None, meta=None, *args, **kwargs)[source]
exception pyticketswitch.exceptions.PyticketswitchError[source]

Miscellaneous

class pyticketswitch.address.Address(lines=None, country_code=None, county=None, email=None, home_phone=None, post_code=None, town=None, work_phone=None)[source]

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.

lines

list of address lines.

Type:list
town

town for the address.

Type:str
county

the county or region of the address.

Type:str
country_code

ISO 3166-1 country code.

Type:str
post_code

post or ZIP code for the address.

Type:str
email

a contact email address.

Type:str
home_phone

a contact home phone number.

Type:str
work_phone

a contact work phone number.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Address object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns an address.
Returns:a new Address object populated with the data from the api.
Return type:Address
class pyticketswitch.country.Country(code, description=None)[source]

Represents a country

code

ISO 3166-1 country code.

Type:str
description

a human readable name for the country.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Country object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a country.
Returns:a new Country object populated with the data from the api.
Return type:Country
class pyticketswitch.user.User(id_, name=None, country=None, sub_user=None, is_b2b=False, statement_descriptor=None, backend_group=None, content_group=None)[source]

Describes a user of the API

id

the user identifier.

Type:str
name

human readable name.

Type:str
country

ISO 3166-1 country code.

Type:str
sub_user

the identifier of the sub user.

Type:str
is_b2b

indicates that the account is a b2b account.

Type:bool
statement_descriptor

what will appear on a customers bank statement when ingresso takes the payment.

Type:str
backend_group

what product group a user belongs to. Users in the same backend_group will see the same products.

Type:str
content_group

what content group a user belongs to. Users in the same content_group will see the same textual and graphical content.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new User object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a user.
Returns:a new User object populated with the data from the api.
Return type:User
class pyticketswitch.customer.Customer(first_name, last_name, address_lines, country_code, title=None, initials=None, suffix=None, email=None, post_code=None, town=None, county=None, country=None, phone=None, home_phone=None, work_phone=None, agent_reference=None, supplier_can_use_data=False, user_can_use_data=False, world_can_use_data=False, first_name_latin=None, last_name_latin=None, address_lines_latin=None, title_latin=None, initials_latin=None, suffix_latin=None, post_code_latin=None, town_latin=None, county_latin=None, country_latin=None, **kwargs)[source]

Describes a cutomer to ticketswitch.

first_name

customers first name.

Type:str
last_name

customers last name.

Type:str
address_lines

list of address lines, at least one address line is required.

Type:list
country_code

ISO 3166-1 country code that the customer is living in.

Type:str
title

customer title.

Type:str
initials

customer initials.

Type:str
suffix

customer name suffix.

Type:str
email

email address for contacting the customer.

Type:str
post_code

post or ZIP code for the customers address.

Type:str
town

town for the customers address.

Type:str
county

the county or region of the customers address.

Type:str
country

the country as a string for the customers address.

Type:str
phone

a contact phone number for the user.

Type:str
home_phone

the customers home phone number.

Type:str
work_phone

the customers work phone number.

Type:str
agent_reference

agent reference for the customer.

Type:str
supplier_can_use_data

indicates that the supplier of the tickets is allowed to access and use this data.

Type:bool
user_can_use_data

indicates that the user (you) can access and use this data.

Type:bool
world_can_use_data

indicates that pretty much anyone is allowed to access and use this data.

Type:bool
first_name_latin

first name in latin characters.

Type:str
last_name_latin

last name in latin characters.

Type:str
address_lines_latin

list of str address lines in latin characters.

Type:list
title_latin

title in latin characters

Type:str
initials_latin

initials in latin characters.

Type:str
suffix_latin

suffix in latin characters.

Type:str
post_code_latin

post_code in latin characters.

Type:str
town_latin

town in latin characters.

Type:str
county_latin

county in latin characters.

Type:str
country_latin

country in latin characters.

Type:str
kwargs

arbitrary keyword arguments to store along with this customer object.

Type:dict
as_api_parameters()[source]

Generates a dictionary of parameters to be passed back to the API.

Returns:a set of parameters describing the customer to the API.
Return type:dict

Note

the latin_* attributes are not passed to the API as they are generated internally. As such there is no need to provided them when creating a Customer for API consumption.

as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

classmethod from_api_data(data)[source]

Creates a new Customer object from API data from ticketswitch.

Parameters:data (dict) – the part of the response from a ticketswitch API call that concerns a customer.
Returns:a new Customer object populated with the data from the api.
Return type:Customer
class pyticketswitch.debitor.Debitor(typ=None, name=None, description=None, integration_data=None, aggregation_key=None)[source]

Information about a 3rd party that will take payment from your customer.

This information is primarily used for bypassing callouts an integrating directly with payment providers on the front end.

When your account is set up to sell on credit (i.e. you are always taking payment from the customer in your application directly), this information will not be present, and it should not be relevant.

When the source system is taking payment this information will not be present.

When debitor information is not present or you are not front end integrating you should refer to the Reservation.needs_payment_card, Reservation.needs_email_address, and Reservation.needs_agent_reference attributes as to what information you need to pass back to the API for purchasing tickets.

Regardless of the debitor it’s advisable to implement the full purchase/callout/callback process in the event that your front end integration goes awry.

See front end integrations for more information

type

all debitors with the same type can be assumed to integrate in the same manor, however their parameters and integration data might be different.

Type:str
name

name of the specific implementation of the debitor.

Type:str
description

human readable description of the debitor.

Type:str
integration_data

data used to do front end integrations. For the format of this data please consult the documentation for the relevant debitor type.

Type:dict
aggregation_key

a key used to identify if debitors are the same for purposes of payment aggregation between bundles

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str

class pyticketswitch.card_type.CardType(code=None, description=None)[source]

Type of card that will be accepted during the payment process

code

identifier for the card type.

Type:str
description

human readable description of the card type.

Type:str
as_dict_for_json(hide_none=True, hide_empty=True)

Generate a json serialisable dictionary from the object

Dates are changed to strings in ISO 8601 format.

Lists children are recursively serialised.

Dictionary values are recursively serialised, keys are left as is.

Objects that implement __jsondict__ return the result of calling __jsondict__ on the object.

Parameters:
  • hide_none (bool, optional) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool, optional) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
Returns:

a dictionary representation of the object.

Return type:

dict

as_json(hide_none=True, hide_empty=True, **kwargs)

Generate a json represetation of an object.

Parameters:
  • hide_none (bool) – when True the returned dictionary will not include attributes who’s value is None.
  • hide_empty (bool) – when True the returned dictionary will not include attributes who’s value is iterable and has a length of zero.
  • **kwargs – passed to json.dumps().
Returns:

a json representation of an object

Return type:

str