wystia package

Subpackages

Submodules

wystia.api_base module

” Base API Classes

wystia.api_data module

class wystia.api_data.WistiaDataApi[source]

Bases: _BaseWistiaApi

Helper class to interact with the Wistia Data API (docs below)

https://wistia.com/support/developers/data-api

Fully implements the following sections in the API documentation:

  • Paging and Sorting Responses

  • Projects

  • Medias

  • Customizations

  • Captions

classmethod copy_media(media_id: str, dest_project_id: str | None = None, owner: str | None = None) Media[source]
Copy a media, optionally to another project, via the Medias#copy API:

https://wistia.com/support/developers/data-api#medias_copy

Raises:
classmethod copy_project(project_id: str, admin_email: str | None = None) Project[source]

Copies an existing project in your account, including all media and sections, via the Projects:copy API:

classmethod copy_video(video_id: str, dest_project_id: str | None = None, owner: str | None = None, model_cls: type[T] = <class 'wystia.models.Video'>) T | Video[source]
Copy a video, optionally to another project, via the Medias#copy API:

https://wistia.com/support/developers/data-api#medias_copy

Raises:
classmethod create_captions(video_id: str, lang_code: LanguageCode | None = None, srt_contents: str | None = None, srt_file: str | None = None) None[source]

Create new captions for a given language on a Wistia video, via the Captions#create API:

Note that this always add new captions, regardless of whether captions already exist for the language. Please use update_captions() if we need to replace captions for a language instead.

Parameters:
  • video_id – The Wistia video to add the new captions for.

  • lang_code – An optional ISO-639–2 language code for the file. If left unspecified, the language code will be detected automatically.

  • srt_contents – The caption text in SRT format.

  • srt_file – The path to an SRT file.

Raises:

ContentIsEmpty – If one of srt_contents or srt_file is not provided.

classmethod create_customizations(video_id: str, customizations: Customizations) Customizations[source]

Overwrites the customizations for a video on Wistia, via the Customizations#create API:

Returns:

The new customizations on the video

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod create_project(project_name: str | None = None, admin_email: str | None = None, public_upload: bool | None = None, public_download: bool | None = None, public: bool | None = None) Project[source]
Create a new project in your account, via the Projects:create API:

https://wistia.com/support/developers/data-api#projects_create

classmethod delete_captions(video_id: str, lang_code: LanguageCode)[source]

Deletes the captions for a video on Wistia, via the Captions#delete API:

classmethod delete_customizations(video_id: str)[source]

Deletes the customizations for a video on Wistia, via the Customizations#delete API:

classmethod delete_media(media_id: str)[source]

Deletes a media (generally a video) from Wistia, via the Medias#delete API:

Returns:

A boolean indicating whether the video was successfully deleted.

classmethod delete_project(project_id: str)[source]
Delete a project in your account, via the Projects:delete API:

https://wistia.com/support/developers/data-api#projects_delete

Returns:

A boolean indicating whether the video was successfully deleted.

classmethod delete_video(media_id: str)

Deletes a media (generally a video) from Wistia, via the Medias#delete API:

Returns:

A boolean indicating whether the video was successfully deleted.

classmethod get_captions(video_id: str, lang_code: LanguageCode) VideoCaptions | None[source]

Retrieves the captions for a specific language on a Wistia video, via the Captions#show API:

The text of the captions will be in SRT format. If no captions exist for the specified language, a None value is returned.

classmethod get_customizations(video_id: str) Customizations[source]

Get customizations for a video on Wistia, via the Customizations#show API:

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod get_media(media_id: str) Media[source]
Get information on a Wistia media, via the Medias#show API:

https://wistia.com/support/developers/data-api#medias_show

Raises:

NoSuchMedia – If the media does not exist on Wistia

classmethod get_stats_for_video(video_id: str) VideoStats[source]

Get aggregated tracking stats on a Wistia video, via the Medias#stats API:

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod get_video(video_id: str, model_cls: type[T] = <class 'wystia.models.Video'>) T | Video[source]
Get information on a Wistia video, via the Medias#show API:

https://wistia.com/support/developers/data-api#medias_show

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod list_all_projects(sort_by: SortBy | None = None, sort_dir: SortDir | None = None, per_page=100) Container[Project][source]

Retrieve a list of Projects in the account, via the Projects:list API:

Defaults to sorting by Project ID. You can pass the`sort_by` argument to sort by another value.

Raises:

NoSuchProject – If the project does not exist on Wistia

classmethod list_captions(video_id: str) Container[VideoCaptions][source]

Retrieves all the captions on a Wistia video, via the Captions#index API:

The text of the captions will be in SRT format.

Raises:

NoSuchMedia – If the video does not exist on Wistia.

classmethod list_medias(project_id: str | None = None, media_name: str | None = None, media_type: MediaType | None = None, media_id: str | None = None, sort_by: SortBy | None = None, sort_dir: SortDir | None = None, model_cls: type[T] = <class 'wystia.models.Media'>) Container[T | Media][source]

Get all medias for a Wistia project or by other criteria, via the Medias#list API:

Defaults to sorting by Project ID. You can pass the`sort_by` argument to sort by another value.

Raises:

NoSuchProject – If the project does not exist on Wistia

classmethod list_project(project_id: str, sort_by: SortBy | None = None, sort_dir: SortDir | None = None, per_page=500, model_cls: type[T] = <class 'wystia.models.Media'>) Container[T | Media][source]

Get all medias (generally videos) for a Wistia project, via the Projects#show API:

Defaults to sorting by Project ID. You can pass the`sort_by` argument to sort by another value.

Raises:

NoSuchProject – If the project does not exist on Wistia

classmethod list_videos(project_id: str | None = None, video_name: str | None = None, media_type: MediaType | None = MediaType.VIDEO, video_id: str | None = None, sort_by: SortBy | None = None, sort_dir: SortDir | None = None) Container[Video][source]

Get all videos for a Wistia project or by other criteria, via the Medias#list API:

