Merge pull request #2 from realpython/docs

Add docstrings to all modules, and a simple help text to the program

Author: gahjelle

reader/__main__.py

@@ -1,11 +1,48 @@
+"""Read the latest Real Python tutorials
+
+Usage:
+------
+
+List the latest tutorials:
+
+    $ realpython
+
+Read one tutorial:
+
+    $ realpython <id>
+
+    where <id> is the number shown when listing tutorials.
+
+Read the latest tutorial:
+
+    $ realpython 0
+
+
+Contact:
+--------
+
+- https://realpython.com/contact/
+
+More information is available at:
+
+- https://pypi.org/project/realpython-reader/
+- https://github.com/realpython/reader
+"""
+# Standard library imports
 import sys
 
+# Reader imports
 from reader import feed
 from reader import viewer
 
 
 def main() -> None:
     """Read the Real Python article feed"""
+    # Show help message
+    if "-h" in sys.argv or "--help" in sys.argv:
+        viewer.show(__doc__)
+        return
+
     # An article ID is given, show article
     if len(sys.argv) > 1:
         article = feed.get_article(sys.argv[1])

reader/feed.py

@@ -1,16 +1,21 @@
-from typing import List
+"""Interact with the Real Python feed"""
+# Standard library imports
+from typing import Dict, List
+
+# Third party imports
 import feedparser
 import html2text
-import reader
 
-_CACHED_FEED = feedparser.FeedParserDict()
+# Reader imports
+from reader import URL
+_CACHED_FEEDS: Dict[str, feedparser.FeedParserDict] = dict()
 
 
 def _feed() -> feedparser.FeedParserDict:
     """Cache contents of the feed, so it's only read once"""
-    if not _CACHED_FEED:
-        _CACHED_FEED.update(feedparser.parse(reader.URL))
-    return _CACHED_FEED
+    if URL not in _CACHED_FEEDS:
+        _CACHED_FEEDS[URL] = feedparser.parse(URL)
+    return _CACHED_FEEDS[URL]
 
 
 def get_site() -> str:
@@ -25,9 +30,14 @@ def get_article(article_id: str) -> str:
     try:
         article = articles[int(article_id)]
     except (IndexError, ValueError):
-        raise SystemExit("Error: Unknown article ID")
+        max_id = len(articles) - 1
+        msg = f"Unknown article ID, use ID from 0 to {max_id}"
+        raise SystemExit(f"Error: {msg}")
 
-    html = article.content[0].value
+    try:
+        html = article.content[0].value
+    except AttributeError:
+        html = article.summary
     text = html2text.html2text(html)
     return f"# {article.title}\n\n{text}"
 

reader/viewer.py

@@ -1,3 +1,6 @@
+"""Functions for displaying the Real Python feed"""
+
+# Standard library imports
 from typing import List
 
 

setup.py

@@ -1,15 +1,21 @@
+"""Setup script for realpython-reader"""
+
 import pathlib
-from setuptools import find_packages, setup
+from setuptools import setup
 
 # The directory containing this file
 HERE = pathlib.Path(__file__).parent
 
+# The text of the README file
+README = (HERE / "README.md").read_text()
+
 
+# This call to setup() does all the work
 setup(
     name="realpython-reader",
     version="0.0.1",
     description="Read Real Python Tutorials",
-    long_description=(HERE / "README.md").read_text(),
+    long_description=README,
     long_description_content_type="text/markdown",
     url="https://github.com/realpython/reader",
     author="Real Python",
@@ -20,7 +26,7 @@
         "Programming Language :: Python",
         "Programming Language :: Python :: 3",
     ],
-    packages=find_packages(exclude=("tests",)),
+    packages=["reader"],
     install_requires=["feedparser", "html2text"],
     entry_points={
         "console_scripts": [