Merge pull request #1 from realpython/reader

Simple Feed Reader for Real Python tutorials

README.md

@@ -1 +1,59 @@
-# reader
+# Real Python Feed Reader
+
+The Real Python Feed Reader is a very simple [web feed](https://en.wikipedia.org/wiki/Web_feed) reader that can download the latest Real Python tutorials from the [Real Python feed](https://realpython.com/contact/#rss-atom-feed).
+
+## Installation
+
+You can install the Real Python Feed Reader from [PyPI](https://pypi.org/project/realpython-reader/):
+
+    pip install realypython-reader
+
+## How to use
+
+The Real Python Feed Reader is a command line application. To see a list of the [latest Real Python tutorials](https://realpython.com/) simply call the program:
+
+    $ realpython 
+    The latest tutorials from Real Python (https://realpython.com/)
+      0 Logging in Python
+      1 The Best Python Books
+      2 Conditional Statements in Python
+      3 Structuring Python Programs
+      4 We're Celebrating 1 Million Page Views per Month!
+      5 Python Pandas: Tricks & Features You May Not Know
+      6 Python Community Interview With Mariatta Wijaya
+      7 Primer on Python Decorators
+      8 Sets in Python
+      9 The Ultimate Guide to Django Redirects
+     10 Advanced Git Tips for Python Developers
+     11 Python Community Interview With Mike Driscoll
+     12 Dictionaries in Python
+     13 Socket Programming in Python (Guide)
+     14 Python Code Quality: Tools & Best Practices
+     15 Documenting Python Code: A Complete Guide
+     16 Fast, Flexible, Easy and Intuitive: How to Speed Up Your Pandas Projects
+     17 Lists and Tuples in Python
+     18 Reading and Writing CSV Files in Python
+     19 Generating Random Data in Python (Guide)
+
+To read one particular tutorial, call the program with the numerical ID of the tutorial as a parameter:
+
+    $ realpython 0
+    # Logging in Python
+
+    Logging is a very useful tool in a programmer's toolbox. It can help you
+    develop a better understanding of the flow of a program and discover scenarios
+    that you might not even have thought of while developing.
+
+    Logs provide developers with an extra set of eyes that are constantly looking
+    at the flow that an application is going through. They can store information,
+    like which user or IP accessed the application. If an error occurs, then they
+    can provide more insights than a stack trace by telling you what the state of
+    the program was before it arrived at the line of code where the error
+    occurred.
+
+You can also call the Real Python Feed Reader in your own Python code, by importing from the `reader` package:
+
+    >>> from reader import feed
+    >>> feed.get_titles()
+    ['Logging in Python', 'The Best Python Books', ...]
+

reader/__init__.py

@@ -0,0 +1,15 @@
+"""Real Python feed reader
+
+Import the `feed` module to work with the Real Python feed:
+
+    >>> from reader import feed
+    >>> feed.get_titles()
+    ['Logging in Python', 'The Best Python Books', ...]
+
+See https://github.com/realpython/reader/ for more information
+"""
+# Version of realpython-reader package
+__version__ = "0.0.1"
+
+# URL of Real Python feed
+URL = "https://realpython.com/atom.xml"

reader/__main__.py

@@ -0,0 +1,22 @@
+import sys
+
+from reader import feed
+from reader import viewer
+
+
+def main() -> None:
+    """Read the Real Python article feed"""
+    # An article ID is given, show article
+    if len(sys.argv) > 1:
+        article = feed.get_article(sys.argv[1])
+        viewer.show(article)
+
+    # No ID is given, show list of articles
+    else:
+        site = feed.get_site()
+        titles = feed.get_titles()
+        viewer.show_list(site, titles)
+
+
+if __name__ == "__main__":
+    main()

reader/feed.py

@@ -0,0 +1,38 @@
+from typing import List
+import feedparser
+import html2text
+import reader
+
+_CACHED_FEED = feedparser.FeedParserDict()
+
+
+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
+
+
+def get_site() -> str:
+    """Get name and link to web site of the feed"""
+    info = _feed().feed
+    return f"{info.title} ({info.link})"
+
+
+def get_article(article_id: str) -> str:
+    """Get article from feed with the given ID"""
+    articles = _feed().entries
+    try:
+        article = articles[int(article_id)]
+    except (IndexError, ValueError):
+        raise SystemExit("Error: Unknown article ID")
+
+    html = article.content[0].value
+    text = html2text.html2text(html)
+    return f"# {article.title}\n\n{text}"
+
+
+def get_titles() -> List[str]:
+    """List titles in feed"""
+    articles = _feed().entries
+    return [a.title for a in articles]

reader/viewer.py

@@ -0,0 +1,13 @@
+from typing import List
+
+
+def show(article: str) -> None:
+    """Show one article"""
+    print(article)
+
+
+def show_list(site: str, titles: List[str]) -> None:
+    """Show list of articles"""
+    print(f"The latest tutorials from {site}")
+    for article_id, title in enumerate(titles):
+        print(f"{article_id:>3} {title}")

setup.py

@@ -0,0 +1,30 @@
+import pathlib
+from setuptools import find_packages, setup
+
+# The directory containing this file
+HERE = pathlib.Path(__file__).parent
+
+
+setup(
+    name="realpython-reader",
+    version="0.0.1",
+    description="Read Real Python Tutorials",
+    long_description=(HERE / "README.md").read_text(),
+    long_description_content_type="text/markdown",
+    url="https://github.com/realpython/reader",
+    author="Real Python",
+    author_email="[email protected]",
+    license="MIT",
+    classifiers=[
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+    ],
+    packages=find_packages(exclude=("tests",)),
+    install_requires=["feedparser", "html2text"],
+    entry_points={
+        "console_scripts": [
+            "realpython=reader.__main__:main",
+        ]
+    },
+)