Defaults to sorting by Project ID. You can pass the`sort_by` argument to sort by another value.

Raises:

NoSuchProject – If the project does not exist on Wistia

classmethod order_captions(video_id: str, automated: bool = False, rush: bool = True, automatically_enable: bool = True) None[source]

Purchase English captions on a Wistia video, via the Captions#purchase API:

Parameters:
  • video_id – The hashed id of the video to order captions for.

  • automated – Set to true to order computer-generated captions ($0.25/minute) or false to order human-generated captions ($2.50/minute). Defaults to false.

  • rush – Set to true to enable a rush order (one business day turnaround, $4.00/minute), or false to retain the standard four business day turnaround for human-generated captions ($2.50/minute). Defaults to true.

  • automatically_enable – Set to true to automatically enable captions for the video as soon as the order is ready or false to hold the captions for review before manually enabling them. Defaults to true.

Raises:
classmethod update_captions(video_id: str, lang_code: LanguageCode, srt_contents: str | None = None, srt_file: str | None = None) None[source]

Replace captions for a given language on a Wistia video, via the Captions#update API:

Note: it is generally safer to call this method instead of create_captions(), which always adds new captions for a given language; this method falls back to create_captions() in case captions don’t exist for the specified language.

Parameters:
  • video_id – The Wistia video to add the new captions for.

  • lang_code – An ISO-639–2 language code for the file. If left unspecified, the language code will be detected automatically.

  • srt_contents – The caption text in SRT format.

  • srt_file – The path to an SRT file.

Raises:

ContentIsEmpty – If one of srt_contents or srt_file is not provided.

classmethod update_customizations(video_id: str, customizations: Customizations) Customizations[source]

Updates the customizations for a video on Wistia, via the Customizations#update API:

Returns:

The new customizations on the video

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod update_media(media_id: str, media_name: str | None = None, media_desc: str | None = None, thumbnail_media_id: str | None = None, model_cls: type[T] = <class 'wystia.models.Media'>) T | Media[source]

Updates attributes on a media (generally a video), via the Medias#update API:

Parameters:
  • media_id – The hashed id of the media on Wistia.

  • media_name – An optional new name for the media.

  • media_desc – An optional new description for this media. Accepts plain text or markdown.

  • thumbnail_media_id – The Wistia hashed ID of an image that will replace the still that’s displayed before the player starts playing.

  • model_cls – The model class to load the response data into.

Raises:

NoSuchMedia – If the media does not exist on Wistia

classmethod update_project(project_id: str, project_name: str | None = None, public_upload: bool | None = None, public_download: bool | None = None, public: bool | None = None) Project[source]

Update an existing project in your account, via the Projects:update API:

classmethod update_video(video_id: str, video_name: str | None = None, video_desc: str | None = None, thumbnail_media_id: str | None = None) Video[source]
Updates attributes on a video, via the Medias#update API:

https://wistia.com/support/developers/data-api#medias_update

Parameters:
  • video_id – The hashed id of the video on Wistia.

  • video_name – An optional new name for the video.

  • video_desc – An optional new description for this video. Accepts plain text or markdown.

  • thumbnail_media_id – The Wistia hashed ID of an image that will replace the still that’s displayed before the player starts playing.

Raises:

NoSuchMedia – If the video does not exist on Wistia

wystia.api_embed module

class wystia.api_embed.WistiaEmbedApi[source]

Bases: _BaseWistiaApi

Helper class to interact with the Wistia Media Embed API (docs below)

https://wistia.com/support/developers/embed-options

classmethod asset_url(video_id: str | None = None, media_data: VideoEmbedData | None = None, asset_type='original') str | None[source]

Get the media asset url stored on Wistia, by default for the “original” video.

Note: one of video_id or media_data must be specified.

Note that Wistia also has separate asset url’s for various resolutions on each video.

classmethod get_data(video_id: str) VideoEmbedData[source]

Get media embed data for a Wistia video using the endpoint to the .jsonp file

classmethod num_assets(video_id: str | None = None, media_data: VideoEmbedData | None = None, asset_type='mp4_alternate_audio') int[source]

Return the total number of assets (by default, AD files) associated with a Wistia video.

wystia.api_helper module

Utility functions for interacting with the Wistia API.

class wystia.api_helper.WistiaHelper[source]

Bases: object

Helper class for interacting with Wistia API and Wistia videos, which further simplifies any calls. This assumes that WistiaApi has been configured as needed with the API token.

classmethod customize_video_on_wistia(video_id: str, player_color: str)[source]

Set commonly used customization options for a media on Wistia.

classmethod disable_captions_and_ad(video_id: str, on_by_default: bool = False)[source]

Disable captions and AD on a Wistia video.

classmethod enable_ad(video_id: str)[source]

Enable audio descriptions on a Wistia video.

classmethod enable_captions(video_id: str, on_by_default: bool = False)[source]

Enable captions on a Wistia video.

classmethod enable_captions_and_ad(video_id: str, on_by_default: bool = False)[source]

Enable captions and AD on a Wistia video.

classmethod has_captions_enabled(video_id: str) bool[source]

Check if a video has captions available in the player settings.

Returns:

A boolean indicating if the video player has captions available.

static is_archived_video(video_name: str) bool[source]

Check if this is an archived video which is automatically created by Wistia.

In that case, we shouldn’t order captions for it, since it’s a copy of a video that was replaced with new media.

Source: https://wistia.com/learn/product-updates/improved-library-management-tools # noqa: E501

classmethod project_details(project_id: str, projects: Container[Project] | None = None) Project[source]

Retrieve details on a Wistia project.

The optional parameter projects contains info on all projects in the Wistia account, such as a response from the Projects:list API.

Raises:

NoSuchProject – If the project doesn’t exist on Wistia

classmethod update_video_name(video_id: str, video_title: str) Video[source]

Update the title for a Wistia video.

classmethod video_exists(video_id: str) bool[source]

Check if a video exists on Wistia.

wystia.api_upload module

class wystia.api_upload.WistiaUploadApi[source]

