Add docstrings to remaining modules

This PR includes:
- Adding docstrings to all remaining modules, except unit tests
- Remove unwanted context snipper from addon.xml (testing leftover)
- Re-add pylint missing-docstring test

The helper-objects may need a more sensible docstring.
Other docstrings probably could use some more context information as well.

addon.xml

@@ -15,19 +15,6 @@
     </extension>
     <extension point="xbmc.service" library="service.py"/>
 
-    <extension point="kodi.context.item">
-        <menu id="kodi.core.main">
-            <item library="resources/menus/follow.py">
-                <label>30411</label>
-                <visible>IsEqual(ListItem.Property(Favorite),False)</visible>
-            </item>
-            <item library="resources/menus/unfollow.py">
-                <label>30412</label>
-                <visible>IsEqual(ListItem.Property(Favorite),True)</visible>
-            </item>
-        </menu>
-    </extension>
-
     <extension point="xbmc.addon.metadata">
         <summary lang="en_GB">Watch videos from VRT NU</summary>
         <description lang="en_GB">

pylintrc

@@ -6,7 +6,6 @@ disable=
     import-error,
     invalid-name,
     line-too-long,
-    missing-docstring, # Temporarily disabled until we fixed it
     no-init,
     no-self-use,
     old-style-class,

resources/lib/helperobjects.py

@@ -8,8 +8,10 @@
 
 
 class ApiData:
+    ''' This helper object holds all media information '''
 
     def __init__(self, client, media_api_url, video_id, publication_id, is_live_stream):
+        ''' The constructor for the ApiData class '''
         self.client = client
         self.media_api_url = media_api_url
         self.video_id = video_id
