API Design

I am starting to think that the current approach to implementing a Pythonic interface to the Brightcove API needs some rework. I started off just quickly ripping methods to match one for one with the published API, which is starting feel clunky and hard to use. Instead, I think the right approach is to think about the Python interface that would be useful and well designed and then work back towards making the appropriate HTTP calls.

Instead of working with the Connection object directly, it can always be passed into a Media API object to override the default instantiation (e.g. you didn’t have your account setup configured in a pybrightcove.cfg file in your /etc directory). However, by default, each object will create the required reference to the Connection object which really just abstracts and handles all communication to the Brightcove servers and returning structured responses.

Create a New Video

from pybrightcove import Video
v = Video(filename='/my/new/videofile.mov', 
            name="My New Video File", 
            short_description="My short description")
v.tags.append('cool')
v.tags.append('spring')
....  # And so on, setting all the optional properties you care about
v.save()
print v.id
3422523421342L

Check Upload Status of a Video

from pybrightcove import Video
v = Video(id=3422523421342L)  ## Implicit find by id done
print v.get_upload_status()
UPLOADING | PROCESSING | COMPLETE | ERROR   ## 4 possible values

Update an Existing Video

from pybrightcove import Video
v = Video(id=3422523421342L)  ## Implicit find by id done
v.tags.append('warm')
v.tags.append('may')
v.long_description = "This was previously not set but now it is."
v.save()
print v.tags
['cool', 'spring', 'warm', 'may']

Delete an Existing Video

from pybrightcove import Video
v = Video(id=3422523421342L)   ## Implicit find by id done
v.delete()

v = Video(reference_id='SOME REF ID')  ## Implicit find by reference id done
v.delete()

Sharing a Video

from pybrightcove import Video
v = Video(id=3422523421342L)   ## Implicit find by id done
v.share(accounts=[32342342, 234234234, 234234242], auto_accept=True)
print v.shared_video_ids
[2342342525L, 5235235252L, 2342342352L]  ## One video id for each account shared with

Adding or Updating an Image for a Video

from pybrightcove import Video
from pybrightcove import ImageType
v = Video(id=3422523421342L)   ## Implicit find by id done
v.add_image(filename='/mnt/path/to/image.png', 
        reference_id='image-one', 
        display_name='Image One', 
        ImageType.VIDEO_STILL)
v.update_image(remote_url='http://adifferentfile.com/image.png', 
        reference_id='image-one')

Finding Videos

from pybrightcove import Video
videoList = Video.find_by_tags(and_tags=['warm', 'may'])
videoList = Video.find_by_text('previously not set')
videoList = Video.find_by_campaign(3422552)
videoList = Video.find_by_user(11041241)
videoList = Video.find_by_reference_ids(['MY_REF_ID', 'Another Ref Id'])
videoList = Video.find_by_ids([342342342342L, 234234252532L, 2525253235232L])
videoList = Video.find_all()
video = Video(id=342345252522L)
videoList = video.find_related()

Create a Playlist

from pybrightcove import Playlist
from pybrightcove import PlaylistType
p = Playlist(name="My New Playlist", type=PlaylistType.EXPLICIT)
p.reference_id = "My Unique Identifier"
p.short_description = "A short description that will be truncated at 200 characters."
p.videos.append(v1)
p.videos.append(v2)
p.videos.append(vn)
p.save()
print p.id
2342345252L

Update an Existing Playlist

from pybrightcove import Playlist
p = Playlist(id=2342345252L)   ## Implicit find by id done
p.reference_id = "A New Identifier"
p.save()

Delete an Existing Playlist

from pybrightcove import Playlist
p = Playlist(id=2342345252L)   ## Implicit find by id done
p.delete()

p = Playlist(reference_id='A New Identifier')  ## Implicit find by reference id done
p.delete()

Finding Playlists

from pybrightcove import Playlist
playlistList = Playlist.find_by_ids([
        2342345252L, 
        2534234234L, 
        2342342342L])
playlistList = Playlist.find_by_reference_ids([
        'A New Identifier', 
        'Another Playlist Ref Id'])
playlistList = Playlist.find_by_player_id(2342342)
playlistList = Playlist.find_all()