Documentation pass

bot/cogs/wumbopresence.py

@@ -5,7 +5,7 @@
 
 from discord import Game
 
-def randWumbo(wumboJSON=None):
+def randWumbo(wumboJSON=None) -> str:
     """
     Load list of Wumboisms from input JSON file & return a random string from the list
 

bot/models/Overwatch.py

@@ -10,6 +10,9 @@ class OWPatch():
     def __init__(self, patchref: str=None, ver: str=None, patchdate: datetime=None, 
                  patchURL: URL=None, bannerURL: URL=None
                  ):
+        """
+        Helper object to represent Blizzard's Overwatch Patch notes
+        """
         defaultpatchURL = URL('https://playoverwatch.com/en-us/news/patch-notes/pc')
         defaultbannerURL = URL('https://gear.blizzard.com/media/wysiwyg/default/logos/ow-logo-white-nds.png')
 

bot/models/Reddit.py

@@ -64,7 +64,7 @@ def __init__(self, credentialJSON: Path=Path('./credentials.JSON')):
         Helper class for PRAW instance
 
         On instantiation, an attempt is made to authenticate using the input credential JSON
-        Credential JSON should contain a 'RedditOAuth' key with a (ID, secret) tuple
+        Credential JSON should contain a 'RedditOAuth' key with an (ID, secret) tuple
 
         The isauthenticated attribute can be queried to determine authentication status
         """
@@ -155,9 +155,6 @@ async def asyncfromURL(inURL: str=None) -> typing.List:
             https://old.reddit.com/r/subreddit/comments/*
 
         Other input URL formats are not supported
-
-        The skipvalidation flag allows you to skip the URL validation if it has already
-        been validated
         """
         inURL = RedditJSON._validateURL(inURL, checkJSON=False)
         if RedditJSON._isredditJSON(inURL):
@@ -176,6 +173,9 @@ def fromJSON(jsonURL: typing.Union[str, URL]=None, skipvalidation: bool=False) -
             https://old.reddit.com/r/subreddit/comments/*(/).json
 
         Other input URL formats are not supported
+
+        The skipvalidation flag allows you to skip the URL validation if it has already
+        been validated
         """
         if not skipvalidation:
             jsonURL = RedditJSON._validateURL(jsonURL, checkJSON=True)

docs/Models/Overwatch.rst

@@ -0,0 +1,47 @@
+Overwatch Abstract Models
+==================================
+
+Class Reference
+---------------
+.. class:: Overwatch.OWPatch(**kwargs)
+
+    Helper class to generate an object from Blizzard's Patch Notes
+
+    .. attribute:: patchref(str)
+
+        Patch reference ID
+
+        e.g. ``'patch-50148'``
+
+    .. attribute:: ver(str)
+
+        Patch version number
+
+        e.g. ``'1.28.0.1'``
+
+    .. attribute:: patchdate(datetime)
+
+        Patch date (UTC)
+
+        e.g. ``dt.strptime('09/11/2018', '%m/%d/%Y')``
+
+    .. attribute:: patchURL(yarl.URL)
+
+        Patch notes permalink
+
+        Patch note permalink is provided by `BlizzTrack <https://blizztrack.com/patch_notes/overwatch/latest>`_
+
+    .. attribute:: bannerURL(yarl.URL)
+
+        Blizzard patch banner URL permalink
+
+    .. staticmethod:: getblizztrack(patchref:str) -> yarl.URL
+
+        Build a ``yarl.URL`` object from a patch reference ID
+
+        .. code-block:: python3
+
+            >>> from cogs import overwatch
+            >>> patchURL = overwatch.PatchNotesParser.getblizztrack('50148')
+            >>> print(patchURL)
+            https://blizztrack.com/patch_notes/overwatch/50148

docs/Models/Reddit.rst

