A clean, resource friendly and easy to use API for thetvdb.com
Project description
pytvdbapi - A python API for thetvdb.com
========================================
|statusimage| |coverageimage| |pypiimage|
**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.
Key Features
------------
* A clean and easy to use interface
* A well documented API
* Support for Python 2.6, 2.7, 3.3 and 3.4
* Thoroughly tested against all supported versions.
Dependencies
============
**pytvdbapi** depends on the following packages to function.
* `httplib2 <http://code.google.com/p/httplib2/>`_
Install
=======
The easiest and recommended way to install **pytvdbapi** is to use pip_::
$pip install pytvdbapi
Depending on your platform, you may need root permission to execute the above
commands.
ArchLinux
----------
Tobias Röttger is kindly maintaining an ArchLinux package of **pytvdbapi** that
can be found `here <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_. These are some of the things you
can do with **pytvdbapi**.
Create a db instance::
>>> from pytvdbapi import api
>>> db = api.TVDB('B43FF87DE395DF56')
Search for a show name::
>>> result = db.search('Dexter', 'en')
>>> len(result)
1
Obtain a show instance and access the data::
>>> show = result[0]
>>> print(show.SeriesName)
Dexter
>>> len(show) # List the number of seasons of the show, season 0 is the specials season
9
Access individual seasons::
>>> season = show[1]
>>> len(season) # List the number of episodes in the season, they start at index 1
12
>>> print(season.season_number)
1
Access an episode within the season::
>>> episode = season[2]
>>> print(episode.EpisodeNumber)
2
>>> print(episode.EpisodeName)
Crocodile
Documentation
=============
The documentation for **pytvdbapi** is hosted at http://packages.python.org/pytvdbapi/ and there is a
version over at `Readthedocs <http://pytvdbapi.readthedocs.org/en/latest/>`__.
Known Issues
============
* **pytvdbapi** only works with Python 2.6, 2.7, 3.3 and 3.4
**NOT 3.0, 3.1 or 3.2**.
* **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 <https://github.com/fuzzycode/pytvdbapi/issues>`_
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 <https://twitter.com/#!/fuzzycode>`__
License
=======
**pytvdbapi** is released under the `LGPL 3 <http://opensource.org/licenses/LGPL-3.0>`__ license. See the
LICENSE.txt file for more details.
.. |statusimage| image:: https://travis-ci.org/fuzzycode/pytvdbapi.png?branch=master
:target: https://travis-ci.org/fuzzycode/pytvdbapi
.. |coverageimage| image:: https://coveralls.io/repos/fuzzycode/pytvdbapi/badge.png
:target: https://coveralls.io/r/fuzzycode/pytvdbapi
.. |pypiimage| image:: https://pypip.in/v/pytvdbapi/badge.png
:target: https://crate.io/packages/pytvdbapi/
.. _thetvdb.com: http://thetvdb.com
.. _PyPI: http://pypi.python.org/pypi
.. _pip: https://pip.pypa.io/en/latest/index.html
CHANGELOG
=========
2014-10-28, 0.5.0
-----------------
* Added find and filter functions to the Show and Season classes to allow searching for specific
episodes.
* Added get_episode_by_air_date function to search for an episode by air date for a given series
* Update the get_episode function to allow downloading using *default*, *dvd* or *absolute* sort order.
* Update the get_series function to allow getting a series using imdb id and zap2it id.
* Speed up load times when downloading data
* Use zip format for retrieving series data.
* Bug fixes and code clean-up
2013-11-22, 0.4.0
-----------------
* Removed support for Python 3.2
* Improved unicode support
* Improved compatibility with standard Python functions like *hasattr()* and *getattr()*
* Show, Season, Episode, Actor and Banner instances can now be pickled
* Added the get_episode() function to access an episode directly using the episode id.
* Added the option *ignore_case* to be able to access the attributes in a case insensitive manner.
* Added the *load_actors* and *load_banners* functions to load actors and banners on individual shows
* Fixed broken unit tests and improved test stability
* Bug fixes and code clean-up
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.
========================================
|statusimage| |coverageimage| |pypiimage|
**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.
Key Features
------------
* A clean and easy to use interface
* A well documented API
* Support for Python 2.6, 2.7, 3.3 and 3.4
* Thoroughly tested against all supported versions.
Dependencies
============
**pytvdbapi** depends on the following packages to function.
* `httplib2 <http://code.google.com/p/httplib2/>`_
Install
=======
The easiest and recommended way to install **pytvdbapi** is to use pip_::
$pip install pytvdbapi
Depending on your platform, you may need root permission to execute the above
commands.
ArchLinux
----------
Tobias Röttger is kindly maintaining an ArchLinux package of **pytvdbapi** that
can be found `here <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_. These are some of the things you
can do with **pytvdbapi**.
Create a db instance::
>>> from pytvdbapi import api
>>> db = api.TVDB('B43FF87DE395DF56')
Search for a show name::
>>> result = db.search('Dexter', 'en')
>>> len(result)
1
Obtain a show instance and access the data::
>>> show = result[0]
>>> print(show.SeriesName)
Dexter
>>> len(show) # List the number of seasons of the show, season 0 is the specials season
9
Access individual seasons::
>>> season = show[1]
>>> len(season) # List the number of episodes in the season, they start at index 1
12
>>> print(season.season_number)
1
Access an episode within the season::
>>> episode = season[2]
>>> print(episode.EpisodeNumber)
2
>>> print(episode.EpisodeName)
Crocodile
Documentation
=============
The documentation for **pytvdbapi** is hosted at http://packages.python.org/pytvdbapi/ and there is a
version over at `Readthedocs <http://pytvdbapi.readthedocs.org/en/latest/>`__.
Known Issues
============
* **pytvdbapi** only works with Python 2.6, 2.7, 3.3 and 3.4
**NOT 3.0, 3.1 or 3.2**.
* **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 <https://github.com/fuzzycode/pytvdbapi/issues>`_
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 <https://twitter.com/#!/fuzzycode>`__
License
=======
**pytvdbapi** is released under the `LGPL 3 <http://opensource.org/licenses/LGPL-3.0>`__ license. See the
LICENSE.txt file for more details.
.. |statusimage| image:: https://travis-ci.org/fuzzycode/pytvdbapi.png?branch=master
:target: https://travis-ci.org/fuzzycode/pytvdbapi
.. |coverageimage| image:: https://coveralls.io/repos/fuzzycode/pytvdbapi/badge.png
:target: https://coveralls.io/r/fuzzycode/pytvdbapi
.. |pypiimage| image:: https://pypip.in/v/pytvdbapi/badge.png
:target: https://crate.io/packages/pytvdbapi/
.. _thetvdb.com: http://thetvdb.com
.. _PyPI: http://pypi.python.org/pypi
.. _pip: https://pip.pypa.io/en/latest/index.html
CHANGELOG
=========
2014-10-28, 0.5.0
-----------------
* Added find and filter functions to the Show and Season classes to allow searching for specific
episodes.
* Added get_episode_by_air_date function to search for an episode by air date for a given series
* Update the get_episode function to allow downloading using *default*, *dvd* or *absolute* sort order.
* Update the get_series function to allow getting a series using imdb id and zap2it id.
* Speed up load times when downloading data
* Use zip format for retrieving series data.
* Bug fixes and code clean-up
2013-11-22, 0.4.0
-----------------
* Removed support for Python 3.2
* Improved unicode support
* Improved compatibility with standard Python functions like *hasattr()* and *getattr()*
* Show, Season, Episode, Actor and Banner instances can now be pickled
* Added the get_episode() function to access an episode directly using the episode id.
* Added the option *ignore_case* to be able to access the attributes in a case insensitive manner.
* Added the *load_actors* and *load_banners* functions to load actors and banners on individual shows
* Fixed broken unit tests and improved test stability
* Bug fixes and code clean-up
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.
