pytvdbapi 0.5.0

A clean, resource friendly and easy to use API for thetvdb.com

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
[e-mail] 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.