Bases: _BaseWistiaApi

Helper class to interact with the Wistia Upload API (docs below)

https://wistia.com/support/developers/upload-api

classmethod upload_file(file_path: str, project_id: str | None = None, title: str | None = None, description: str | None = None, contact_id: int | None = None, max_retries=5) UploadResponse[source]

Uploads a video file (given an absolute file path) to Wistia, and returns the hashed ID of the newly hosted video.

Docs:

https://wistia.com/support/developers/upload-api#the-request

Parameters:
  • file_path – The path of the video file to upload.

  • project_id – The hashed id of the project to upload media into. If omitted, a new project will be created and uploaded to.

  • title – Optional display name for the video. If omitted, the filename will be used instead.

  • description – Optional description for the video.

  • contact_id – A Wistia contact id, an integer value. If omitted, it will default to the contact_id of the account’s owner.

  • max_retries – Maximum number of retries, in case we run into a BrokenPipeError while uploading the video; defaults to 5.

Raises:

UploadFailed – In case the upload operation fails; also logs error details from the Upload API response.

Uploads a public video link to Wistia, and returns the hashed ID of the newly hosted video.

Docs:

https://wistia.com/support/developers/upload-api#the-request

Parameters:
  • url – A public, downloadable link for the video.

  • project_id – The hashed id of the project to upload media into. If omitted, a new project will be created and uploaded to.

  • title – Optional display name for the video. If omitted, the filename will be used instead.

  • description – Optional description for the video.

  • contact_id – A Wistia contact id, an integer value. If omitted, it will default to the contact_id of the account’s owner.

Raises:

UploadFailed – In case the upload operation fails; also logs error details from the Upload API response.

wystia.config module

Configs and settings for Wistia API

class wystia.config.WistiaConfig[source]

Bases: object

ALL_CAPTIONS_URL = 'medias/{media_id}/captions.json'
API_URL = 'https://api.wistia.com/v1/'
CAPTIONS_ORDER_URL = 'medias/{media_id}/captions/purchase.json'
CUSTOMIZATION_URL = 'medias/{media_id}/customizations.json'
EMBED_URL = 'https://fast.wistia.com/embed/'
LANG_CAPTIONS_URL = 'medias/{media_id}/captions/{lang_code}.json'
MEDIAS_COPY_URL = 'medias/{media_id}/copy.json'
MEDIAS_EMBED_URL = 'medias/{media_id}.json'
MEDIAS_SHOW_URL = 'medias/{media_id}.json'
MEDIAS_STATS_URL = 'medias/{media_id}/stats.json'
MEDIAS_URL = 'medias.json'
PROJECTS_COPY_URL = 'projects/{project_id}/copy.json'
PROJECTS_SHOW_URL = 'projects/{project_id}.json'
PROJECTS_URL = 'projects.json'
UPLOAD_URL = 'https://upload.wistia.com/'
classmethod wistia_url(video_id, account_name='REPLACE-ME')[source]

Construct the wistia media Url given a video id

wystia.constants module

Project-specific constants

wystia.errors module

Project-specific exception classes

exception wystia.errors.ContentIsEmpty[source]

Bases: WistiaError

exception wystia.errors.NoSuchMedia(media_id)[source]

Bases: WistiaError

exception wystia.errors.NoSuchProject(project_id)[source]

Bases: WistiaError

exception wystia.errors.UploadFailed(r: Response)[source]

Bases: WistiaError

exception wystia.errors.VideoHasCaptions(video_id)[source]

Bases: WistiaError

exception wystia.errors.WistiaError(message, **log_kwargs)[source]

Bases: Exception

Base exception class for errors raised by this library.

ERR_STATUS = 400
response()[source]

Formats an error object and returns an AWS Lambda Proxy response.

wystia.log module

wystia.models module

class wystia.models.CaptionsV1(on: bool | None = None, on_by_default: bool | None = None, is_async: bool | None = None, language: str = '')[source]

Bases: object

CaptionsV1 dataclass

is_async: bool | None = None
language: str = ''
on: bool | None = None
on_by_default: bool | None = None
class wystia.models.ChapterList(id: int, title: str, time: float, deleted: bool)[source]

Bases: object

ChapterList dataclass

deleted: bool
id: int
time: float
title: str
class wystia.models.Chapters(on: bool | None = None, visible_on_load: bool | None = None, chapter_list: list[ChapterList] | None = None)[source]

Bases: object

Chapters dataclass

chapter_list: list[ChapterList] | None = None
on: bool | None = None
visible_on_load: bool | None = None
class wystia.models.Container(iterable=(), /)[source]

Bases: List[T]

Convenience wrapper around a collection of dataclass instances.

For all intents and purposes, this should behave exactly as a list object.

Usage:

>>> from dataclass_wizard import Container, fromlist
>>> from dataclasses import make_dataclass
>>>
>>> A = make_dataclass('A', [('f1', str), ('f2', int)])
>>> list_of_a = fromlist(A, [{'f1': 'hello', 'f2': 1}, {'f1': 'world', 'f2': 2}])
>>> c = Container[A](list_of_a)
>>> print(c.prettify())
prettify(encoder: ~dataclass_wizard.type_def.Encoder = <function dumps>, ensure_ascii=False, **encoder_kwargs) str[source]

Convert the list of instances to a prettified JSON string.

to_json(encoder: ~dataclass_wizard.type_def.Encoder = <function dumps>, **encoder_kwargs) str[source]

Convert the list of instances to a JSON string.

to_json_file(file: str, mode: str = 'w', encoder: ~dataclass_wizard.type_def.FileEncoder = <function dump>, **encoder_kwargs) None[source]

Serializes the list of instances and writes it to a JSON file.

