=====
Usage
=====

To use Wistia API Helper in a project::

    from wystia import <API helper class>

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

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

.. code-block:: python3

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

Sample usage with the `Data API <https://wistia.com/support/developers/data-api>`_:

.. code-block:: python3

    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)
    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
    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 <https://wistia.com/support/developers/upload-api>`_:

.. code-block:: python3

    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:

.. code-block:: python3

    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:

.. code-block:: python3

    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')
