API Reference¶

Complete reference for all public modules in pretalx-client.

Client¶

class pretalx_client.client.PretalxClient[source]¶

Bases: object

HTTP client for the Pretalx REST API.

Provides methods to fetch speakers, talks, and schedule data from a Pretalx event. Handles pagination automatically and supports both authenticated and public access. Returns typed dataclasses rather than raw dicts.

Delegates low-level HTTP operations to the auto-generated GeneratedPretalxClient.

Parameters:

event_slug (str) – The Pretalx event slug (e.g. "pycon-us-2026").
base_url (str) – Root URL of the Pretalx instance. Defaults to "https://pretalx.com".
api_token (str) – Optional API token for authenticated access. When empty, only publicly available data will be returned.

Example:

client = PretalxClient("pycon-us-2026", api_token="abc123")
speakers = client.fetch_speakers()
talks = client.fetch_talks()
schedule = client.fetch_schedule()

__init__(event_slug, *, base_url='https://pretalx.com', api_token='')[source]¶

Initialize the client for a specific Pretalx event.

Parameters:

event_slug (str) – The Pretalx event slug (e.g. "pycon-us-2026").
base_url (str) – Root URL of the Pretalx instance.
api_token (str) – Optional API token for authenticated access.

fetch_event()[source]¶

Fetch metadata for this event.

Returns the raw event dict with keys: name, slug, date_from, date_to, timezone, urls, etc.

Return type:: dict[str, Any]
Returns:: A raw event dict from the Pretalx API.
Raises:: RuntimeError – If the API returns an HTTP error status.

fetch_rooms()[source]¶

Fetch room ID-to-name mappings for the event.

Return type:: dict[int, str]
Returns:: A dict mapping room IDs to display names.

fetch_rooms_full()[source]¶

Fetch full room data for the event.

Returns all fields from the Pretalx /rooms/ endpoint including id, name, description, capacity, and position.

Return type:: list[dict[str, Any]]
Returns:: A list of raw room dicts from the Pretalx API.

fetch_submission_types()[source]¶

Fetch submission type ID-to-name mappings for the event.

Return type:: dict[int, str]
Returns:: A dict mapping submission type IDs to display names.

fetch_tracks()[source]¶

Fetch track ID-to-name mappings for the event.

Return type:: dict[int, str]
Returns:: A dict mapping track IDs to display names.

fetch_tags()[source]¶

Fetch tag ID-to-name mappings for the event.

Return type:: dict[int, str]
Returns:: A dict mapping tag IDs to display names.

fetch_speakers()[source]¶

Fetch all speakers for the event.

Return type:: list[PretalxSpeaker]
Returns:: A list of PretalxSpeaker instances.

fetch_talks(*, submission_types=None, tracks=None, tags=None, rooms=None)[source]¶

Fetch all confirmed/accepted talks for the event.

Delegates to fetch_talks_with_fallback() for the endpoint selection logic. Tries the /talks/ endpoint first. When that returns 404 (as it does for some Pretalx events like PyCon US), falls back to /submissions/ with confirmed and accepted states.

Parameters:

submission_types (dict[int, str] | None) – Optional ID-to-name mapping for submission types.
tracks (dict[int, str] | None) – Optional ID-to-name mapping for tracks.
tags (dict[int, str] | None) – Optional ID-to-name mapping for tags.
rooms (dict[int, str] | None) – Optional ID-to-name mapping for rooms.

Return type:

list[PretalxTalk]

Returns:

A list of PretalxTalk instances.

fetch_submissions(*, state='', submission_types=None, tracks=None, tags=None, rooms=None)[source]¶

Fetch submissions for the event, optionally filtered by state.

Parameters:

state (str) – Pretalx submission state to filter by (e.g. "confirmed"). When empty, all submissions are returned.
submission_types (dict[int, str] | None) – Optional ID-to-name mapping for submission types.
tracks (dict[int, str] | None) – Optional ID-to-name mapping for tracks.
tags (dict[int, str] | None) – Optional ID-to-name mapping for tags.
rooms (dict[int, str] | None) – Optional ID-to-name mapping for rooms.

Return type:

list[PretalxTalk]

Returns:

A list of PretalxTalk instances.

classmethod fetch_events(*, base_url='https://pretalx.com', api_token='')[source]¶

Fetch all events accessible to the given API token.

Calls GET /api/events/ which does not require an event slug. Returns raw event dicts with keys: name, slug, date_from, date_to, etc.

Parameters:

base_url (str) – Root URL of the Pretalx instance.
api_token (str) – API token for authenticated access.

Return type:

list[dict[str, Any]]

Returns:

A list of raw event dicts from the Pretalx API.

fetch_schedule(*, rooms=None)[source]¶

Fetch schedule slots for the event from the paginated /slots/ endpoint.

Uses the /slots/ endpoint which returns fully expanded slot objects with start/end times and room IDs, unlike /schedules/latest/ which only returns slot ID integers.

Parameters:: rooms (dict[int, str] | None) – Optional ID-to-name mapping for resolving integer room IDs.
Return type:: list[PretalxSlot]
Returns:: A list of PretalxSlot instances.

Data Models¶

class pretalx_client.models.PretalxSpeaker[source]¶

Bases: object

A speaker record from the Pretalx API.

Variables:

code – Unique alphanumeric speaker identifier in Pretalx.
name – Speaker’s display name.
biography – Markdown-formatted biography text.
avatar_url – URL to the speaker’s avatar image.
email – Speaker’s email (only available with authenticated API access).
submissions – List of submission codes this speaker is associated with.

Parameters:

code (str)
name (str)
biography (str)
avatar_url (str)
email (str)
submissions (list[str])