class wystia.models.Customizations(vulcan: bool | None = None, anonymize_ip: bool = True, player_color: str = '', still_url: str | None = None, unaltered_still_image_asset: UnalteredStillImageAsset | None = None, thumbnail_alt_text: str | None = None, auto_play: bool | None = None, silent_auto_play: bool | None = None, end_video_behavior: str | None = None, controls_visible_on_load: bool = True, play_button: bool | None = None, bpb_time: bool | None = None, small_play_button: bool | None = None, play_bar: bool | None = None, volume_control: bool | None = None, settings_control: bool | None = None, playback_rate_control: bool | None = None, quality_control: bool | None = None, fullscreen_button: bool | None = None, plugin: Plugin | None = None, private: Private | None = None, encrypted: Encrypted | None = None, audio_description_is_required: bool | None = None, plays_inline: bool | None = None, branding: bool | None = None, show_customer_logo: bool | None = None, customer_logo_image_url: str = '', customer_logo_target_url: str = '', chapters_on: bool | None = None, spherical: bool | None = None, video_quality: str = '', muted: bool | None = None)[source]

Bases: JSONSerializable

Model class which represents customization data for a Wistia video - also known as “Embed Options” in the Wistia docs.

Ref: https://wistia.com/support/developers/embed-options

anonymize_ip: bool = True
audio_description_is_required: bool | None = None
auto_play: bool | None = None
bpb_time: bool | None = None
branding: bool | None = None
chapters_on: bool | None = None
controls_visible_on_load: bool = True
customer_logo_image_url: str = ''
customer_logo_target_url: str = ''
encrypted: Encrypted | None = None
end_video_behavior: str | None = None
fullscreen_button: bool | None = None
muted: bool | None = None
play_bar: bool | None = None
play_button: bool | None = None
playback_rate_control: bool | None = None
player_color: str = ''
plays_inline: bool | None = None
plugin: Plugin | None = None
private: Private | None = None
quality_control: bool | None = None
settings_control: bool | None = None
silent_auto_play: bool | None = None
small_play_button: bool | None = None
spherical: bool | None = None
still_url: str | None = None
thumbnail_alt_text: str | None = None
unaltered_still_image_asset: UnalteredStillImageAsset | None = None
video_quality: str = ''
volume_control: bool | None = None
vulcan: bool | None = None
class wystia.models.Encrypted(password_protect_password: str = '')[source]

Bases: object

Encrypted dataclass

password_protect_password: str = ''
class wystia.models.Eventbrite(on: bool | None = None, event_id: str = '', text: str = '', time: float | None = None, duration: int | None = None, type: str | None = None, conversion_opportunity_key: str | None = None)[source]

Bases: object

Eventbrite dataclass

conversion_opportunity_key: str | None = None
duration: int | None = None
event_id: str = ''
on: bool | None = None
text: str = ''
time: float | None = None
type: str | None = None
class wystia.models.LanguageCode(value)[source]

Bases: Enum

The 3-character Language Codes for Wistia, as specified by ISO-639-2.

CHINESE = 'chi'
ENGLISH = 'eng'
FRENCH = 'fre'
GERMAN = 'ger'
ITALIAN = 'ita'
JAPANESE = 'jpn'
SPANISH = 'spa'

Bases: object

Link dataclass

conversion_opportunity_id: int | None = None
conversion_opportunity_key: str | None = None
duration: float
name: str
position: str | None = None
text: str
theme: str | None = None
time: float
url: str
class wystia.models.Media(hashed_id: str, id: int, name: str, type: MediaType, created: datetime, updated: datetime, archived: bool | None = None, duration: float | None = None, status: MediaStatus = MediaStatus.NOT_FOUND, description: str = '', progress: float = 0.0, thumbnail: Thumbnail = None, project: ProjectInfo | None = None, embed_code: str = None, assets: list[Asset] = None, section: str | None = None)[source]

Bases: JSONListWizard

Media dataclass

archived: bool | None = None
assets: list[Asset] = None
created: datetime
description: str = ''
duration: float | None = None
embed_code: str = None
hashed_id: str
id: int
name: str
progress: float = 0.0
project: ProjectInfo | None = None
project_id

Return the project’s hashed id.

section: str | None = None
set_project_id(project_id: str)[source]

Set the project’s hashed id for the media.

status: MediaStatus = 'not_found'
thumbnail: Thumbnail = None
type: MediaType
updated: datetime
class wystia.models.MediaStatus(value)[source]

Bases: Enum

Describes the current status of Media files.

The status indicates which stage in processing the file is at.

https://wistia.com/support/developers/data-api#media-status

FAILED = 'failed'
NOT_FOUND = 'not_found'
PROCESSING = 'processing'
QUEUED = 'queued'
READY = 'ready'
class wystia.models.MediaType(value)[source]

Bases: Enum

Wistia Media Types, as documented in the link below:

https://wistia.com/support/developers/data-api#medias_response

AUDIO = 'Audio'
IMAGE = 'Image'
PDF = 'PdfDocument'
SWF = 'Swf'
UNKNOWN = 'UnknownType'
VIDEO = 'Video'
WORD = 'MicrosoftOfficeDocument'
class wystia.models.MidrollLinkV1(on: bool | None = None, links: list[Link] | None = None)[source]

Bases: object

MidrollLinkV1 dataclass

on: bool | None = None
class wystia.models.PasswordProtectedVideo(on: bool | None = None, challenge: str | None = None)[source]

Bases: object

PasswordProtectedVideo dataclass

challenge: str | None = None
on: bool | None = None
class wystia.models.Plugin(thumbnail_text_overlay_v2: ThumbnailTextOverlayV2 | None = None, thumbnail_text_overlay: ThumbnailTextOverlay | None = None, video_thumbnail: VideoThumbnail | None = None, midroll_link_v1: MidrollLinkV1 | None = None, post_roll_v1: PostRollV1 | None = None, captions_v1: CaptionsV1 = <factory>, chapters: Chapters | None = None, eventbrite: Eventbrite | None = None, share: Share | None = None, require_email_v1: RequireEmailV1 | None = None, password_protected_video: PasswordProtectedVideo | None = None)[source]

Bases: object

Plugin dataclass

