Reference#

i_need_a_res#

I Need A Res.

exception i_need_a_res.LocationError#

A custom exception for invalid locations.

i_need_a_res.convert_book_date_to_datetime(book_date)#

Converts human-friendly date options into a datetime object.

Parameters:

book_date (str) – date to book reservation

Returns:

A datetime object representation of the book date.

Return type:

datetime

geo#

Utils for geolocations.

class i_need_a_res.geo.GeoPoint(latitude, longitude)#

Dataclass for geolocations.

Parameters:

  • latitude (float) – latitude of location

  • longitude (float) – longitude of location

latitude: float#

latitude of location

longitude: float#

longitude of location

i_need_a_res.geo.USER_AGENT = "<module 'i_need_a_res' from '/home/docs/checkouts/readthedocs.org/user_builds/i-need-a-res/envs/latest/lib/python3.10/site-packages/i_need_a_res/__init__.py'>"#

app name for querying the Nominatim API.

Type:

str

i_need_a_res.geo.convert_to_geopoint(latitude, longitude)#

Helper function to convert string lat & long to a GeoPoint.

Parameters:

  • latitude (str) – string latitude

  • longitude (str) – string longitude

Returns:

GeoPoint from strings.

Return type:

GeoPoint

i_need_a_res.geo.get_city_geopoint(city)#

Function to get the latitude and longitude from a str representing a city.

Parameters:

city (str) – name of the city

Returns:

GeoPoint of the city center

Return type:

GeoPoint

providers#

Reservation providers.

providers.opentable#

Module for OpenTable-specific handling of reservations.

i_need_a_res.providers.opentable.get_reservation(api_key, auth_token, city, search_day, party_size)#

Stub function to return reservations.

Parameters:

  • api_key (str) –

  • auth_token (str) –

  • city (str) –

  • search_day (datetime) –

  • party_size (int) –

Return type:

ReservationSlot

providers.resy#

Module for Resy-specific handling of reservations.

i_need_a_res.providers.resy.get_reservation(api_key, auth_token, city, search_day, party_size)#

Function to orchestrate getting a random reservation.

Parameters:

  • api_key (str) – Resy API key

  • auth_token (str) – Resy user JWT token

  • city (str) – city to search for reservations in

  • search_day (datetime) – day to search reservations for

  • party_size (int) – size of the party

Returns:

A ReservationSlot object

Example

>>> ReservationSlot("The French Laundry", datetime(2023, 01, 01, 19, 00), "some_token_value")

Raises:

LocationError – if city is not a supported Resy city.

Return type:

ReservationSlot

providers.resy.resy_client#

Module for Resy API client.

Todo: * add POST reservation routes for v1.0.0 * add rest of GET routes (eventually)

i_need_a_res.providers.resy.resy_client.RESY_API_URL = 'https://api.resy.com'#

Base URL for the Resy API

Type:

str

class i_need_a_res.providers.resy.resy_client.ResyAuth(api_key, auth_token)#

Attaches Resy-required auth headers to the given Request or Session object.

Parameters:

  • api_key (str) –

  • auth_token (str) –

api_key#

Resy API key

Type:

str

auth_token#

Resy user JWT token

Type:

str

api_key#

Resy API key

auth_token#

Resy user JWT token

class i_need_a_res.providers.resy.resy_client.ResyClient(api_key, auth_token)#

Class for Resy API client.

Parameters:

  • api_key (str) –

  • auth_token (str) –

sesssion#

Session for requests to the Resy API

Type:

requests.sessions.Session

session.auth#

Authorization information for the Resy API, persisting across requests.

Type:

requests.sessions.Session.auth

get_venues(geolocation, search_day, party_size)#

Method for returning all venues on Resy with available reservation slots for the given date, time, city, and party size.

Parameters:

  • geolocation (GeoPoint) – NamedTuple of the city’s center coordinates

  • search_day (datetime) – Day to search reservations for.

  • party_size (int) – Size of party.

Returns:

A list of ResyVenue objects.

Return type:

List[Venue]

providers.models#

Data models for provider-related classes.

class i_need_a_res.providers.models.ReservationProvider(value)#

Data class to store available reservation providers.

Currently, only Resy and OpenTable are supported.

class i_need_a_res.providers.models.ReservationSlot(restaurant_name, time, token, reservation_provider)#

Immutable data structure for reservation slots.

Parameters:

  • restaurant_name (str) – Name of the restaurant

  • time (datetime) – Time of reservation

  • token (str) – Reservation provider token

  • reservation_provider (ReservationProvider) – Name of provider

reservation_provider: ReservationProvider#

Name of provider

restaurant_name: str#

Name of the restaurant

time: datetime#

Time of reservation

token: str#

Reservation provider token

class i_need_a_res.providers.models.Venue(venue_id, name, cuisine, price_range, rating, coordinates, reservation_slots)#

Mutable data structure for venues.

Parameters:

  • venue_id (int) –

  • name (str) –

  • cuisine (str) –

  • price_range (int) –

  • rating (float) –

  • coordinates (GeoPoint) –

  • reservation_slots (List[ReservationSlot]) –

venue_id#

unique ID of the venue

Type:

int

name#

name of the venue

Type:

str

cuisine#

type of food the venue serves

Type:

str

price_range#

price range of the venue, from 1 to 4.

Type:

int

rating#

rating of the venue from reviews

Type:

float

coordinates#

latitude and longitude of the venue.

Type:

i_need_a_res.geo.GeoPoint

reservation_slots#

a list of ReservationSlot objects representing the available slots.

Type:

List[i_need_a_res.providers.models.ReservationSlot]