Python PyQt5 GUI to view tv program details using tvmaze API and SQLite

televison, tv_viewer, tv, maze, SQLite, PyQt, gavin, lyons, schedule, API, GUI, communication, database, prettytable, pyqt5, python, python3, pytvmaze, sql, sqlite-database, sqllite, television, tv-maze, tv-viewer, tvmaze, tvmaze-api, tvmazeapi, upstream
pip install tv-viewer==1.2



  • Name: tv_viewer
  • Title : Graphical user interface to view tv show details using TV maze API
  • Description: GUI to view tv program details using TV maze application programming interface. Written in python 3 and PyQt 5, it also stores user favourites in an SQLite database. It uses python module pytvmaze to interface with API and python module prettytable to help display results.
  • Author: Gavin Lyons

Table of contents


If you are an Arch linux OS user tv_viewer can be installed by PKGBUILD. The PKGBUILD file is available in the AUR - Arch user repository.

AUR package name :tv_viewer
AUR maintainer : glyons
AUR location:

For other Linux OS users, the program is present in pyhton package index, Pypi. Make sure that python 3 and pip3 have been installed on your machine, then:

sudo pip3 install tv_viewer

Could not add pyqt5 to setup script for pip so this must be installed manually, if installing via pip. pyqt info


type below in terminal to launch or select icon from Desktop app menus under Other. 


File Path Description
$HOME/.config/tv_viewer/fav.db Database created by program
/usr/share/doc/tv_viewer/ Help
/usr/share/pixmaps/tv_viewer.png icon
/usr/share/applications/tv_viewer.desktop desktop entry main executable python script python module dealing with PyQt code python module dealing with SQLite code python module dealing with Pytvmaze code python module dealing with logging


Dependencies Usage
prettytable (0.7.2) used to format text extracted from API into tables
pytvmaze (2.0.8) Python interface to TV Maze API
pyqt5 (5.9.2) GUI toolkit


From the menu bar a user can select about, help and exit options.

The TV maze API associates a unique ID with each TV show called the Maze_ID.

On the main screen the user is prompted to enter name of show in input box. The software then returns a list of television shows based on the input. The user can then select the show by row number and is presented with various details of it. From here they select more detailed information by selecting one of the radio buttons and pressing Select. Options include overview, seasons, cast, crew, episodes and more miscellaneous information. They can also view and/or toggle the favourite status of show by pressing Edit Fav button.

The software also includes a favourite function where user can store favourites TV shows in a database. The database has one table shows and two fields name and number. the maze_ID of the show is stored at number. The contents of the database can be displayed by pressing View Favs button. Favourites records can be added by entering an existing maze_id in input box and pressing Edit Favs button, records can be deleted by adding a maze_id of show not in database and pressing Edit Favs button. The favourite section will also show next episode date and days till next episode.

A reset and exit button is also available.

Log file

Debug log file to store information outputted by program is stored at


sample output time: Level: module: message: + traceback error if available.

2017-12-04 15:03:32:INFO:__main__:  Main Loop Start
2017-12-04 15:04:42:WARNING:tv_api_work.tv_api_work:No next episode data available

Exceptions are generated by software as a result of missing and incomplete API data by TV maze for some shows. These are caught and outputted to log file and won't interfere with running of program. The software should catch most issues and output them there. Also displayed here are various other debug information.

To Do

  • Code the "Upcoming shows" Function/Button

See Also

There are screenshots in the repository.

If you should find a bug or you have any other query, please send a report. Pull requests, suggestions for improvements and new features welcome.


See in documentation section for version control history


Copyright (C) 2017 Gavin Lyons This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public license published by the Free Software Foundation, see in documentation section for more details