captions_v1: CaptionsV1
chapters: Chapters | None = None
eventbrite: Eventbrite | None = None
password_protected_video: PasswordProtectedVideo | None = None
post_roll_v1: PostRollV1 | None = None
require_email_v1: RequireEmailV1 | None = None
share: Share | None = None
thumbnail_text_overlay: ThumbnailTextOverlay | None = None
thumbnail_text_overlay_v2: ThumbnailTextOverlayV2 | None = None
video_thumbnail: VideoThumbnail | None = None
class wystia.models.PostRollV1(on: bool | None = None, rewatch: bool | None = None, text: str | None = None, link: str | None = None, time: float | None = None, auto_size: bool | None = None, cta_type: str | None = None, style: Style | None = None, alt_text: str | None = None, raw: str | None = None, image: str | None = None, conversion_opportunity_key: str | None = None)[source]

Bases: object

PostRollV1 dataclass

alt_text: str | None = None
auto_size: bool | None = None
conversion_opportunity_key: str | None = None
cta_type: str | None = None
image: str | None = None
on: bool | None = None
raw: str | None = None
rewatch: bool | None = None
style: Style | None = None
text: str | None = None
time: float | None = None
class wystia.models.Private(show_comments: bool | None = None, password_protect_on: bool | None = None)[source]

Bases: object

Private dataclass

password_protect_on: bool | None = None
show_comments: bool | None = None
class wystia.models.Project(hashed_id: str, id: int, name: str, media_count: int, created: datetime, updated: datetime, anonymous_can_upload: bool, anonymous_can_download: bool, public: bool, public_id: str, description: str | None)[source]

Bases: JSONListWizard

Project dataclass

anonymous_can_download: bool
anonymous_can_upload: bool
created: datetime
description: str | None
hashed_id: str
id: int
media_count: int
name: str
public: bool
public_id: str
updated: datetime
class wystia.models.RequireEmailV1(on: bool | None = None, top_text: str | None = None, bottom_text: str | None = None, time: float | None = None, ask_name: bool | None = None, allow_skip: bool | None = None, persistent_turnstile: bool | None = None, conversion_opportunity_key: str | None = None, submit_button_text: str | None = None, is_async: bool | None = None)[source]

Bases: object

RequireEmailV1 dataclass

allow_skip: bool | None = None
ask_name: bool | None = None
bottom_text: str | None = None
conversion_opportunity_key: str | None = None
is_async: bool | None = None
on: bool | None = None
persistent_turnstile: bool | None = None
submit_button_text: str | None = None
time: float | None = None
top_text: str | None = None
class wystia.models.Share(on: bool | None = None, channels: str | None = None, page_title: str | None = None, page_url: str | None = None, tweet_text: str | None = None, override_url: bool | None = None, conversion_opportunity_key: str | None = None, download_type: str | None = None)[source]

Bases: object

Share dataclass

channels: str | None = None
conversion_opportunity_key: str | None = None
download_type: str | None = None
on: bool | None = None
override_url: bool | None = None
page_title: str | None = None
page_url: str | None = None
tweet_text: str | None = None
class wystia.models.SortBy(value)[source]

Bases: Enum

The name of the field to sort by. Defaults to sorting by Project ID.

https://wistia.com/support/developers/data-api#sorting

CREATED = 'created'
NAME = 'name'
UPDATED = 'updated'
class wystia.models.SortDir(value)[source]

Bases: Enum

Specifies the direction of the sort, defaults to ASC (ascending) order.

https://wistia.com/support/developers/data-api#sorting

ASC = 1
DESC = 0
class wystia.models.Style(background_color: str)[source]

Bases: object

Style dataclass

background_color: str
class wystia.models.ThumbnailTextOverlay(on: bool | None = None, text: str = '', include_text_overlay: bool | None = None, chapters: Chapters | None = None, captions_v1: CaptionsV1 | None = None, is_async: bool | None = None)[source]

Bases: object

ThumbnailTextOverlay dataclass

captions_v1: CaptionsV1 | None = None
chapters: Chapters | None = None
include_text_overlay: bool | None = None
is_async: bool | None = None
on: bool | None = None
text: str = ''
class wystia.models.ThumbnailTextOverlayV2(on: bool | None = None, text: str = '', include_text_overlay: bool | None = None, text_overlay_image_url: str | None = None, is_async: bool | None = None)[source]

Bases: object

ThumbnailTextOverlayV2 dataclass

include_text_overlay: bool | None = None
is_async: bool | None = None
on: bool | None = None
text: str = ''
text_overlay_image_url: str | None = None
class wystia.models.UnalteredStillImageAsset(url: str, width: int | None = None, height: int | None = None)[source]

Bases: object

UnalteredStillImageAsset dataclass

height: int | None = None
url: str
width: int | None = None
class wystia.models.UploadResponse(hashed_id: str, id: int, name: str, type: MediaType, description: str | None, account_id: int, archived: bool, created: datetime, updated: datetime, progress: float, thumbnail: Thumbnail, duration: float | None = None, status: MediaStatus = MediaStatus.QUEUED)[source]

Bases: JSONSerializable

Represents a response from the Wistia Upload API

Example response format:

https://wistia.com/support/developers/upload-api#response-format

account_id: int
archived: bool
created: datetime
description: str | None
duration: float | None = None
hashed_id: str
id: int
name: str
progress: float
status: MediaStatus = 'queued'
thumbnail: Thumbnail
type: MediaType
updated: datetime
class wystia.models.Video(hashed_id: str, id: int, name: str, type: MediaType, created: datetime, updated: datetime, archived: bool | None = None, duration: float = 0.0, status: MediaStatus = MediaStatus.NOT_FOUND, description: str = '', progress: float = 0.0, thumbnail: Thumbnail = None, project: ProjectInfo = None, embed_code: str = None, assets: list[Asset] = None, section: str | None = None, has_audio_description: bool | None = None, captions_enabled: bool | None = None, overlay_text: str | None = None, caption_duration: float | None = None, num_captions: int | None = None, ad_disabled: bool | None = None)[source]

Bases: Media, JSONListWizard