@@ -18,27 +20,34 @@ def __init__(self, client, media_api_url, video_id, publication_id, is_live_stre
 
 
 class Credentials:
+    ''' This helper object holds all credential information '''
 
     def __init__(self, _kodi):
+        ''' The constructor for the Credentials class '''
         self._kodi = _kodi
         self.username = _kodi.get_setting('username')
         self.password = _kodi.get_setting('password')
 
     def are_filled_in(self):
+        ''' Whether the credentials have been filled in and are stored in the settings '''
         return bool(self.username and self.password)
 
     def reload(self):
+        ''' Reload the credentials from the settings '''
         self.username = self._kodi.get_setting('username')
         self.password = self._kodi.get_setting('password')
 
     def reset(self):
+        ''' Reset the credentials in the settings '''
         self.username = self._kodi.set_setting('username', None)
         self.password = self._kodi.set_setting('password', None)
 
 
 class StreamURLS:
+    ''' This helper object holds all information to be used when playing streams '''
 
     def __init__(self, stream_url, subtitle_url=None, license_key=None, use_inputstream_adaptive=False):
+        ''' The constructor for the StreamURLS class '''
         self.stream_url = stream_url
         self.subtitle_url = subtitle_url
         self.license_key = license_key
@@ -47,8 +56,10 @@ def __init__(self, stream_url, subtitle_url=None, license_key=None, use_inputstr
 
 
 class TitleItem:
+    ''' This helper object holds all information to be used with Kodi xbmc's ListItem object '''
 
     def __init__(self, title, url_dict, is_playable, art_dict=None, video_dict=None, context_menu=None):
+        ''' The constructor for the TitleItem class '''
         self.title = title
         self.url_dict = url_dict
         self.is_playable = is_playable

resources/lib/vrtapihelper.py

@@ -17,13 +17,15 @@
 
 
 class VRTApiHelper:
+    ''' A class with common VRT NU API functionality '''
 
     _VRT_BASE = 'https://www.vrt.be'
     _VRTNU_SEARCH_URL = 'https://vrtnu-api.vrt.be/search'
     _VRTNU_SUGGEST_URL = 'https://vrtnu-api.vrt.be/suggest'
     _VRTNU_SCREENSHOT_URL = 'https://vrtnu-api.vrt.be/screenshots'
 
     def __init__(self, _kodi, _favorites):
+        ''' Constructor for the VRTApiHelper class '''
         self._kodi = _kodi
         self._proxies = _kodi.get_proxies()
         install_opener(build_opener(ProxyHandler(self._proxies)))
@@ -33,6 +35,7 @@ def __init__(self, _kodi, _favorites):
         self._channel_filter = [channel.get('name') for channel in CHANNELS if _kodi.get_setting(channel.get('name')) == 'true']
 
     def get_tvshow_items(self, category=None, channel=None, use_favorites=False):
+        ''' Get all TV shows for a given category or channel, optionally filtered by favorites '''
         params = dict()
 
         if category:
@@ -59,6 +62,7 @@ def get_tvshow_items(self, category=None, channel=None, use_favorites=False):
         return self._map_to_tvshow_items(api_json, use_favorites=statichelper.boolean(use_favorites))
 
     def _map_to_tvshow_items(self, tvshows, use_favorites=False):
+        ''' Construct a list of TV show TitleItems based on Suggests API query and filtered by favorites '''
         tvshow_items = []
         if statichelper.boolean(use_favorites):
             favorite_names = self._favorites.names()
@@ -102,6 +106,7 @@ def _map_to_tvshow_items(self, tvshows, use_favorites=False):
         return tvshow_items
 
     def get_latest_episode(self, tvshow):
+        ''' Get the latest episode of a program '''
         import json
         video = None
         params = {
@@ -118,6 +123,7 @@ def get_latest_episode(self, tvshow):
         return video
 
     def get_episode_items(self, path=None, page=None, show_seasons=False, use_favorites=False, variety=None):
+        ''' Construct a list of TV show episodes TitleItems based on API query and filtered by favorites '''
         titletype = None
         season_key = None
         all_items = True
@@ -184,11 +190,13 @@ def get_episode_items(self, path=None, page=None, show_seasons=False, use_favori
         return episode_items, sort, ascending, content
 
     def _get_season_data(self, api_json):
+        ''' Return a list of seasons '''
         facets = api_json.get('facets', dict()).get('facets')
         seasons = next((f.get('buckets', []) for f in facets if f.get('name') == 'seasons' and len(f.get('buckets', [])) > 1), None)
         return seasons
 
     def _get_season_episode_data(self, api_url, show_seasons, all_items=True):
+        ''' Return a list of episodes for a given season '''
         import json
         self._kodi.log_notice('URL get: ' + unquote(api_url), 'Verbose')
         api_json = json.load(urlopen(api_url))
@@ -208,6 +216,7 @@ def _get_season_episode_data(self, api_url, show_seasons, all_items=True):
         return dict(episodes=episodes), None
 
     def _map_to_episode_items(self, episodes, titletype=None, season_key=None, use_favorites=False):
+        ''' Construct a list of TV show episodes TitleItems based on Search API query and filtered by favorites '''
         from datetime import datetime
         import dateutil.parser
         import dateutil.tz
@@ -319,6 +328,7 @@ def _map_to_episode_items(self, episodes, titletype=None, season_key=None, use_f
         return episode_items, sort, ascending, 'episodes'
 
     def _map_to_season_items(self, api_url, seasons, episodes):
+        ''' Construct a list of TV show season TitleItems based on Search API query and filtered by favorites '''
         import random
 
         season_items = []
@@ -390,6 +400,7 @@ def _map_to_season_items(self, api_url, seasons, episodes):
         return season_items, sort, ascending, 'seasons'
 
     def search(self, search_string, page=0):
+        ''' Search VRT NU content for a given string '''
         import json
 
         page = statichelper.realpage(page)
@@ -409,18 +420,21 @@ def search(self, search_string, page=0):
         return episode_items, sort, ascending, content
 
     def get_live_screenshot(self, channel):
+        ''' Get a live screenshot for a given channel, only supports Eén, Canvas and Ketnet '''
         url = '%s/%s.jpg' % (self._VRTNU_SCREENSHOT_URL, channel)
         self.__delete_cached_thumbnail(url)
         return url
 
     def __delete_cached_thumbnail(self, url):
+        ''' Remove a cached thumbnail from Kodi in an attempt to get a realtime live screenshot '''
         crc = self.__get_crc32(url)
         ext = url.split('.')[-1]
         path = 'special://thumbnails/%s/%s.%s' % (crc[0], crc, ext)
         self._kodi.delete_file(path)
 
     @staticmethod
     def __get_crc32(string):
+        ''' Return the CRC32 checksum for a given string '''
         string = string.lower()
         string_bytes = bytearray(string.encode())
         crc = 0xffffffff
@@ -435,6 +449,7 @@ def __get_crc32(string):
         return '%08x' % crc
 
     def _make_label(self, result, titletype, options=None):
+        ''' Return an appropriate label matching the type of listing and VRT NU provided displayOptions '''
         if options is None:
             options = dict()
 
@@ -488,6 +503,7 @@ def _make_label(self, result, titletype, options=None):
         return label, sort, ascending
 
     def get_channel_items(self, action=actions.PLAY, channels=None):
+        ''' Construct a list of channel ListItems, either for Live TV or the TV Guide listing '''
         from resources.lib import tvguide
         _tvguide = tvguide.TVGuide(self._kodi)
 
@@ -540,6 +556,7 @@ def get_channel_items(self, action=actions.PLAY, channels=None):
         return channel_items
 
     def get_category_items(self):
+        ''' Construct a list of category ListItems '''
         categories = []
 
         # Try the cache if it is fresh
@@ -579,6 +596,7 @@ def get_category_items(self):
         return category_items
 
     def get_categories(self, proxies=None):
+        ''' Return a list of categories by scraping the website '''
         from bs4 import BeautifulSoup, SoupStrainer
         self._kodi.log_notice('URL get: https://www.vrt.be/vrtnu/categorieen/', 'Verbose')
         response = urlopen('https://www.vrt.be/vrtnu/categorieen/')
@@ -596,14 +614,17 @@ def get_categories(self, proxies=None):
         return categories
 
     def get_category_thumbnail(self, element):
+        ''' Return a category thumbnail, if available '''
         if self._showfanart:
             raw_thumbnail = element.find(class_='media').get('data-responsive-image', 'DefaultGenre.png')
             return statichelper.add_https_method(raw_thumbnail)
         return 'DefaultGenre.png'
 
     @staticmethod
     def get_category_title(element):
+        ''' Return a category title, if available '''
         found_element = element.find('a')
         if found_element:
             return statichelper.strip_newlines(found_element.contents[0])
+        # FIXME: We should probably fall back to something sensible here, or raise an exception instead
         return ''

resources/lib/vrtplayer.py

@@ -202,6 +202,7 @@ def search(self, search_string=None, page=None):
         self._kodi.show_listing(search_items, sort=sort, ascending=ascending, content=content, cache=False)
 
     def play_latest_episode(self, params):
+        ''' A hidden feature in the VRT NU add-on to play the latest episode of a program '''
         video = self._apihelper.get_latest_episode(params.get('tvshow'))
         if not video:
             self._kodi.log_error('Play latest episode failed, params %s' % params)

test/apihelpertests.py

@@ -2,6 +2,8 @@
 
 # GNU General Public License v3.0 (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+# pylint: disable=missing-docstring
+
 from __future__ import absolute_import, division, print_function, unicode_literals
 import unittest
 

test/favoritestests.py

@@ -2,6 +2,8 @@
 
 # GNU General Public License v3.0 (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+# pylint: disable=missing-docstring
+
 from __future__ import absolute_import, division, print_function, unicode_literals
 import unittest
 

test/routertests.py

@@ -2,6 +2,8 @@
 
 # GNU General Public License v3.0 (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+# pylint: disable=missing-docstring
+
 from __future__ import absolute_import, division, print_function, unicode_literals
 import unittest
 

test/searchtests.py

@@ -2,6 +2,8 @@
 
 # GNU General Public License v3.0 (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+# pylint: disable=missing-docstring
+
 from __future__ import absolute_import, division, print_function, unicode_literals
 import unittest
 

test/streamservicetests.py

@@ -3,6 +3,7 @@
 # GNU General Public License v3.0 (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # pylint: disable=unused-variable
+# pylint: disable=missing-docstring
 
 from __future__ import absolute_import, division, print_function, unicode_literals
 from datetime import datetime, timedelta

test/tvguidetests.py

@@ -2,6 +2,8 @@
 
 # GNU General Public License v3.0 (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+# pylint: disable=missing-docstring
+
 from __future__ import absolute_import, division, print_function, unicode_literals
 from datetime import datetime, timedelta
 import random

test/vrtplayertests.py

@@ -3,6 +3,7 @@
 # GNU General Public License v3.0 (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # pylint: disable=unused-variable
+# pylint: disable=missing-docstring
 
 from __future__ import absolute_import, division, print_function, unicode_literals
 import random