wystia 0.3.0

A Python wrapper library for the Wistia API

Wistia API Helper

A Python wrapper library for the Wistia API

• Free software: MIT license

• Documentation: https://wystia.readthedocs.io.

• Wistia Developer Docs: https://wistia.com/support/developers.

Usage

Sample usage with the Data API:

from wystia import WistiaDataApi
from wystia.models import SortBy, LanguageCode, VideoData

# Retrieve a list of all projects in the Wistia account,
# sorted A-Z and in ascending order.
projects = WistiaDataApi.list_all_projects(SortBy.NAME)
project_ids = [p['hashedId'] for p in projects]

# Retrieve a list of videos for a Wistia project.
# Note: If you don't require asset info (such as ADs) on each
#   video, I suggest calling `list_project` instead.
videos = WistiaDataApi.list_videos('project-id')

# Retrieve info on a particular video
video_dict = WistiaDataApi.get_video('video-id')
vd = VideoData(**video_dict)
# If the video has captions, that won't be included in the `Medias#show`
# response by default, so we'll need a separate API call as below.
# vd.process_captions(
#     WistiaDataApi.list_captions(real_video_id))
print(vd)

# Update attributes on a media (video), or set a custom thumbnail on the video.
WistiaDataApi.update_video(
    'video-id', thumbnail_media_id='uploaded-thumbnail-id')

# Get aggregated stats for a video, such as view count
stats = WistiaDataApi.get_stats_for_video('video-id')

# Retrieve the customization data for a video
customizations = WistiaDataApi.get_customizations('video-id')

# Update only specific customizations for a video
# Note the embed options are documented here:
#   https://wistia.com/support/developers/embed-options
WistiaDataApi.update_customizations('video-id',
                                    {'playerColor': '#e7fad1',
                                     # Hide comments on the media page
                                     'private': {'show_comments': 'false'}})

# Get the Spanish captions on a video
captions = WistiaDataApi.get_captions('video-id', LanguageCode.SPANISH)

# Add (or replace) the English captions on a video
WistiaDataApi.update_captions('video-id', LanguageCode.ENGLISH,
                              srt_file='path/to/file.srt')

… or to upload media via the Upload API:

from wystia import WistiaUploadApi

# Upload a file to a (default) project on Wistia
r = WistiaUploadApi.upload_file('path/to/my-file.mp4')
# Check if the video was successfully uploaded
# assert r.created
# assert r.name == 'my-file.mp4'

# Uploads with a public link to a video, such as
# an S3 pre-signed url.
r = WistiaUploadApi.upload_link('my-s3-link',
                                title='My Video Name',
                                description='My Description')

… you can alternatively retrieve asset info via the public Media Embed link:

from wystia import WistiaEmbedApi

# Get the media embed data
embed_data = WistiaEmbedApi.get_data('video-id')

# Retrieve the source URL of the original media
source_url = WistiaEmbedApi.asset_url(media_data=embed_data)

… when using the Data API, the WistiaHelper can help to further simplify some calls:

from wystia import WistiaHelper

# Check if the video exists in your Wistia account
assert WistiaHelper.video_exists('abc1234567')

# Check if a video's name indicates the video is an archived copy of an
# existing video, as discussed in the below article on replacing a media:
#   https://wistia.com/learn/product-updates/improved-library-management-tools
assert WistiaHelper.is_archived_video(
    'My Title [Archived on August 13, 2015]')

# Update the player color on a video
WistiaHelper.customize_video_on_wistia('video-id', 'ffffcc')

# Individually enable captions / AD in the player for a video
WistiaHelper.enable_ad('video-id')
WistiaHelper.enable_captions('video-id', on_by_default=False)

# Disable captions / AD in the player for a video
if WistiaHelper.has_captions_enabled('video-id'):
    print('Disabling captions and AD for the video')
    WistiaHelper.disable_captions_and_ad('video-id')

Installing Wystia and Supported Versions

The Wystia (Wistia helper) library is available on PyPI:

$ python -m pip install wystia

The wystia library officially supports Python 3.5 or higher.

Getting Started

Using the methods on the API classes assume your Wistia API token has previously been configured, for example via the environment. The API token will then be used globally by all the API classes when making requests to the Wistia API.

You can set the following environment variable with your API token:

• WISTIA_API_TOKEN

Another option is to use the global configure method as shown below:

WistiaDataApi.configure('MY-API-TOKEN')

Data API

The wrapper class WistiaDataApi interacts with the Wistia Data API (docs below):

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

It fully implements the following sections in the API documentation:

• Paging and Sorting Responses

• Projects

• Medias

• Customizations

• Captions

The following sections in the API have not been implemented (mainly as I haven’t used them before):

• Project Sharings

• Account

Tips

If you need to retrieve info on videos in a project and you don’t need complete info such as a list of assets for the video, I recommend using list_project instead of list_videos. This is because the Projects#show API returns up to 500 results per request, whereas the Medias#list only returns the default 100 results per page.

Assuming a project in your Wistia account has a total of about 250 media, here is the number of API calls you might expect from each individual approach:

from wystia import WistiaDataApi

videos = WistiaDataApi.list_videos('project-id')
assert WistiaDataApi.request_count() == 3

# Resets request count for the next call
WistiaDataApi.reset_request_count()

videos = WistiaDataApi.list_project('project-id')
assert WistiaDataApi.request_count() == 1

Thread Safety

The Wistia API classes are completely thread safe, since requests.Session objects are not re-used between API calls.

This means that if you have two (un-related) API operations to perform, such as updating a video’s title and adding captions on the video, then you can certainly run those calls in parallel so that they complete a bit faster.

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

History

0.3.0 (2021-07-21)

Features and Improvements

• Add compatibility changes to extend support to Python 3.5 and 3.6

• WistiaHelper: Add method project_details to retrieve info on a particular Wistia project

• WistiaEmbedApi: Update to parse the .json response rather than the .jsonp version

• Makefile: Add new command init, which can be used to install Dev dependencies for the project

  • Ensure the new command is compatible with Python 3.5, which has dependencies on separate package versions; here we should use requirements-py35-dev.txt instead.

• Makefile: Update coverage command to run unit tests by default

Bugfixes

• models.VideoData: The parameter to the process_captions method is now correctly type-annotated to accept a List of Dict

0.2.1 (2021-06-17)

• WistiaHelper: Add method enable_captions_and_ad

• Remove .format usage in log statements

• Remove an unnecessary method ad_needed from VideoData

• Update readme and Sphinx docs/

0.2.0 (2021-06-16)

• Fully implement all sections in the Wistia Data API

• Add more methods to the WistiaHelper class

• Request Count and API Token should now be globally shared by all API sub-classes

• Lot of code refactoring

• Exclude .mp4 files from dist, to reduce total package size

• Add more test cases

• Update docs with better examples

0.1.0 (2021-06-12)

• First release on PyPI.