Video dataclass

ad_disabled: bool | None = None
caption_duration: float | None = None
captions_enabled: bool | None = None
duration: float = 0.0
has_audio_description: bool | None = None
property has_captions: bool

Indicates whether the Wistia video has a captions file.

classmethod list_for_project(project_id: str) list[Video][source]

List videos for a Wistia project.

classmethod load_video(video_id: str) Video[source]

Retrieve video data from Wistia and return a new Video object.

num_captions: int | None = None
overlay_text: str | None = None
process_captions(captions: Iterable[VideoCaptions])[source]

Process the response from the Captions: Index API for the video.

Sets the following attributes on the object:
  • num_captions

  • caption_duration

Ref: https://wistia.com/support/developers/data-api#captions_index

process_customizations(customizations: Customizations)[source]

Process the response from the Customizations: Show API for the video.

Sets the following attributes on the object:
  • ad_disabled

  • captions_enabled

  • overlay_text

Ref: https://wistia.com/support/developers/data-api#customizations_show

project: ProjectInfo = None
class wystia.models.VideoCaptions(language: LanguageCode, text: str, english_name: str, native_name: str, is_draft: bool)[source]

Bases: JSONListWizard

Video Captions dataclass

approx_total_duration

Return the approximate duration (in seconds) of the captions.

This duration is estimated based on the end timestamp in the SRT contents of the captions.

english_name: str
is_draft: bool
language: LanguageCode
native_name: str
text: str
class wystia.models.VideoEmbedData(hashed_id: str, name: str, created_at: datetime, duration: float, assets: list[EmbedAsset], project_id: int, stats: EmbedStats, distillery_url: str, account_key: str, privacy_mode: bool, media_id: int, account_id: int, analytics_host: str, media_key: str, type: str, media_type: str, progress: float, status: int, branding: bool, enable_customer_logo: bool, seo_description: str, preload_preference: str, flash_player_url: str, show_about: bool, first_embed_for_account: bool, first_share_for_account: bool, keyframe_align: bool, use_media_data_host_logic: bool, tracking_transmit_interval: int, integrations: dict[str, str], embed_options: Customizations, captions: list[EmbedCaption] = <factory>, hls_enabled: bool = False, transcript: Transcript | None = None, source_url: str = '', ad_url: str | None = None, has_audio_description: bool = False)[source]

Bases: JSONSerializable

VideoEmbedData dataclass

account_id: int
account_key: str
ad_enabled
ad_url: str | None = None
analytics_host: str
assets: list[EmbedAsset]
branding: bool
captions: list[EmbedCaption]
captions_enabled
created_at: datetime
distillery_url: str
duration: float
embed_options: Customizations
first_embed_for_account: bool
first_share_for_account: bool
flash_player_url: str
has_audio_description: bool = False
hashed_id: str
hls_enabled: bool = False
integrations: dict[str, str]
keyframe_align: bool
classmethod load_video(video_id: str) VideoEmbedData[source]

Retrieve video embed data from Wistia and return a new VideoEmbedData object.

media_id: int
media_key: str
media_type: str
name: str
num_captions
preload_preference: str
privacy_mode: bool
progress: float
project_id: int
seo_description: str
show_about: bool
source_url: str = ''
stats: EmbedStats
status: int
tracking_transmit_interval: int
transcript: Transcript | None = None
type: str
use_media_data_host_logic: bool
class wystia.models.VideoStats(id: int, hashed_id: str, name: str, stats: Stats)[source]

Bases: JSONSerializable

VideoStats dataclass

hashed_id: str
id: int
name: str
stats: Stats
class wystia.models.VideoThumbnail(on: bool, hashed_id: str, trim_start: int, trim_end: int, is_async: bool | None = None)[source]

Bases: object

VideoThumbnail dataclass

hashed_id: str
is_async: bool | None = None
on: bool
trim_end: int
trim_start: int

wystia.requests_config module

Config for retries using the requests library

wystia.requests_models module

class wystia.requests_models.SessionWithRetry(auth=None, num_retries=7, backoff_factor=1, additional_status_force_list: list[int] | None = None)[source]

Bases: Session

Extend the request.Session class to provide support for HTTP retries (in cases of timeout or other server-side errors)

wystia.requests_models.prefix_url_session(prefix: str, session=None) Session[source]

Returns a requests.Session object which makes all HTTP requests against a base API endpoint.

https://stackoverflow.com/a/53140699/10237506

Module contents

A Python wrapper library for the Wistia API

Docs:
wystia.WistiaApi

alias of WistiaDataApi

class wystia.WistiaDataApi[source]

Bases: _BaseWistiaApi

Helper class to interact with the Wistia Data API (docs below)

https://wistia.com/support/developers/data-api

Fully implements the following sections in the API documentation:

  • Paging and Sorting Responses

  • Projects

  • Medias

  • Customizations

  • Captions

classmethod copy_media(media_id: str, dest_project_id: str | None = None, owner: str | None = None) Media[source]
Copy a media, optionally to another project, via the Medias#copy API:

https://wistia.com/support/developers/data-api#medias_copy

Raises:
classmethod copy_project(project_id: str, admin_email: str | None = None) Project[source]

Copies an existing project in your account, including all media and sections, via the Projects:copy API:

classmethod copy_video(video_id: str, dest_project_id: str | None = None, owner: str | None = None, model_cls: type[T] = <class 'wystia.models.Video'>) T | Video[source]
Copy a video, optionally to another project, via the Medias#copy API:

https://wistia.com/support/developers/data-api#medias_copy

Raises:
classmethod create_captions(video_id: str, lang_code: LanguageCode | None = None, srt_contents: str | None = None, srt_file: str | None = None) None[source]

Create new captions for a given language on a Wistia video, via the Captions#create API:

Note that this always add new captions, regardless of whether captions already exist for the language. Please use update_captions() if we need to replace captions for a language instead.

