
Overview
--------------------------------------------
* 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
---------------------------

  * [Overview](#overview)
  * [Table of contents](#table-of-contents)
  * [Installation and Setup](#installation-and-setup)
  * [Usage](#usage)
  * [Files](#files)
  * [Dependencies](#dependencies)
  * [Features](#features)
  * [Log file](#log-file)
  * [See Also](#see-also)
  * [Communication](#communication)
  * [History](#history)
  * [Copyright](#copyright)

Installation and Setup
-----------------------------------------------

The program is present in python package index, Pypi.
Make sure that python 3 and pip3 have been installed on your machine, then: 

```sh
sudo pip3 install tv_viewer
```

Note: Could not add pyqt5 to setup script for pip so this must be installed manually, 
if installing via pip. [pyqt info](https://stackoverflow.com/questions/38488063/add-pyqt5-to-install-require)

The program uses the OS home environmental variable to know where to place database and log file
It should be setup on most Operating systems. To view it type at a python prompt.

```sh
import os
print(os.environ['home'])
```

Usage
-------------------------------------------
type below in terminal  to launch *or* select icon from Desktop app menus under Other(linux only)

```sh
tv_viewer.py 
```

Files 
-----------------------------------------

| File Path | Description |
| ------ | ------ |
| $HOME/.config/tv_viewer/fav.db | Database created by program |
| $HOME/.cache/tv_viewer/tvviewerlog_YYMMDD_HHMMSS | Log file |
| /usr/share/doc/tv_viewer/README.md | Help Linux only |
| /usr/share/pixmaps/tv_viewer.png | icon Linux only |
| /usr/share/applications/tv_viewer.desktop | desktop entry Linux only |
| tv_viewer.py | main executable python script |
| tv_qt_class.py | python module dealing with PyQt code |
| tv_sqllite.py | python module dealing with SQLite code |
| tv_api_work.py | python module dealing with Pytvmaze code |
| logger_conf.py | python module dealing with logging |


Dependencies
-------------------------------------
| 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 |

Features
----------------------
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 

```sh
| $HOME/.cache/tv_viewer/tvviewerlog_YYMMDD_HHMMSS
```
sample output
time: Level: module: message: + traceback error if available. 
```sh
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.


See Also
-----------
* [TV maze API](http://www.tvmaze.com/api)
* [pytvmaze Python interface to TV Maze API ](https://github.com/srob650/pytvmaze)
* [prettytable python module](https://github.com/dprince/python-prettytable)
* [PyQt5](http://pyqt.sourceforge.net/Docs/PyQt5/)
* [SQLite](https://sqlite.org/)

There are screenshots in the repository. 


Communication
-------------------
* Contact: Upstream repo at github site below or glyons66@hotmail.com
* Upstream repository: [Github](https://github.com/gavinlyonsrepo/tv_viewer)

History
------------------
See changelog.md in documentation section for version control history

Copyright
---------
Copyright (C) 2017 Gavin Lyons, see LICENSE.md in documentation section 
for more details.
