wetherspoons-api-python 1.0.0

A Python package for accessing JD Wetherspoon's venue and menu data

Wetherspoons API - Python

A Python package for accessing JD Wetherspoon's venue and menu data, including drink information with pricing and alcohol unit calculations.

This is a Python port of the original TypeScript package by Joss Bird.

Installation

pip install wetherspoons-api-python

Or for development:

git clone https://github.com/slack2450/wetherspoons-api.git
cd wetherspoons-api-python
pip install -e .

Features

• 🏪 Fetch all Wetherspoons venues
• 📍 Get detailed venue information
• 🍺 Access venue menus and drinks
• 💰 Calculate price per unit (PPU) for alcoholic beverages
• ✅ Type-safe with Pydantic validation
• 🔄 Automatic handling of different portion sizes

Usage

Get All Venues

from wetherspoons_api import venues

all_venues = venues()
print(all_venues)
# [
#   HighLevelVenue(franchise='lloyds', id=123, is_closed=False, 
#                 name='The Moon Under Water', venue_ref=456),
#   ...
# ]

Get Venue Details

from wetherspoons_api import venues, get_venue

all_venues = venues()
venue = all_venues[0]
details = get_venue(venue)

print(details)
# DetailedVenue(can_place_order=True, franchise='lloyds', id=123,
#              name='The Moon Under Water', sales_areas=[{'id': 789}],
#              venue_can_order=True, venue_ref=456)

Get Drinks with Price Analysis

from wetherspoons_api import venues, get_drinks

all_venues = venues()
venue = all_venues[0]
drinks = get_drinks(venue)

print(drinks)
# [
#   Drink(name='Ruddles Best', units=2.27, product_id=12345,
#         price=249, ppu=109.69),
#   ...
# ]
# Sorted by best value (lowest price per unit first)

Get Menus

from wetherspoons_api import venues, get_venue, get_menus, get_menu

all_venues = venues()
venue = all_venues[0]
details = get_venue(venue)

# Get all menus for a sales area
menus = get_menus(details, details.sales_areas[0]['id'])

# Get detailed menu information
drinks_menu = next((m for m in menus if m.name == 'Drinks'), None)
if drinks_menu:
    detailed_menu = get_menu(drinks_menu)
    print(detailed_menu.data['categories'])

API Reference

Functions

venues() -> List[HighLevelVenue]

Fetches all Wetherspoons venues.

Returns: List of venue objects with basic information.

get_venue(venue: HighLevelVenue) -> DetailedVenue

Gets detailed information about a specific venue.

Parameters:

• venue: A venue object from venues()

Returns: Detailed venue information including sales areas and ordering capabilities.

get_menus(venue: DetailedVenue, sales_area_id: int) -> List[HighLevelMenu]

Fetches all menus for a specific sales area in a venue.

Parameters:

• venue: A detailed venue object from get_venue()
• sales_area_id: The ID of the sales area

Returns: List of menu objects.

get_menu(high_level_menu: HighLevelMenu) -> DetailedMenu

Gets detailed menu information including all products and categories.

Parameters:

• high_level_menu: A menu object from get_menus()

Returns: Detailed menu with categories, item groups, and products.

get_drinks(high_level_venue: HighLevelVenue) -> List[Drink]

Fetches all drinks from a venue's drinks menu, calculates alcohol units and price per unit, then sorts by best value.

Parameters:

• high_level_venue: A venue object from venues()

Returns: List of drinks sorted by price per unit (best value first).

Models

HighLevelVenue

class HighLevelVenue:
    franchise: str
    id: int
    is_closed: bool
    name: str
    venue_ref: int
    address: Optional[Address]

DetailedVenue

class DetailedVenue:
    can_place_order: Optional[bool]
    franchise: str
    id: int
    is_closed: Optional[bool]
    name: str
    sales_areas: List[dict]
    venue_can_order: Optional[bool]
    venue_ref: Union[str, int]
    address: Optional[Address]

Drink

class Drink:
    name: str
    units: float        # Alcohol units
    product_id: int
    price: int          # Price in pence
    ppu: float          # Price per unit in pence

How It Works

The package:

1. Connects to the JD Wetherspoon API
2. Validates all responses using Pydantic models for type safety
3. Calculates alcohol units based on ABV and volume information
4. Determines the best value portion size for each drink
5. Sorts drinks by price per unit to help find the best deals

Development

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run tests
pytest

# Run tests with coverage
pytest --cov=wetherspoons_api --cov-report=html

# Run specific test
pytest tests/test_api.py::TestVenues::test_venues_filters_open_venues

Testing

The package includes comprehensive unit tests with pytest. Tests use mocking to avoid hitting the live API during development.

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=wetherspoons_api

License

MIT © Joss Bird - Original TypeScript version

Python port maintains the same MIT license.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

Report bugs and feature requests at https://github.com/slack2450/wetherspoons-api/issues

Original TypeScript Version

This is a Python port of the original wetherspoons-api TypeScript package.