Update documentation

bot/models/NewsParser.py

@@ -13,6 +13,7 @@ def __init__(self, bot):
         self._parsername = None
         self._loadconverter = None
         self._saveconverter = None
+        self._comparator = None
 
     def loadposted(self):
         if self.logJSONpath.exists():

bot/models/Steam.py

@@ -45,7 +45,7 @@ def __repr__(self):
 
     @staticmethod
     async def asyncgetnewsforapp(
-        appID: int = 582_010,
+        appID: int = 582010,
         count: int = 10,
         maxlength: int = 300,
         format: str = "json",
@@ -77,7 +77,7 @@ async def asyncgetnewsforapp(
 
     @staticmethod
     def getnewsforapp(
-        appID: int = 582_010,
+        appID: int = 582010,
         count: int = 10,
         maxlength: int = 300,
         format: str = "json",

docs/Models/ManualCheck.rst

@@ -0,0 +1,18 @@
+Manual Patch Check Abstract Helper
+======================================
+
+Class Reference
+---------------
+.. class:: ManualCheck
+
+    .. comethod:: check(ctx: commands.Context, toinvoke: typing.Callable, commandstr: str)
+        :staticmethod:
+
+        Helper method for manual patch check invocation commands
+
+        ``toinvoke`` is the parser-specific patch check function to invoke
+
+        ``commandstr`` is a descriptive string to use for logging & bot feedback messages
+
+        .. note::
+            ``bot.Helpers.isDM`` and ``bot.Helpers.isOwner`` checks are run prior to invoking the patch check function

docs/Models/NewsParser.rst

@@ -0,0 +1,73 @@
+Abstract News Parser
+========================
+
+Class Reference
+---------------
+
+
+Function Reference
+------------------
+
+.. class:: NewsParser
+
+    Abstract news parser base class
+
+    .. note::
+        All attributes are defined at the child parser level
+
+    .. attribute:: bot
+
+        ``discord.commands.Bot`` instance
+
+    .. attribute:: postednews
+
+        List containing posted information.
+
+        Format of list entries is defined at the child parser level
+
+    .. attribute:: _parsername
+
+        Descriptive parser shortname
+
+    .. attribute:: _loadconverter
+
+        Function that accepts externally saved posts and formats them for ``postednews``
+
+    .. attribute:: _saveconverter
+
+        Function that accepts entries from ``postednews`` and formats them for external saving
+
+    .. attribute:: _comparator
+
+        Model attribute (as ``str``) used to compare posts to the list of posted news as a new post check
+
+    .. method:: loadposted
+
+        Load saved information from the child class-specified JSON file into ``self.loadposted``
+
+        JSON data is assumed to be stored as a list. ``self._loadconverter`` is run for each JSON list entry
+
+    .. method:: saveposted
+
+        Dump information from ``self.postednews`` into a child class-specified JSON file
+
+        ``self.postednews`` is assumed to be a list. ``self._saveconverter`` is run for each list entry prior to the JSON dump
+
+    .. comethod:: patchcheck(posts: typing.List)
+
+        Abstract patch checking method.
+
+        On invocation:
+            #. Load saved posts using ``NewsParser.loadposted``
+            #. Check ``posts`` against loaded posts using ``self._comparator`` to get the appropriate comparison attribute
+            #. If new posts are present, call the child class' ``postembed`` method to generate & send Discord embed
+            #. Save posted news using ``NewsParser.saveposted``
+
+Function Reference
+------------------
+
+.. cofunction:: patchchecktimer(client, parsers: typing.Tuple = (), sleepseconds: int = 3600)
+
+    Abstract patch checking event loadposted
+
+    Invoke the input ``parsers`` every ``sleepseconds``

docs/Models/Overwatch.rst

@@ -35,6 +35,21 @@ Class Reference
 
         Blizzard patch banner URL permalink
 
+    .. comethod:: asyncfromURL(inURL: typing.Union[str, URL]) -> typing.List
+        :staticmethod:
+
+        Return a list of Overwatch.OWPatch objects parsed from inURL.
+
+        Default URL is Blizzard's Overwatch PC patch notes. Other URLs are not explicitly supported
+
+    .. staticmethod:: fromURL(inURL: typing.Union[str, URL]) -> typing.List
+
+        *This function is blocking*
+
+        Return a list of Overwatch.OWPatch objects parsed from inURL.
+
+        Default URL is Blizzard's Overwatch PC patch notes. Other URLs are not explicitly supported
+
     .. staticmethod:: getblizztrack(patchref:str) -> yarl.URL
 
         Build a ``yarl.URL`` object from a patch reference ID

docs/Models/Reddit.rst

@@ -91,6 +91,8 @@ Class Reference
 
     .. staticmethod:: fromJSON(jsonURL: typing.Union[str, URL]=None, skipvalidation: bool=False) -> typing.List:
 
+        *This function is blocking*
+
         Return a list of ``Reddit.RedditPost`` objects from an input Reddit JSON URL
 
         Supported URL schemas are:
@@ -122,6 +124,8 @@ Class Reference
 
     .. staticmethod:: fromURL(inURL: typing.Union[str, yarl.URL]=None) -> typing.List:
 
+        *This function is blocking*
+
         Return a list of ``reddit.RedditPost`` objects from an input Reddit URL
 
         Supported URL schemas are:

docs/Models/Steam.rst

@@ -62,6 +62,8 @@ Class Reference
 
     .. staticmethod:: getnewsforapp(appID: int=582010, count: int=10, maxlength: int=300, format: str='json', **kwargs) -> typing.List
 
+        *This function is blocking*
+
         Return a list of ``mhw.SteamNewsPost`` objects for the specified ``appID``
 
         ``count`` specifies the number of posts to Return

docs/Models/index.rst

@@ -8,4 +8,6 @@ Abstract base models by Wumbot's cogs
 
    Overwatch
    Reddit
-   Steam
+   Steam
+   NewsParser
+   ManualCheck

docs/cogs/overwatch.rst

@@ -40,9 +40,14 @@ Parser Reference
         #. Check patch references against those previously posted
         #. If new patch(es): Build embed, post to channel, and save the patch reference(s) to the local JSON log
 
-.. class:: overwatch.PatchNotesParser
+.. class:: overwatch.PatchRundownParser
+
+    Reddit user `/u/itsjieyang <https://reddit.com/u/itsjieyang>`_'s Overwatch patch rundown monitor
 
-    Reddit user `/u/itsjieyang <https://reddit.com/u/itsjieyang>`_'s Overwatch Patch GIF Monitor
+    Rundows are currently posted as:
+      * Gfycat - Brief summary
+      * Youtube Video - Extended rundown
+      * Streamable - Brief/extended rundown
 
     .. attribute:: bot(WumbotClient)
 
@@ -60,25 +65,25 @@ Parser Reference
 
         Path to JSON storage file
 
-    .. attribute:: postedGIFs(List[str])
+    .. attribute:: postedrundowns(List[str])
 
         ``List`` containing posted patch notes
 
-        Patches are stored as Gfycat permalinks, as ``str`` (e.g. ``'https://gfycat.com/MajorDiligentIbizanhound'``)
+        Patches are stored as permalinks, as ``str`` (e.g. ``'https://gfycat.com/MajorDiligentIbizanhound'``)
 
     .. comethod:: patchcheck
         :classmethod:
 
         Executes the patch check operations:
 
-        #. Parse /u/itsjieyang's submissions for Gfycat submissions to /r/overwatch
+        #. Parse /u/itsjieyang's submissions for submissions to /r/overwatch
 
         .. note::
             An attempt is made to open an authenticated `PRAW <https://github.com/praw-dev/praw>`_ session to query submissions. If a session cannot be generated, Reddit's JSON is used as a fallback
 
         #. Build `Models.Reddit.RedditPost` objects
         #. Check Gfycat URLs against those previously posted
-        #. If new patch GIF(s): Build embed, post to channel, and save the Gfycat permalink to the local JSON log
+        #. If new patch rundown(s): Build embed, post to channel, and save the permalink to the local JSON log
 
     .. staticmethod:: gfygif(inURL: typing.Union[str, yarl.URL]) -> yarl.URL
 
@@ -95,15 +100,15 @@ Parser Reference
 
     Asynchronous patch checking loop for use with Discord.py's event loop
 
-    ``overwatch.PatchNotesParser`` and ``overwatch.PatchGifParser`` are called every ``sleepseconds``
+    ``overwatch.PatchNotesParser`` and ``overwatch.PatchRundownParser`` are called every ``sleepseconds``
 
 Command Reference
 -----------------
 Commands are prefixed with ``~``
 
-.. function:: ~checkOWgif
+.. function:: ~checkOWrundown
 
-    Manually invoke the ``overwatch.PatchGifParser.patchcheck()`` coroutine
+    Manually invoke the ``overwatch.PatchRundownParser.patchcheck()`` coroutine
 
     .. note::
         This command is only enabled for the server owner via DM.

readthedocs.yml

@@ -4,7 +4,7 @@ build:
   image: latest
 
 python:
-  version: 3.6
+  version: 3.7
   pip_install: true
   extra_requirements:
     - docs

setup.py

@@ -19,7 +19,7 @@
       description='A Python Discord bot for Wumbology, Inc.',
       long_description=readme,
       extras_require=extras_require,
-      python_requires='>=3.6.0',
+      python_requires='>=3.7.0',
       classifiers=[
         'Development Status :: 4 - Beta',
         'Intended Audience :: Developers',