code: str¶

name: str¶

biography: str¶

avatar_url: str¶

email: str¶

submissions: list[str]¶

classmethod from_api(data)[source]¶

Construct a PretalxSpeaker from a raw Pretalx API dict.

Parses through the generated Speaker or SpeakerOrga model for field validation, then adapts into the consumer-friendly shape. Falls back to direct dict extraction when the generated model cannot handle the API response (e.g. avatar vs avatar_url).

Parameters:: data (dict[str, Any]) – A single speaker object from the Pretalx speakers endpoint.
Return type:: PretalxSpeaker
Returns:: A populated PretalxSpeaker instance.

__init__(code, name, biography='', avatar_url='', email='', submissions=<factory>)¶

Parameters:

code (str)
name (str)
biography (str)
avatar_url (str)
email (str)
submissions (list[str])

class pretalx_client.models.PretalxTalk[source]¶

Bases: object

A talk or submission record from the Pretalx API.

Variables:

code – Unique alphanumeric submission identifier.
title – Talk title.
abstract – Short summary.
description – Full description.
submission_type – Resolved display name of the submission type.

track: Resolved display name of the track.: tags: Resolved display names of tags. duration: Duration in minutes. state: Submission lifecycle state. speaker_codes: List of speaker codes linked to this talk. room: Resolved display name of the scheduled room. slot_start: Scheduled start time (ISO 8601). slot_end: Scheduled end time (ISO 8601).

Parameters:

code (str)
title (str)
abstract (str)
description (str)
submission_type (str)
track (str)
tags (list[str])
duration (int | None)
state (str)
speaker_codes (list[str])
room (str)
slot_start (str)
slot_end (str)

code: str¶

title: str¶

abstract: str¶

description: str¶

submission_type: str¶

track: str¶

tags: list[str]¶

duration: int | None¶

state: str¶

speaker_codes: list[str]¶

room: str¶

slot_start: str¶

slot_end: str¶

classmethod from_api(data, *, submission_types=None, tracks=None, tags=None, rooms=None)[source]¶

Construct a PretalxTalk from a raw Pretalx API dict.

Parses through the generated Submission model for field validation, then resolves integer IDs to display names via the adapter layer. Falls back to direct dict extraction when the generated model cannot handle the API response shape.

Parameters:

data (dict[str, Any]) – A single submission or talk object from the Pretalx API.
submission_types (dict[int, str] | None) – Optional {id: name} mapping for resolving integer submission type IDs.
tracks (dict[int, str] | None) – Optional {id: name} mapping for resolving integer track IDs.
tags (dict[int, str] | None) – Optional {id: name} mapping for resolving integer tag IDs.
rooms (dict[int, str] | None) – Optional {id: name} mapping for resolving integer room IDs.

Return type:

PretalxTalk

Returns:

A populated PretalxTalk instance.

__init__(code, title, abstract='', description='', submission_type='', track='', tags=<factory>, duration=None, state='', speaker_codes=<factory>, room='', slot_start='', slot_end='')¶

Parameters:

code (str)
title (str)
abstract (str)
description (str)
submission_type (str)
track (str)
tags (list[str])
duration (int | None)
state (str)
speaker_codes (list[str])
room (str)
slot_start (str)
slot_end (str)

class pretalx_client.models.PretalxSlot[source]¶

Bases: object

A schedule slot from the Pretalx schedule API.

Variables:

room – Resolved display name of the room.
start – Slot start time as an ISO 8601 string.
end – Slot end time as an ISO 8601 string.
code – Submission code if this slot holds a talk, empty otherwise.
title – Resolved display title for the slot.
start_dt – Parsed start datetime, or None if unparsable.
end_dt – Parsed end datetime, or None if unparsable.

Parameters:

room (str)
start (str)
end (str)
code (str)
title (str)
start_dt (datetime | None)
end_dt (datetime | None)

room: str¶

start: str¶

end: str¶

code: str¶

title: str¶

start_dt: datetime | None¶

end_dt: datetime | None¶

classmethod from_api(data, *, rooms=None)[source]¶

Construct a PretalxSlot from a raw Pretalx schedule slot dict.

Validates the raw dict through the generated TalkSlot model, then delegates to normalize_slot() for field extraction and normalization.

Handles both the legacy format (string room, code, title keys) and the real paginated /slots/ format (integer room ID, submission key instead of code, no title).

Parameters:

data (dict[str, Any]) – A single slot object from the Pretalx schedule endpoint.
rooms (dict[int, str] | None) – Optional {id: name} mapping for resolving integer room IDs.

Return type:

PretalxSlot

Returns:

A populated PretalxSlot instance.

__init__(room, start, end, code='', title='', start_dt=None, end_dt=None)¶

Parameters:

room (str)
start (str)
end (str)
code (str)
title (str)
start_dt (datetime | None)
end_dt (datetime | None)

class pretalx_client.models.SubmissionState[source]¶

Bases: StrEnum

Pretalx submission lifecycle states.

Values are sourced from the OpenAPI-generated StateEnum where available, with DELETED added for states observed in practice but absent from the published schema.

SUBMITTED = 'submitted'¶

ACCEPTED = 'accepted'¶

REJECTED = 'rejected'¶

CONFIRMED = 'confirmed'¶

WITHDRAWN = 'withdrawn'¶

CANCELED = 'canceled'¶

DRAFT = 'draft'¶

DELETED = 'deleted'¶

__new__(value)¶

Adapters¶

`pretalx_client.adapters.normalization`	Normalization helpers for Pretalx multilingual and ID-based fields.
`pretalx_client.adapters.schedule`	Schedule slot parsing and datetime normalization for Pretalx API data.