A Python wrapper library for the Wistia API
Wystia - Wistia API Helper
A Python wrapper library for the Wistia API
Free software: MIT license
Wistia Developer Docs: https://wistia.com/support/developers.
The Wystia library is available on PyPI, and can be installed with pip:
$ pip install wystia
You’ll also need to create an access token as outlined in the docs.
Sample usage with the Data API:
Note: The following example makes use of WistiaApi, which is an alias to the class WistiaDataApi.
from wystia import WistiaApi from wystia.models import SortBy, LanguageCode, Customizations, Private # Setup the Wistia API token to use for requests. You can alternatively # set this via the env variable 'WISTIA_API_TOKEN'. WistiaApi.configure('MY-TOKEN') # Retrieve a list of all projects in the Wistia account, # sorted A-Z and in ascending order. projects = WistiaApi.list_all_projects(SortBy.NAME) project_ids = [p.hashed_id for p in projects] # Print the project data as a prettified JSON string print(projects.prettify()) # 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 = WistiaApi.list_videos('project-id') # Retrieve info on a particular video vd = WistiaApi.get_video('video-id') # 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( # WistiaApi.list_captions(real_video_id)) print(vd) # Update attributes on a media (video), or set a custom thumbnail on the video. WistiaApi.update_video( 'video-id', thumbnail_media_id='uploaded-thumbnail-id' ) # Get aggregated stats for a video, such as view count stats = WistiaApi.get_stats_for_video('video-id') # Retrieve the customization data for a video customizations = WistiaApi.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 sample_embed_options = Customizations( player_color='#e7fad1', # Hide comments on the media page private=Private(show_comments=False) ) WistiaApi.update_customizations('video-id', sample_embed_options) # Get the Spanish captions on a video captions = WistiaApi.get_captions('video-id', LanguageCode.SPANISH) # Add (or replace) the English captions on a video WistiaApi.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')
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:
Another option is to use the global configure method as shown below:
There is additionally a Quickstart section in the docs which walks through - in more detail - how to get up and running with the Wystia library.
The wrapper class WistiaDataApi (aliased to WistiaApi) interacts with the Wistia Data API (docs below):
It fully implements the following sections in the API documentation:
Paging and Sorting Responses
The following sections in the API have not been implemented (mainly as I haven’t used them before):
In general, the API methods that begin with list - such as list_project - will return a Container object, which essentially acts as a thin wrapper around a collection of model classes. For all intents and purposes, this behaves exactly the same as a list object.
One of the main benefits is that it implements a __str__ method, which leverages the builtin pprint module in Python to pretty-print the Python object representation of each model or dataclass instance; this will format the output more nicely, for example whenever print(obj) is called on the Container result.
The Container objects also implement the following convenience methods, which can be used to easily display the JSON string representation of the list of dataclass instances:
to_json - Convert the list of instances to a JSON string.
prettify - Convert the list of instances to a prettified JSON string.
List Medias in a Project
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
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.
Refactor any model classes that would be returned in list API calls to subclass from JSONListWizard instead of JSONWizard, simply so that Container objects will be returned by default.
Refactor to import Container from the dataclass-wizard library instead. For backwards compatibility reasons, the models module still exports the Container namespace.
Wystia has officially dropped support for Python versions 3.5 and 3.6. The support for 3.6 needed to be dropped primarily because of the from __future__ import annotations usage in the code.
Refactored all API helper classes to return model class objects as a result, rather than Python dict objects. In the case of any list- related API responses, we now return a Container object so that it can be easier to print or display the result for debugging purposes.
All inputs to the API helper methods that previously accepted a dict object, have in general been refactored to accept a model dataclass instance as an input instead.
Renamed some error classes; for example, NoSuchMedia instead of NoSuchVideo.
Renamed some model classes; for example, MediaStatus instead of VideoStatus.
Features and Improvements
Added WistiaApi to the list of public exports, which is aliased to the WistiaDataApi helper class.
Added new methods to the WistiaDataApi class for more explicitly interacting with medias instead of videos. For example, a list_medias method is added as an alternative to calling list_videos.
Refactored the CI process to use GitHub Workflows instead of Travis CI.
Added 3.10 to the list of supported Python versions.
Updated the project status from Beta to Production/Stable.
Added an examples/ folder in the project repo on GitHub, which contains Python scripts to demonstrate sample usage.
Updated docs and added a new Quickstart section.
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
models.VideoData: The parameter to the process_captions method is now correctly type-annotated to accept a List of Dict
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/
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
First release on PyPI.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Hashes for wystia-1.1.0-py2.py3-none-any.whl