Parameters:
  • video_id – The Wistia video to add the new captions for.

  • lang_code – An optional ISO-639–2 language code for the file. If left unspecified, the language code will be detected automatically.

  • srt_contents – The caption text in SRT format.

  • srt_file – The path to an SRT file.

Raises:

ContentIsEmpty – If one of srt_contents or srt_file is not provided.

classmethod create_customizations(video_id: str, customizations: Customizations) Customizations[source]

Overwrites the customizations for a video on Wistia, via the Customizations#create API:

Returns:

The new customizations on the video

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod create_project(project_name: str | None = None, admin_email: str | None = None, public_upload: bool | None = None, public_download: bool | None = None, public: bool | None = None) Project[source]
Create a new project in your account, via the Projects:create API:

https://wistia.com/support/developers/data-api#projects_create

classmethod delete_captions(video_id: str, lang_code: LanguageCode)[source]

Deletes the captions for a video on Wistia, via the Captions#delete API:

classmethod delete_customizations(video_id: str)[source]

Deletes the customizations for a video on Wistia, via the Customizations#delete API:

classmethod delete_media(media_id: str)[source]

Deletes a media (generally a video) from Wistia, via the Medias#delete API:

Returns:

A boolean indicating whether the video was successfully deleted.

classmethod delete_project(project_id: str)[source]
Delete a project in your account, via the Projects:delete API:

https://wistia.com/support/developers/data-api#projects_delete

Returns:

A boolean indicating whether the video was successfully deleted.

classmethod delete_video(media_id: str)

Deletes a media (generally a video) from Wistia, via the Medias#delete API:

Returns:

A boolean indicating whether the video was successfully deleted.

classmethod get_captions(video_id: str, lang_code: LanguageCode) VideoCaptions | None[source]

Retrieves the captions for a specific language on a Wistia video, via the Captions#show API:

The text of the captions will be in SRT format. If no captions exist for the specified language, a None value is returned.

classmethod get_customizations(video_id: str) Customizations[source]

Get customizations for a video on Wistia, via the Customizations#show API:

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod get_media(media_id: str) Media[source]
Get information on a Wistia media, via the Medias#show API:

https://wistia.com/support/developers/data-api#medias_show

Raises:

NoSuchMedia – If the media does not exist on Wistia

classmethod get_stats_for_video(video_id: str) VideoStats[source]

Get aggregated tracking stats on a Wistia video, via the Medias#stats API:

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod get_video(video_id: str, model_cls: type[T] = <class 'wystia.models.Video'>) T | Video[source]
Get information on a Wistia video, via the Medias#show API:

https://wistia.com/support/developers/data-api#medias_show

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod list_all_projects(sort_by: SortBy | None = None, sort_dir: SortDir | None = None, per_page=100) Container[Project][source]

Retrieve a list of Projects in the account, via the Projects:list API:

Defaults to sorting by Project ID. You can pass the`sort_by` argument to sort by another value.

Raises:

NoSuchProject – If the project does not exist on Wistia

classmethod list_captions(video_id: str) Container[VideoCaptions][source]

Retrieves all the captions on a Wistia video, via the Captions#index API:

The text of the captions will be in SRT format.

Raises:

NoSuchMedia – If the video does not exist on Wistia.

classmethod list_medias(project_id: str | None = None, media_name: str | None = None, media_type: MediaType | None = None, media_id: str | None = None, sort_by: SortBy | None = None, sort_dir: SortDir | None = None, model_cls: type[T] = <class 'wystia.models.Media'>) Container[T | Media][source]

Get all medias for a Wistia project or by other criteria, via the Medias#list API:

Defaults to sorting by Project ID. You can pass the`sort_by` argument to sort by another value.

Raises:

NoSuchProject – If the project does not exist on Wistia

classmethod list_project(project_id: str, sort_by: SortBy | None = None, sort_dir: SortDir | None = None, per_page=500, model_cls: type[T] = <class 'wystia.models.Media'>) Container[T | Media][source]

Get all medias (generally videos) for a Wistia project, via the Projects#show API:

Defaults to sorting by Project ID. You can pass the`sort_by` argument to sort by another value.

Raises:

NoSuchProject – If the project does not exist on Wistia

classmethod list_videos(project_id: str | None = None, video_name: str | None = None, media_type: MediaType | None = MediaType.VIDEO, video_id: str | None = None, sort_by: SortBy | None = None, sort_dir: SortDir | None = None) Container[Video][source]

Get all videos for a Wistia project or by other criteria, via the Medias#list API:

Defaults to sorting by Project ID. You can pass the`sort_by` argument to sort by another value.

Raises:

NoSuchProject – If the project does not exist on Wistia

classmethod order_captions(video_id: str, automated: bool = False, rush: bool = True, automatically_enable: bool = True) None[source]

Purchase English captions on a Wistia video, via the Captions#purchase API:

Parameters:
  • video_id – The hashed id of the video to order captions for.

  • automated – Set to true to order computer-generated captions ($0.25/minute) or false to order human-generated captions ($2.50/minute). Defaults to false.

  • rush – Set to true to enable a rush order (one business day turnaround, $4.00/minute), or false to retain the standard four business day turnaround for human-generated captions ($2.50/minute). Defaults to true.

  • automatically_enable – Set to true to automatically enable captions for the video as soon as the order is ready or false to hold the captions for review before manually enabling them. Defaults to true.

Raises:
classmethod update_captions(video_id: str, lang_code: LanguageCode, srt_contents: str | None = None, srt_file: str | None = None) None[source]

Replace captions for a given language on a Wistia video, via the Captions#update API:

Note: it is generally safer to call this method instead of create_captions(), which always adds new captions for a given language; this method falls back to create_captions() in case captions don’t exist for the specified language.

Parameters:
  • video_id – The Wistia video to add the new captions for.

  • lang_code – An ISO-639–2 language code for the file. If left unspecified, the language code will be detected automatically.

  • srt_contents – The caption text in SRT format.

  • srt_file – The path to an SRT file.

Raises:

ContentIsEmpty – If one of srt_contents or srt_file is not provided.

