littleevents 0.1.0

The official Python SDK for interacting with the Little Events API.

littleevents

The official, developer-friendly Python SDK for interacting with the Little Africa Events API.

littleevents allows external businesses and organizers to seamlessly list, create, and manage events, as well as configure, disable, or enable ticket tiers on the Little Africa platform.

---

Key Features

• Resource-Oriented Interface: Natural, idiomatic usage (e.g. client.events.list_events(), client.ticket_prices.create_ticket_price()).
• Resilient Request Pipeline: Automatically handles HTTP retries on standard rate limits (429) and server errors (5xx) using httpx.HTTPTransport.
• Zero-Overhead Serialization: Pure Python dictionary interfaces for requests and responses—no complex validation models or Pydantic overhead.
• Rich Error Observation: Surfaces LittleEventsAPIError preserving raw upstream HTTP status codes, error structures, and validation messages.
• Clean Sync Client: Optimized HTTP connection pool management built on httpx.

---

Installation

Install the package via pip from PyPI:

pip install littleevents

---

Quickstart

1. Client Initialization

Import the client and initialize it using your Bearer API token:

from littleevents import LittleEventsClient

# Initialize the client
client = LittleEventsClient(api_key="your-little-bearer-token")

---

2. Events Management

List Organizer Events

Retrieve all events belonging to the authenticated organizer:

events_response = client.events.list_events()
print(f"Retrieved {len(events_response.get('data', []))} events.")

Create a New Event

Add a new event under your organizer account. Image dimensions must be exactly 500x500 px:

new_event_data = {
    "EventName": "Startup Neon Gala",
    "Description": "An exquisite evening celebration of tech innovators.",
    "Location": "Alchemist Bar, Westlands",
    "ContactEmail": "[e-mail]",
    "ContactPhone": "[phone]",
    "Country": "Kenya",
    "City": "Nairobi",
    "ImageUrl": "https://example.com/500x500-banner.jpg", # Exactly 500x500 px
    "EventType": "regular",
    "TestEvent": True, # Set to True for sandbox testing
    "Timings": [
        {
            "ShowID": "cb488791-3252-440c-a1de-e5324f10d8cc",
            "Label": "Main Show",
            "Start": "2026-06-01T18:00:00.000Z",
            "End": "2026-06-01T22:00:00.000Z"
        }
    ]
}

created_event = client.events.create_event(new_event_data)

Get Event Details by ID

event = client.events.get_event("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print(event["EventName"])

Update Event

Modify details of an existing event (fields are optional):

client.events.update_event(
    event_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    data={"Location": "Broadwalk Mall, Westlands"}
)

Request Go Live

Submit an event for review and publication by the Little Africa team:

client.events.request_go_live("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

---

3. Ticket Prices Management

Create Ticket Price

Attach a price tier to an existing event:

ticket_payload = {
    "EventID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "PriceName": "Early Bird General",
    "Price": 1500, # In Currency denomination
    "Remaining": 100, # Total supply available
    "Currency": "KES", # "KES" or "USD"
    "MaxAttendees": 100,
    "MaxTicketsPerOrder": 5
}

client.ticket_prices.create_ticket_price(ticket_payload)

Update Ticket Price

client.ticket_prices.update_ticket_price(
    price_id="f47ac10b-58cc-4372-a567-0e02b2c3d479",
    data={"Price": 1800}
)

Disable / Enable Ticket Tiers

Manage the active sales status of ticket tiers:

# Terminate sales for a tier
client.ticket_prices.disable_ticket_price("f47ac10b-58cc-4372-a567-0e02b2c3d479")

# Re-enable sales for a tier
client.ticket_prices.enable_ticket_price("f47ac10b-58cc-4372-a567-0e02b2c3d479")

List Active Ticket Prices

Retrieve active ticket prices bound to a specific event:

active_tickets = client.ticket_prices.list_active_ticket_prices_for_event("a1b2c3d4-e5f6-7890-abcd-ef1234567890")

---

Robust Error Handling

The SDK raises standard LittleEventsAPIError whenever the Little Africa API responds with a non-2xx status code. This preserves the upstream message and state details:

from littleevents import LittleEventsClient, LittleEventsAPIError

client = LittleEventsClient(api_key="token")

try:
    # Trigger an intentional error (e.g. invalid dimensions)
    client.events.create_event({
        "EventName": "Gala",
        "ImageUrl": "https://example.com/invalid-image.jpg" # Not 500x500 px
        # ... other missing required fields
    })
except LittleEventsAPIError as e:
    print(f"API Error Occurred! Status Code: {e.status_code}")
    print(f"Server Message: {e.message}")
    print(f"Full JSON Payload: {e.response_data}")

---

License

This project is licensed under the MIT License.