A clean, resource friendly and easy to use API for thetvdb.com
Project description
About
pytvdbapi is a python API for thetvdb.com online database for tv-shows. The API is designed to be as easy and intuitive as possible to use.
The API is designed to respect the functionality of thetvdb.com as far as possible. It uses caching as much as possible to reduce the workload of the servers.
Key Features
A clean and easy to use interface
A well documented API
Support for Python 3.2
Thoroughly tested against all supported platforms. Tests covering ~97% of the code base.
Continuously tested against PEP8 and pylint.
Dependencies
pytvdbapi depends on the following packages to function.
Install
The easiest and recommended way to install pytvdbapi is to use pip:
$pip install pytvdbapi
Or you can download the desired version from https://github.com/fuzzycode/pytvdbapi/downloads/ and unpack it and execute:
$cd pytvdbapi/ $python setup.py install
Depending on your platform, you may need root permission to execute the above commands.
To get the latest development version you can install directly from source. Note that no guaranties are made as to the stability of the source tree:
$pip install git+git://github.com/fuzzycode/pytvdbapi.git
ArchLinux
Tobias Röttger is kindly maintaining an ArchLinux package of pytvdbapi that can be found at https://aur.archlinux.org/packages.php?ID=58697.
Usage
To use the API you should apply for an API key for your particular application. An API key can be obtained for free from thetvdb.com. Note that the key used in the examples is only intended for testing purposes and should not be used for other purposes.
To search for a specific show:
>>> from pytvdbapi import api >>> db = api.TVDB("B43FF87DE395DF56") >>> search = db.search("How I met your mother", "en") >>> len(search) 1 >>> show = search[0] >>> show.SeriesName 'How I Met Your Mother'
You can index individual seasons and individual episodes using convenient indexing:
>>> from pytvdbapi import api >>> db = api.TVDB("B43FF87DE395DF56") >>> search = db.search("How I met your mother", "en") >>> show = search[0] >>> show[1] <Season 001> >>> show[1][4] <Episode S001E004 - Return of the Shirt>
To list all episodes of a show:
>>> from pytvdbapi import api >>> db = api.TVDB("B43FF87DE395DF56") >>> search = db.search("How I met your mother", "en") >>> show = search[0] >>> for season in show: ... for episode in season: ... print(episode) #doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE ... <Episode S000E001 - Robin Sparkles Music Video - Let's Go to the Mall> <Episode S000E002 - Robin Sparkles Music Video - Sandcastles In the Sand> <Episode S000E003 - Marshall's Music Video - You Just Got Slapped> <Episode S000E004 - Lily and Marshall's Honeymoon Videos> <Episode S000E005 - Barney Stinson's Video Resume> <Episode S000E006 - Nothing Suits Me Like A Suit> <Episode S000E007 - A Night With Your Mother Panel Discussion> <Episode S000E008 - The Beaver Song> <Episode S000E009 - Best Night Ever> <Episode S000E010 - Best Night Ever: Behind the Scenes> <Episode S001E001 - Pilot> <Episode S001E002 - Purple Giraffe> ... ... <Episode S007E010 - Tick Tick Tick...> <Episode S007E011 - The Rebound Girl> <Episode S007E012 - Symphony of Illumination> ...
Testing
Testing pytvdbapi is really easy, just type the following from the package root folder:
$ python setup.py test
If all turns out all right you should see a nice and happy OK at the end.
Documentation
The documentation for pytvdbapi is hosted at http://packages.python.org/pytvdbapi/. It also comes with a version of the documentation included in docs/build/html/.
Known Issues
At the moment, pytvdbapi only works with Python 2.6, 2.7 and 3.2, NOT 3.0 or 3.1. This is due to an issue with httplib2 on Python 3.0, 3.1.
pytvdbapi does currently NOT support the use of Proxy Servers.
Bugs
If you find any bug or want to request a new feature to the API please use the issue tracker associated with the project.
Try to be as detailed as possible when filing a bug, preferably providing a patch or a test case illustrating the issue.
Contact
To get in contact with me, you can send me an email at develop@bjornlarsson.net or you can follow me on twitter @fuzzycode
CHANGELOG
2012-06-29, 0.3.0
Added Actor objects to contain extended actor data
Added Banner objects to contain extended banner data
Added a get() function to access a show directly using the show id.
Updated the status to Alpha
2012-04-16, 0.2.3
Fixed an issue with missing data folder in package
2012-01-05, 0.2.2
Updated author name to avoid unicode issues
Improved the documentation
2011-12-17, 0.2.1
Updated test coverage
Made the source code PEP8 and Pylint compatible
Updated documentation and prepared for PyPI release
2011-12-07, 0.2.0
Updated to support Python 2.6, 2.7 and 3.2
Made the interfaces cleaner by using collections.Mapping
2011-11-29, 0.1.1
Renamed the package to pytvdbapi to avoid any confusion with the official thetvdb.com service.
Updated the setup.py to use setuptools if available
2011-11-28, 0.1.0
Initial alpha release of the package.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.