{"id":20033144,"url":"https://github.com/dbr/tvdb_api","last_synced_at":"2025-05-16T14:05:26.033Z","repository":{"id":396600,"uuid":"14645","full_name":"dbr/tvdb_api","owner":"dbr","description":"Simple to use interface to TheTVDB.com API in Python","archived":false,"fork":false,"pushed_at":"2024-06-24T18:34:33.000Z","size":2288,"stargazers_count":339,"open_issues_count":17,"forks_count":65,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-19T16:26:33.699Z","etag":null,"topics":["api-wrapper","tvdb"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2008-05-05T13:01:53.000Z","updated_at":"2025-01-15T09:47:37.000Z","dependencies_parsed_at":"2022-07-16T14:30:57.186Z","dependency_job_id":"8c5780c0-d39f-42d4-8326-5d568dc08fc2","html_url":"https://github.com/dbr/tvdb_api","commit_stats":{"total_commits":547,"total_committers":22,"mean_commits":"24.863636363636363","dds":0.07495429616087756,"last_synced_commit":"ce0382181a9e08a5113bfee0fed2c78f8b1e613f"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbr%2Ftvdb_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbr%2Ftvdb_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbr%2Ftvdb_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbr%2Ftvdb_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbr","download_url":"https://codeload.github.com/dbr/tvdb_api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253736100,"owners_count":21955786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","tvdb"],"created_at":"2024-11-13T09:44:38.367Z","updated_at":"2025-05-16T14:05:26.012Z","avatar_url":"https://github.com/dbr.png","language":"Python","readme":"# `tvdb_api`\n[![PyPI][pypi-img]][pypi-link] [![Build Status][travis-img]][travis-link] [![codecov][coverage-img]][coverage-link]\n\n`tvdb_api` is an easy to use interface to [thetvdb.com][tvdb]\n\nIt supports Python 2.7, and 3.5 onwards\n\n`tvnamer` has moved to a separate repository: [github.com/dbr/tvnamer][tvnamer] - it is a utility which uses `tvdb_api` to rename files from `some.show.s01e03.blah.abc.avi` to `Some Show - [01x03] - The Episode Name.avi` (which works by getting the episode name from `tvdb_api`)\n\n\n[tvdb]: http://thetvdb.com\n[tvnamer]: http://github.com/dbr/tvnamer\n[travis-link]: https://travis-ci.com/dbr/tvdb_api\n[travis-img]: https://travis-ci.com/dbr/tvdb_api.svg?branch=master\n[pypi-link]: https://pypi.org/project/tvdb-api/\n[pypi-img]: https://img.shields.io/pypi/v/tvdb_api\n[coverage-link]: https://codecov.io/gh/dbr/tvdb_api\n[coverage-img]: https://codecov.io/gh/dbr/tvdb_api/branch/master/graph/badge.svg\n\n\n## To install\n\nYou can easily install `tvdb_api` via `pip`\n\n    pip install --upgrade tvdb_api\n\nYou may need to use sudo, depending on your setup:\n\n    sudo pip install --upgrade tvdb_api\n\n## Basic usage\n\nFirst initialise an instance of the `Tvdb` class with your API key:\n\n    import tvdb_api\n    t = tvdb_api.Tvdb() \n\nNote you must specify the apikey argument here, for example:\n\n    t = Tvdb(apikey=\"ENTER YOUR API KEY HERE\") # doctest:+SKIP\n\nSee https://thetvdb.com/api-information to register a key.\n\nThen to use the API:\n\n    episode = t['My Name Is Earl'][1][3] # get season 1, episode 3 of show\n    print episode['episodename'] # Print episode name\n\n## Registering an API key\n\nYou must have an API key from \u003chttp://thetvdb.com\u003e in order to use this module.\n\nRegistering for a key is easy to do and can be done within a few minutes - see the following page for details:\n\n\u003chttps://thetvdb.com/api-information\u003e\n\nNote: In `tvdb_api` v2 a default key was included for convenience. However over time this key became very heavily used and this causes problems for TheTVDB.com admins. This old shared key will be deprecated and removed at some point soon.\n\n## Advanced usage\n\nMost of the documentation is in docstrings. The examples are tested (using doctest) so will always be up to date and working.\n\nThe docstring for `Tvdb.__init__` lists all initialisation arguments, including support for non-English searches, custom \"Select Series\" interfaces and enabling the retrieval of banners and extended actor information. You can also override the default API key using `apikey`, recommended if you're using `tvdb_api` in a larger script or application\n\n### Exceptions\n\nThere are several exceptions you may catch, these can be imported from `tvdb_api`:\n\n- `tvdb_error` - this is raised when there is an error communicating with [thetvdb.com][tvdb] (a network error most commonly)\n- `tvdb_userabort` - raised when a user aborts the Select Series dialog (by `ctrl+c`, or entering `q`)\n- `tvdb_shownotfound` - raised when `t['show name']` cannot find anything\n- `tvdb_seasonnotfound` - raised when the requested series (`t['show name][99]`) does not exist\n- `tvdb_episodenotfound` - raised when the requested episode (`t['show name][1][99]`) does not exist.\n- `tvdb_attributenotfound` - raised when the requested attribute is not found (`t['show name']['an attribute']`, `t['show name'][1]['an attribute']`, or ``t['show name'][1][1]['an attribute']``)\n\n### Series data\n\nAll data exposed by [thetvdb.com][tvdb] is accessible via the `Show` class. A Show is retrieved by doing..\n\n    \u003e\u003e\u003e import tvdb_api\n    \u003e\u003e\u003e t = tvdb_api.Tvdb()\n    \u003e\u003e\u003e show = t['scrubs']\n    \u003e\u003e\u003e type(show)\n    \u003cclass 'tvdb_api.Show'\u003e\n\nFor example, to find out what network Scrubs is aired:\n\n    \u003e\u003e\u003e t['scrubs']['network']\n    u'ABC'\n\nThe data is stored in an attribute named `data`, within the Show instance:\n\n    \u003e\u003e\u003e t['scrubs'].data.keys()\n    ['networkid', 'rating', 'airs_dayofweek', 'contentrating', 'seriesname', 'id', 'airs_time', 'network', 'fanart', 'lastupdated', 'actors', 'ratingcount', 'status', 'added', 'poster', 'tms_wanted_old', 'imdb_id', 'genre', 'banner', 'seriesid', 'language', 'zap2it_id', 'addedby', 'firstaired', 'runtime', 'overview']\n\nAlthough each element is also accessible via `t['scrubs']` for ease-of-use:\n\n    \u003e\u003e\u003e t['scrubs']['rating']\n    u'9.0'\n\nThis is the recommended way of retrieving \"one-off\" data (for example, if you are only interested in \"seriesname\"). If you wish to iterate over all data, or check if a particular show has a specific piece of data, use the `data` attribute,\n\n    \u003e\u003e\u003e 'rating' in t['scrubs'].data\n    True\n\n### Banners and actors\n\nSince banners and actors are separate XML files, retrieving them by default is undesirable. If you wish to retrieve banners (and other fanart), use the `banners` Tvdb initialisation argument:\n\n    \u003e\u003e\u003e from tvdb_api import Tvdb\n    \u003e\u003e\u003e t = Tvdb(banners = True)\n\nThen access the data using a `Show`'s `_banner` key:\n\n    \u003e\u003e\u003e t['scrubs']['_banners'].keys()\n    ['fanart', 'poster', 'series', 'season']\n\nThe banner data structure will be improved in future versions.\n\nExtended actor data is accessible similarly:\n\n    \u003e\u003e\u003e t = Tvdb(actors = True)\n    \u003e\u003e\u003e actors = t['scrubs']['_actors']\n    \u003e\u003e\u003e actors[0]\n    \u003cActor \"Zach Braff\"\u003e\n    \u003e\u003e\u003e actors[0].keys()\n    ['sortorder', 'image', 'role', 'id', 'name']\n    \u003e\u003e\u003e actors[0]['role']\n    u'Dr. John Michael \"J.D.\" Dorian'\n\nRemember a simple list of actors is accessible via the default Show data:\n\n    \u003e\u003e\u003e t['scrubs']['actors']\n    u'|Zach Braff|Donald Faison|Sarah Chalke|Judy Reyes|John C. McGinley|Neil Flynn|Ken Jenkins|Christa Miller|Aloma Wright|Robert Maschio|Sam Lloyd|Travis Schuldt|Johnny Kastl|Heather Graham|Michael Mosley|Kerry Bish\\xe9|Dave Franco|Eliza Coupe|'\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbr%2Ftvdb_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbr%2Ftvdb_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbr%2Ftvdb_api/lists"}