@@ -0,0 +1,135 @@
+Reddit Abstract Models
+==================================
+
+Class Reference
+---------------
+
+.. class:: Reddit.RedditPost(self, subreddit: str=None, id: str=None, created_utc: float=None, title: str=None, url: str=None, permalink: str=None, author: str=None, **kwargs)
+
+    Helper object to represent a Reddit Submission
+
+    .. note::
+        To simplify construction from Reddit's JSON return, additional keyword arguments are accepted but discarded
+
+    .. attribute:: subreddit(str)
+
+        Submission subreddit
+
+    .. attribute:: id(str)
+
+        Unique submission ID
+
+        `Base36 <https://en.wikipedia.org/wiki/Base36>`_ encoded
+
+    .. attribute:: created_utc(datetime)
+
+        Post creation date (UTC)
+
+    .. attribute:: title(str)
+
+        Submission title
+
+    .. attribute:: url(yarl.URL)
+
+        Content URL
+
+    .. attribute:: permalink(yarl.URL)
+
+        Submission permalink
+
+    .. attribute:: author(str)
+
+        Submission author
+
+    .. staticmethod:: fromJSON(inJSON: dict) -> RedditPost
+
+        Generate ``Reddit.RedditPost`` from a Reddit submission JSON (as dict)
+
+    .. staticmethod:: fromPRAW(inSub: praw.Submission) -> RedditPost
+
+        Generate ``Reddit.RedditPost`` from a ``praw.Submission`` object
+
+
+.. class:: RedditPRAW(credentialJSON: Path=Path('./credentials.JSON'))
+
+    Helper class for PRAW instance
+
+    .. note:: 
+        On instantiation, an attempt is made to authenticate using the input ``credentialJSON``
+
+        ``credentialJSON`` should contain a ``'RedditOAuth'`` key with an ``(ID, secret)`` tuple
+
+        The ``isauthenticated`` attribute can be queried to determine authentication status
+
+    .. method:: getnewusersubmissions(self, username: str, limit: int=25) -> praw.models.ListingGenerator
+
+        Return a ``praw.ListingGenerator`` of ``username``'s newest Reddit submissions
+
+        API call can be limited to a number of submissions, as specified by ``limit``
+
+
+.. class:: RedditJSON
+
+    Helper class for Reddit JSON methods
+
+    .. comethod:: asyncfromJSON(jsonURL: typing.Union[str, URL]=None, skipvalidation: bool=False) -> typing.List:
+        :staticmethod:
+
+        Return a list of ``Reddit.RedditPost`` objects from an input Reddit JSON URL
+
+        Supported URL schemas are:
+
+        .. code-block:: none
+
+            https://old.reddit.com/u(ser)/username/submitted(/).json
+            https://old.reddit.com/r/subreddit(/).json
+            https://old.reddit.com/r/subreddit/comments/*.json
+
+        Other input URL formats are not supported
+
+        The skipvalidation flag allows you to skip the URL validation if it has already been validated
+
+    .. staticmethod:: fromJSON(jsonURL: typing.Union[str, URL]=None, skipvalidation: bool=False) -> typing.List:
+
+        Return a list of ``Reddit.RedditPost`` objects from an input Reddit JSON URL
+
+        Supported URL schemas are:
+
+        .. code-block:: none
+
+            https://old.reddit.com/u(ser)/username/submitted(/).json
+            https://old.reddit.com/r/subreddit(/).json
+            https://old.reddit.com/r/subreddit/comments/*.json
+
+        Other input URL formats are not supported
+
+        The skipvalidation flag allows you to skip the URL validation if it has already been validated
+
+    .. comethod:: asyncfromURL(inURL: typing.Union[str, yarl.URL]=None) -> typing.List:
+        :staticmethod:
+
+        Return a list of ``reddit.RedditPost`` objects from an input Reddit URL
+
+        Supported URL schemas are:
+
+        .. code-block:: none
+
+            https://old.reddit.com/u(ser)/username/submitted(/)
+            https://old.reddit.com/r/subreddit(/)
+            https://old.reddit.com/r/subreddit/comments/*
+
+        Other input URL formats are not supported
+
+    .. staticmethod:: fromURL(inURL: typing.Union[str, yarl.URL]=None) -> typing.List:
+
+        Return a list of ``reddit.RedditPost`` objects from an input Reddit URL
+
+        Supported URL schemas are:
+
+        .. code-block:: none
+
+            https://old.reddit.com/u(ser)/username/submitted(/)
+            https://old.reddit.com/r/subreddit(/)
+            https://old.reddit.com/r/subreddit/comments/*
+
+        Other input URL formats are not supported

docs/Models/Steam.rst

@@ -0,0 +1,85 @@
+Steam Abstract Models
+==================================
+
+Class Reference
+---------------
+
+.. class:: Steam.SteamNewsPost(**kwargs)
+
+    Helper class for Steam News Posts
+
+    .. attribute:: gid(str)
+
+        Global post ID
+
+    .. attribute:: title(str)
+
+        News post title
+
+    .. attribute:: url(yarl.URL)
+
+        News post permalink
+
+    .. attribute:: is_external_url(bool)
+
+        External URL flag
+
+    .. attribute:: author(str)
+
+        News post author
+
+    .. attribute:: contents(str)
+
+        News post contents
+
+        .. note::
+            Contents are truncated by the API call based on the ``maxlength`` parameter
+
+        .. note::
+            URLs are stripped from ``content`` on object instantiation
+
+    .. attribute:: feedlabel(str)
+
+        News feed label
+
+    .. attribute::  date(datetime)
+
+        Post date (UTC)
+
+    .. attribute:: feedname(str)
+
+        News feed name
+
+    .. attribute:: feed_type(int)
+
+        News feed type [#apilink]_
+
+    .. attribute:: appid(int)
+
+        App ID [#apilink]_
+
+    .. [#apilink] See `Steam's API Documentation <https://developer.valvesoftware.com/wiki/Steam_Web_API#GetNewsForApp_.28v0002.29>`_ for additional details
+
+    .. staticmethod:: getnewsforapp(appID: int=582010, count: int=10, maxlength: int=300, format: str='json', **kwargs) -> typing.List
+
+        Return a list of ``mhw.SteamNewsPost`` objects for the specified ``appID``
+
+        ``count`` specifies the number of posts to Return
+
+        ``maxlength`` specifies the maximum length of the returned contents string
+
+        .. note::
+            Additional ``**kwargs`` are discarded
+
+
+    .. comethod:: asyncgetnewsforapp(appID: int=582010, count: int=10, maxlength: int=300, format: str='json', **kwargs) -> typing.List
+        :staticmethod:
+
+        Return a list of ``mhw.SteamNewsPost`` objects for the specified ``appID``
+
+        ``count`` specifies the number of posts to Return
+
+        ``maxlength`` specifies the maximum length of the returned contents string
+
+        .. note::
+            Additional ``**kwargs`` are discarded

docs/Models/index.rst

@@ -0,0 +1,11 @@
+Wumbot Data Models
+==================================
+
+Abstract base models by Wumbot's cogs
+
+.. toctree::
+   :maxdepth: 2
+
+   Overwatch
+   Reddit
+   Steam

docs/cogs/index.rst

@@ -1,7 +1,7 @@
 Wumbot Extensions
 ==================================
 
-Test1
+Wumbot loads the following cogs on login
 
 .. toctree::
    :maxdepth: 2
@@ -10,3 +10,5 @@ Test1
    mhw
    overwatch
    reddit
+   rocketleague
+   wumbopresence