classmethod update_customizations(video_id: str, customizations: Customizations) Customizations[source]

Updates the customizations for a video on Wistia, via the Customizations#update API:

Returns:

The new customizations on the video

Raises:

NoSuchMedia – If the video does not exist on Wistia

classmethod update_media(media_id: str, media_name: str | None = None, media_desc: str | None = None, thumbnail_media_id: str | None = None, model_cls: type[T] = <class 'wystia.models.Media'>) T | Media[source]

Updates attributes on a media (generally a video), via the Medias#update API:

Parameters:
  • media_id – The hashed id of the media on Wistia.

  • media_name – An optional new name for the media.

  • media_desc – An optional new description for this media. Accepts plain text or markdown.

  • thumbnail_media_id – The Wistia hashed ID of an image that will replace the still that’s displayed before the player starts playing.

  • model_cls – The model class to load the response data into.

Raises:

NoSuchMedia – If the media does not exist on Wistia

classmethod update_project(project_id: str, project_name: str | None = None, public_upload: bool | None = None, public_download: bool | None = None, public: bool | None = None) Project[source]

Update an existing project in your account, via the Projects:update API:

classmethod update_video(video_id: str, video_name: str | None = None, video_desc: str | None = None, thumbnail_media_id: str | None = None) Video[source]
Updates attributes on a video, via the Medias#update API:

https://wistia.com/support/developers/data-api#medias_update

Parameters:
  • video_id – The hashed id of the video on Wistia.

  • video_name – An optional new name for the video.

  • video_desc – An optional new description for this video. Accepts plain text or markdown.

  • thumbnail_media_id – The Wistia hashed ID of an image that will replace the still that’s displayed before the player starts playing.

Raises:

NoSuchMedia – If the video does not exist on Wistia

class wystia.WistiaEmbedApi[source]

Bases: _BaseWistiaApi

Helper class to interact with the Wistia Media Embed API (docs below)

https://wistia.com/support/developers/embed-options

classmethod asset_url(video_id: str | None = None, media_data: VideoEmbedData | None = None, asset_type='original') str | None[source]

Get the media asset url stored on Wistia, by default for the “original” video.

Note: one of video_id or media_data must be specified.

Note that Wistia also has separate asset url’s for various resolutions on each video.

classmethod get_data(video_id: str) VideoEmbedData[source]

Get media embed data for a Wistia video using the endpoint to the .jsonp file

classmethod num_assets(video_id: str | None = None, media_data: VideoEmbedData | None = None, asset_type='mp4_alternate_audio') int[source]

Return the total number of assets (by default, AD files) associated with a Wistia video.

class wystia.WistiaHelper[source]

Bases: object

Helper class for interacting with Wistia API and Wistia videos, which further simplifies any calls. This assumes that WistiaApi has been configured as needed with the API token.

classmethod customize_video_on_wistia(video_id: str, player_color: str)[source]

Set commonly used customization options for a media on Wistia.

classmethod disable_captions_and_ad(video_id: str, on_by_default: bool = False)[source]

Disable captions and AD on a Wistia video.

classmethod enable_ad(video_id: str)[source]

Enable audio descriptions on a Wistia video.

classmethod enable_captions(video_id: str, on_by_default: bool = False)[source]

Enable captions on a Wistia video.

classmethod enable_captions_and_ad(video_id: str, on_by_default: bool = False)[source]

Enable captions and AD on a Wistia video.

classmethod has_captions_enabled(video_id: str) bool[source]

Check if a video has captions available in the player settings.

Returns:

A boolean indicating if the video player has captions available.

static is_archived_video(video_name: str) bool[source]

Check if this is an archived video which is automatically created by Wistia.

In that case, we shouldn’t order captions for it, since it’s a copy of a video that was replaced with new media.

Source: https://wistia.com/learn/product-updates/improved-library-management-tools # noqa: E501

classmethod project_details(project_id: str, projects: Container[Project] | None = None) Project[source]

Retrieve details on a Wistia project.

The optional parameter projects contains info on all projects in the Wistia account, such as a response from the Projects:list API.

Raises:

NoSuchProject – If the project doesn’t exist on Wistia

classmethod update_video_name(video_id: str, video_title: str) Video[source]

Update the title for a Wistia video.

classmethod video_exists(video_id: str) bool[source]

Check if a video exists on Wistia.

class wystia.WistiaUploadApi[source]

Bases: _BaseWistiaApi

Helper class to interact with the Wistia Upload API (docs below)

https://wistia.com/support/developers/upload-api

classmethod upload_file(file_path: str, project_id: str | None = None, title: str | None = None, description: str | None = None, contact_id: int | None = None, max_retries=5) UploadResponse[source]

Uploads a video file (given an absolute file path) to Wistia, and returns the hashed ID of the newly hosted video.

Docs:

https://wistia.com/support/developers/upload-api#the-request

Parameters:
  • file_path – The path of the video file to upload.

  • project_id – The hashed id of the project to upload media into. If omitted, a new project will be created and uploaded to.

  • title – Optional display name for the video. If omitted, the filename will be used instead.

  • description – Optional description for the video.

  • contact_id – A Wistia contact id, an integer value. If omitted, it will default to the contact_id of the account’s owner.

  • max_retries – Maximum number of retries, in case we run into a BrokenPipeError while uploading the video; defaults to 5.

Raises:

UploadFailed – In case the upload operation fails; also logs error details from the Upload API response.

Uploads a public video link to Wistia, and returns the hashed ID of the newly hosted video.

Docs:

https://wistia.com/support/developers/upload-api#the-request

Parameters:
  • url – A public, downloadable link for the video.

  • project_id – The hashed id of the project to upload media into. If omitted, a new project will be created and uploaded to.

  • title – Optional display name for the video. If omitted, the filename will be used instead.

  • description – Optional description for the video.

  • contact_id – A Wistia contact id, an integer value. If omitted, it will default to the contact_id of the account’s owner.

Raises:

UploadFailed – In case the upload operation fails; also logs error details from the Upload API response.