Package: opensubtitlescom
Python OpenSubtitles.com API WrapperA Python wrapper for the OpenSubtitles REST API, providing easy access to subtitle data.
This library allows you to interact with OpenSubtitles.com programmatically,
making it simple to search for and download subtitles for your favorite movies and TV shows.InstallationYou can install the package usingpipdirectly from PyPI or by cloning the repository from GitHub.Install from PyPI:pipinstallopensubtitlescomInstall from GitHub (latest development version):pipinstallgit+ssh://git@github.com/dusking/opensubtitles-com.git--upgradeUsageUsing this wrapper is straightforward.
It follows the OpenSubtitles API documentation closely and converts responses into Python objects.
Here's an example of how to use it:fromopensubtitlescomimportOpenSubtitles# Initialize the OpenSubtitles clientsubtitles=OpenSubtitles(MY_API_KEY,"MyApp v1.0.0")# Log in (retrieve auth token)subtitles.login(MY_USERNAME,MY_PASSWORD)# Search for subtitlesresponse=subtitles.search(query="breaking bad",season_number=1,episode_number=1,languages="en")# Convert the response to a Python dictionaryresponse_dict=response.to_dict()print(response_dict)# Convert the response to a Json formatresponse_json=response.to_json()print(response_json)# Get first response subtitlessrt=subtitles.download_and_parse(response.data[0])Here's another simple example:# Get latest uploaded subtitleslatest_uploads=subtitles.discover_latest()# Convert the response to a Python dictionarylatest_uploads_dict=latest_uploads.to_dict()For more information on available methods and options,
refer to theOpenSubtitles API documentation.Using the CLIThe library is accessible through the CLI, offering various options.
To view all available commands, use the following:$>ost-h
positionalarguments:{set-cred,show-cred,search,download}set-credSettheusernameandpasswordintheconfigfile.show-credShowtheusernameandpasswordintheconfigfile.searchSearchforsubtitlesbyvariouscriteria.downloadDownloadasubtitlebyfile-idormovie-hash.

optionalarguments:-h,--helpshowthishelpmessageandexit--configCONFIGPathtotheconfigurationfile-v,--verboseIncreaseverbositylevelBefore executing CLI commands, set your opensubtitles user credentials using the set-cred command:$>ostset-cred
Enteryourusername(leaveblanktokeepexisting):
Enteryourpassword(leaveblanktokeepexisting):
CredentialssetsuccessfullyCredentials are stored in the configuration file.
Now you can use CLI commands. For instance, to search for subtitles:$>ostsearch--query"The Matrix"+----+---------------------------+----------+---------+------------------------------------------------------------------------+|#  | title                     | imdb-id  | file-id | file-name                                                              |+----+---------------------------+----------+---------+------------------------------------------------------------------------+|1|TheMatrix|133093|4461104|The.Matrix.1999.720p.HDDVD.DTS.x264-ESiR.ENG||2|TheMatrix|133093|4477776|The.Matrix.1999.Subtitles.YIFY||3|TheMatrix|133093|4465191|The.Matrix.1999.BluRay.1080p.x264.DTS-WiKi.ENG||4|TheMatrix|133093|4483524|The.Matrix.1999.1080p.BrRip.x264.YIFY.en||5|TheMatrix|133093|4480638|The.Matrix.1999.1080p.BluRay.x264-CtrlHD.eng-sdh|To download subtitles, use the download command with the specified file-id:$>ostdownload--file-id4461104You can easily download subtitles for a local file using the CLI.
The command will automatically search for the hash and download the first result. For example:$>ostdownload--filemymovie.mp4This command will download the subtitle for "mymovie.mp4" and save it as "mymovie.srt".Running TestsTo execute the unit tests, use the following command:$ python -m unittestMake sure you have the necessary dependencies installed and a valid Python environment set up before running the tests.ContributingContributions to this project are welcome. If you'd like to contribute, please follow these guidelines:Open an issue to discuss your proposed changes before submitting a pull request.Ensure that your code adheres to the project's coding standards.Write tests for your code and make sure existing tests pass.Document your changes thoroughly, including updating this README if necessary.Thank you for your interest in improving this project!