python-opensubtitles

Simple module to access to the OpenSubtitles.org subtitles database. This class is a wrapper to the common methods at OS.

Configuring the test environment

Before start to running the test (if you are only reading the documentation, of course, you don't need to do it :D) you must provide a correct video path and subtitle path.

>>> from os import path
>>> class Test(object):
...     username = 'doctest'
...     password = 'doctest'
...     # Remember to change the video path if you want to run the test!
...     name = 'Dark City'
...     path = ('/home/alex/Videos/'
...             'Dark.City.1998.Directors.Cut.BRRip.H264.AAC.5.1ch.Gopo/')
...     video = 'Dark.City.1998.Directors.Cut.BRRip.H264.AAC.5.1ch.Gopo.mp4'
...     subtitle = 'Dark.City.1998.Directors.Cut.BRRip.H264.AAC.5.1ch.Gopo.srt'

First steps

Typicall import and creation of the OpenSubitles wrapper.

>>> from pythonopensubtitles.opensubtitles import OpenSubtitles
>>> os = OpenSubtitles()

Login

To most of the OpenSubtitles methods you must send a token, this token is given to you by the api after the use of the login method.

>>> token = os.login('[email protected]', 'badpassword')
>>> assert token == None
>>> token = os.login(Test.username, Test.password)
>>> assert type(token) == str

This token will be saved as an attrib of the OpenSubtitle class, so you don't need to send it always to the methods.

Creating a video hash

To search subtitles, upload subtitles... a video hash token must be provided. You can find a generator under this module utils.

>>> from pythonopensubtitles.utils import File
>>> f = File(path.join(Test.path, Test.video))
>>> hash = f.get_hash()
>>> assert type(hash) == str

Getting video size

>>> size = f.size
>>> assert type(size) == long

Search subtitles

If you search for a subtitle you will receive a list of all the subtitles saved at server.

>>> data = os.search_subtitles([{'sublanguageid': 'all', 'moviehash': hash, 'moviebytesize': size}])
>>> assert type(data) == list

Getting the IMDB id

The info that you got on the method above provides you a imdb id, you must get it to try to upload subtitles.

>>> imdb_id = int(data[0].get('IDMovieImdb'))
>>> assert type(imdb_id) == int

Search a movie at IMDB

If you don't know the imdb (perhaps the film is very new and it doesn't have subtitles yet), you can search it providing the film name.

>>> data = os.search_movies_on_imdb(Test.name)
>>> assert type(data) == dict

Get MD5 from a subtitle

To know if the subtitle was uploaded correctly, a md5 of the file must be provided.

>>> from pythonopensubtitles.utils import get_md5
>>> md5 = get_md5(path.join(Test.path, Test.subtitle))
>>> assert type(md5) == str

Try to upload subtitles

Before upload a subtitle you always need to check if it exists on the database:

>>> params = [{'cd1': [{'submd5hash': md5,
...                     'subfilename': Test.subtitle,
...                     'moviehash': hash,
...                     'moviebytesize': size}]}]
>>> already_in_db = os.try_upload_subtitles(params)
>>> assert type(already_in_db) == bool

Upload subtitles

If the subtitle isn't on the database yet, you can upload it with the method upload_subtitles.

You can take the cd1 params from the method above, but for the documentation is more clear do it this way:

>>> from pythonopensubtitles.utils import get_gzip_base64_encoded
>>> if not already_in_db:
...     params = {'baseinfo': {
...                   'idmovieimdb': imdb_id},
...               'cd1': {
...                   'subhash': md5,
...                   'subfilename': Test.subtitle,
...                   'moviehash': hash,
...                   'moviebytesize': size,
...                   'moviefilename': Test.video,
...                   'subcontent': get_gzip_base64_encoded(path.join(Test.path, Test.subtitle))}}
...     url = os.upload_subtitles(params)
...     assert type(url) == str

Ping the server

Each 15 minutes you need to ping the server to show that you are alive. To do it use the metho no_operation:

>>> os.no_operation()
True

Auto update

Get info of the last version of one of the porgrams at OpenSubtitiles DB.

>>> data = os.auto_update('SubDownloader')
>>> assert 'version' in data.keys()

Logout

You can remove your session token with this method:

>>> os.logout()
True