oldnews 0.0.1__tar.gz → 0.1.0__tar.gz

oldnews-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: oldnews
+Version: 0.1.0
+Summary: A terminal-based client for TheOldReader
+Keywords: atom,client,Google Reader,RSS,TheOldReader,terminal,news-reader,news
+Author: Dave Pearson
+Author-email: Dave Pearson <davep@davep.org>
+License-Expression: GPL-3.0-or-later
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: html-to-markdown>=2.15.0
+Requires-Dist: oldas>=0.3.1
+Requires-Dist: textual>=6.3.0
+Requires-Dist: textual-enhanced>=1.2.0
+Requires-Dist: typedal>=4.2.2
+Requires-Dist: xdg-base-dirs>=6.0.2
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/davep/oldnews
+Project-URL: Repository, https://github.com/davep/oldnews
+Project-URL: Documentation, https://oldnews.davep.dev/
+Project-URL: Source, https://github.com/davep/oldnews
+Project-URL: Issues, https://github.com/davep/oldnews/issues
+Project-URL: Discussions, https://github.com/davep/oldnews/discussions
+Description-Content-Type: text/markdown
+
+# OldNews - A TheOldReader client for the terminal
+
+## Introduction
+
+OldNews is a terminal-based client for
+[TheOldReader](https://theoldreader.com). Right now it is an evolving work
+in progress, built on top of [`oldas`](https://github.com/davep/oldas).
+
+## Installing
+
+### pipx
+
+The application can be installed using [`pipx`](https://pypa.github.io/pipx/):
+
+```sh
+$ pipx install oldnews
+```
+
+### uv
+
+The package can be install using [`uv`](https://docs.astral.sh/uv/getting-started/installation/):
+
+```sh
+uv tool install oldnews
+```
+
+## File locations
+
+OldNews stores files in a `oldnews` directory within both [`$XDG_DATA_HOME` and
+`$XDG_CONFIG_HOME`](https://specifications.freedesktop.org/basedir-spec/latest/).
+If you wish to fully remove anything to do with OldNews you will need to
+remove those directories too.
+
+Expanding for the common locations, the files normally created are:
+
+- `~/.config/oldnews/configuration.json` -- The configuration file.
+- `~/.local/share/oldnews/*` -- The locally-held data.
+
+## Getting help
+
+If you need help, or have any ideas, please feel free to [raise an
+issue](https://github.com/davep/oldnews/issues) or [start a
+discussion](https://github.com/davep/oldnews/discussions). However, please
+keep in mind that at the moment the application is very much an ongoing work
+in progress; expect lots of obvious functionality to be missing and "coming
+soon"; perhaps also expect bugs.
+
+## TODO
+
+See [the TODO tag in
+issues](https://github.com/davep/oldnews/issues?q=is%3Aissue+is%3Aopen+label%3ATODO)
+to see what I'm planning.
+
+[//]: # (README.md ends here)

oldnews-0.1.0/README.md

@@ -0,0 +1,54 @@
+# OldNews - A TheOldReader client for the terminal
+
+## Introduction
+
+OldNews is a terminal-based client for
+[TheOldReader](https://theoldreader.com). Right now it is an evolving work
+in progress, built on top of [`oldas`](https://github.com/davep/oldas).
+
+## Installing
+
+### pipx
+
+The application can be installed using [`pipx`](https://pypa.github.io/pipx/):
+
+```sh
+$ pipx install oldnews
+```
+
+### uv
+
+The package can be install using [`uv`](https://docs.astral.sh/uv/getting-started/installation/):
+
+```sh
+uv tool install oldnews
+```
+
+## File locations
+
+OldNews stores files in a `oldnews` directory within both [`$XDG_DATA_HOME` and
+`$XDG_CONFIG_HOME`](https://specifications.freedesktop.org/basedir-spec/latest/).
+If you wish to fully remove anything to do with OldNews you will need to
+remove those directories too.
+
+Expanding for the common locations, the files normally created are:
+
+- `~/.config/oldnews/configuration.json` -- The configuration file.
+- `~/.local/share/oldnews/*` -- The locally-held data.
+
+## Getting help
+
+If you need help, or have any ideas, please feel free to [raise an
+issue](https://github.com/davep/oldnews/issues) or [start a
+discussion](https://github.com/davep/oldnews/discussions). However, please
+keep in mind that at the moment the application is very much an ongoing work
+in progress; expect lots of obvious functionality to be missing and "coming
+soon"; perhaps also expect bugs.
+
+## TODO
+
+See [the TODO tag in
+issues](https://github.com/davep/oldnews/issues?q=is%3Aissue+is%3Aopen+label%3ATODO)
+to see what I'm planning.
+
+[//]: # (README.md ends here)

oldnews-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "oldnews"
+version = "0.1.0"
+description = "A terminal-based client for TheOldReader"
+readme = "README.md"
+authors = [
+    { name = "Dave Pearson", email = "davep@davep.org" }
+]
+requires-python = ">=3.11"
+license = "GPL-3.0-or-later"
+keywords = [
+    "atom",
+    "client",
+    "Google Reader",
+    "RSS",
+    "TheOldReader",
+    "terminal",
+    "news-reader",
+    "news",
+]
+dependencies = [
+    "html-to-markdown>=2.15.0",
+    "oldas>=0.3.1",
+    "textual>=6.3.0",
+    "textual-enhanced>=1.2.0",
+    "typedal>=4.2.2",
+    "xdg-base-dirs>=6.0.2",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/davep/oldnews"
+Repository = "https://github.com/davep/oldnews"
+Documentation = "https://oldnews.davep.dev/"
+Source = "https://github.com/davep/oldnews"
+Issues = "https://github.com/davep/oldnews/issues"
+Discussions = "https://github.com/davep/oldnews/discussions"
+
+[project.scripts]
+oldnews = "oldnews.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.9.4,<0.10.0"]
+build-backend = "uv_build"
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.pyright]
+venvPath="."
+venv=".venv"
+exclude=[".venv"]
+
+[dependency-groups]
+dev = [
+    "codespell>=2.4.1",
+    "mypy>=1.18.2",
+    "pre-commit>=4.3.0",
+    "ruff>=0.14.0",
+    "textual-dev>=1.8.0",
+]

oldnews-0.1.0/src/oldnews/__init__.py

@@ -0,0 +1,17 @@
+"""A terminal-based client for TheOldReader."""
+
+##############################################################################
+# Python imports.
+from importlib.metadata import version
+
+##############################################################################
+# Main app information.
+__author__ = "Dave Pearson"
+__copyright__ = "Copyright 2025, Dave Pearson"
+__credits__ = ["Dave Pearson"]
+__maintainer__ = "Dave Pearson"
+__email__ = "davep@davep.org"
+__version__ = version("oldnews")
+__licence__ = "GPLv3+"
+
+### __init__.py ends here

oldnews-0.1.0/src/oldnews/__main__.py

@@ -0,0 +1,108 @@
+"""The main entry point to the application."""
+
+##############################################################################
+# Python imports.
+from argparse import ArgumentParser, Namespace
+from inspect import cleandoc
+from operator import attrgetter
+
+##############################################################################
+# Local imports.
+from . import __doc__, __version__
+from .data import initialise_database
+from .oldnews import OldNews
+
+
+##############################################################################
+def get_args() -> Namespace:
+    """Get the command line arguments.
+
+    Returns:
+        The arguments.
+    """
+
+    # Build the parser.
+    parser = ArgumentParser(
+        prog="oldnews",
+        description=__doc__,
+        epilog=f"v{__version__}",
+    )
+
+    # Add --version
+    parser.add_argument(
+        "-v",
+        "--version",
+        help="Show version information",
+        action="version",
+        version=f"%(prog)s v{__version__}",
+    )
+
+    # Add --license
+    parser.add_argument(
+        "--license",
+        "--licence",
+        help="Show license information",
+        action="store_true",
+    )
+
+    # Add --bindings
+    parser.add_argument(
+        "-b",
+        "--bindings",
+        help="List commands that can have their bindings changed",
+        action="store_true",
+    )
+
+    # Add --theme
+    parser.add_argument(
+        "-t",
+        "--theme",
+        help="Set the theme for the application (set to ? to list available themes)",
+    )
+
+    # Finally, parse the command line.
+    return parser.parse_args()
+
+
+##############################################################################
+def show_bindable_commands() -> None:
+    """Show the commands that can have bindings applied."""
+    from rich.console import Console
+    from rich.markup import escape
+
+    from .screens import Main
+
+    console = Console(highlight=False)
+    for command in sorted(Main.COMMAND_MESSAGES, key=attrgetter("__name__")):
+        if command().has_binding:
+            console.print(
+                f"[bold]{escape(command.__name__)}[/] [dim italic]- {escape(command.tooltip())}[/]"
+            )
+            console.print(
+                f"    [dim italic]Default: {escape(command.binding().key)}[/]"
+            )
+
+
+##############################################################################
+def show_themes() -> None:
+    """Show the available themes."""
+    for theme in sorted(OldNews(Namespace(theme=None)).available_themes):
+        if theme != "textual-ansi":
+            print(theme)
+
+
+##############################################################################
+def main() -> None:
+    """Main entry function."""
+    if (args := get_args()).license:
+        print(cleandoc(OldNews.HELP_LICENSE))
+    elif args.bindings:
+        show_bindable_commands()
+    elif args.theme == "?":
+        show_themes()
+    else:
+        initialise_database()
+        OldNews(args).run()
+
+
+### __main__.py ends here

oldnews-0.1.0/src/oldnews/commands/__init__.py

@@ -0,0 +1,31 @@
+"""Provides the command messages for the application."""
+
+##############################################################################
+# Local imports.
+from .main import (
+    Escape,
+    MarkAllRead,
+    Next,
+    NextUnread,
+    OpenArticle,
+    Previous,
+    PreviousUnread,
+    RefreshFromTheOldReader,
+    ToggleShowAll,
+)
+
+##############################################################################
+# Exports.
+__all__ = [
+    "Escape",
+    "MarkAllRead",
+    "Next",
+    "NextUnread",
+    "OpenArticle",
+    "Previous",
+    "PreviousUnread",
+    "RefreshFromTheOldReader",
+    "ToggleShowAll",
+]
+
+### __init__.py ends here

oldnews-0.1.0/src/oldnews/commands/main.py

@@ -0,0 +1,73 @@
+"""The main commands used within the application."""
+
+##############################################################################
+# Textual enhanced imports.
+from textual_enhanced.commands import Command
+
+
+##############################################################################
+class RefreshFromTheOldReader(Command):
+    """Connect to TheOldReader and refresh the local articles"""
+
+    BINDING_KEY = "ctrl+r"
+    SHOW_IN_FOOTER = True
+    FOOTER_TEXT = "Refresh"
+
+
+##############################################################################
+class ToggleShowAll(Command):
+    """Toggle between showing all and showing only unread"""
+
+    BINDING_KEY = "f2"
+
+
+##############################################################################
+class Escape(Command):
+    """Back out through the panes, or exit the app if the navigation pane has focus"""
+
+    BINDING_KEY = "escape, q"
+
+
+##############################################################################
+class NextUnread(Command):
+    """Navigate to the next unread article in the currently-selected category"""
+
+    BINDING_KEY = "n"
+
+
+##############################################################################
+class Next(Command):
+    """Navigate to the next article regardless of read status"""
+
+    BINDING_KEY = "N"
+
+
+##############################################################################
+class PreviousUnread(Command):
+    """Navigate to the previous unread article in the currently-selected category"""
+
+    BINDING_KEY = "p"
+
+
+##############################################################################
+class Previous(Command):
+    """Navigate to the next article regardless of read status"""
+
+    BINDING_KEY = "P"
+
+
+##############################################################################
+class OpenArticle(Command):
+    """Open the current article in the web browser"""
+
+    BINDING_KEY = "o"
+
+
+##############################################################################
+class MarkAllRead(Command):
+    """Mark all unread articles in the current category as read"""
+
+    BINDING_KEY = "R"
+
+
+### main.py ends here

oldnews-0.1.0/src/oldnews/data/__init__.py

@@ -0,0 +1,54 @@
+"""Provides functions and classes for managing the app's data."""
+
+##############################################################################
+# Local imports.
+from .auth import get_auth_token, set_auth_token
+from .config import (
+    Configuration,
+    load_configuration,
+    save_configuration,
+    update_configuration,
+)
+from .db import initialise_database
+from .last_grab import last_grabbed_data_at, remember_we_last_grabbed_at
+from .local_articles import (
+    get_local_articles,
+    get_unread_article_ids,
+    locally_mark_article_ids_read,
+    locally_mark_read,
+    save_local_articles,
+)
+from .local_folders import get_local_folders, save_local_folders
+from .local_subscriptions import get_local_subscriptions, save_local_subscriptions
+from .local_unread import LocalUnread, get_local_unread, total_unread
+from .navigation_state import get_navigation_state, save_navigation_state
+
+##############################################################################
+# Exports.
+__all__ = [
+    "Configuration",
+    "get_auth_token",
+    "get_local_articles",
+    "get_local_folders",
+    "get_local_subscriptions",
+    "get_local_unread",
+    "get_navigation_state",
+    "get_unread_article_ids",
+    "initialise_database",
+    "last_grabbed_data_at",
+    "load_configuration",
+    "locally_mark_read",
+    "locally_mark_article_ids_read",
+    "LocalUnread",
+    "remember_we_last_grabbed_at",
+    "save_configuration",
+    "save_local_articles",
+    "save_local_folders",
+    "save_local_subscriptions",
+    "save_navigation_state",
+    "set_auth_token",
+    "total_unread",
+    "update_configuration",
+]
+
+### __init__.py ends here

oldnews-0.1.0/src/oldnews/data/auth.py

@@ -0,0 +1,48 @@
+"""Code relating to TOR auth."""
+
+##############################################################################
+# Python imports.
+from pathlib import Path
+
+##############################################################################
+# Local imports.
+from .locations import data_dir
+
+
+##############################################################################
+def auth_token_file() -> Path:
+    """The location of the token file.
+
+    Returns:
+        The path to the token file.
+    """
+    return data_dir() / ".token"
+
+
+##############################################################################
+def get_auth_token() -> str | None:
+    """Get the TOR auth token.
+
+    Returns:
+        The token, if there is one, otherwise `None`.
+    """
+    if not auth_token_file().is_file():
+        return None
+    return auth_token_file().read_text(encoding="utf-8")
+
+
+##############################################################################
+def set_auth_token(token: str) -> str:
+    """Set the TOR auth token for later use.
+
+    Args:
+        token: The token to use.
+
+    Returns:
+        The token.
+    """
+    auth_token_file().write_text(token, encoding="utf-8")
+    return token
+
+
+### auth.py ends here

oldnews-0.1.0/src/oldnews/data/config.py

@@ -0,0 +1,113 @@
+"""Code relating to the application's configuration file."""
+
+##############################################################################
+# Python imports.
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from functools import lru_cache
+from json import dumps, loads
+from pathlib import Path
+from typing import Iterator
+
+##############################################################################
+# Local imports.
+from .locations import config_dir
+
+
+##############################################################################
+@dataclass
+class Configuration:
+    """The configuration data for the application."""
+
+    theme: str | None = None
+    """The theme for the application."""
+
+    bindings: dict[str, str] = field(default_factory=dict)
+    """Command keyboard binding overrides."""
+
+    local_history: int = 28
+    """The number of days to keep a local copy of an article."""
+
+    show_all: bool = False
+    """Should we show all articles, or just unread articles?"""
+
+    mark_read_on_read_timeout: float = 0.25
+    """How long to wait before marking an article as read, upon reading it."""
+
+    startup_refresh_holdoff_period: float = 600
+    """The number of seconds to wait before hitting TheOldReader again on startup."""
+
+
+##############################################################################
+def configuration_file() -> Path:
+    """The path to the file that holds the application configuration.
+
+    Returns:
+        The path to the configuration file.
+    """
+    return config_dir() / "configuration.json"
+
+
+##############################################################################
+def save_configuration(configuration: Configuration) -> Configuration:
+    """Save the given configuration.
+
+    Args:
+        The configuration to store.
+
+    Returns:
+        The configuration.
+    """
+    load_configuration.cache_clear()
+    configuration_file().write_text(
+        dumps(asdict(configuration), indent=4), encoding="utf-8"
+    )
+    return load_configuration()
+
+
+##############################################################################
+@lru_cache(maxsize=None)
+def load_configuration() -> Configuration:
+    """Load the configuration.
+
+    Returns:
+        The configuration.
+
+    Note:
+        As a side-effect, if the configuration doesn't exist a default one
+        will be saved to storage.
+
+        This function is designed so that it's safe and low-cost to
+        repeatedly call it. The configuration is cached and will only be
+        loaded from storage when necessary.
+    """
+    source = configuration_file()
+    return (
+        Configuration(**loads(source.read_text(encoding="utf-8")))
+        if source.exists()
+        else save_configuration(Configuration())
+    )
+
+
+##############################################################################
+@contextmanager
+def update_configuration() -> Iterator[Configuration]:
+    """Context manager for updating the configuration.
+
+    Loads the configuration and makes it available, then ensures it is
+    saved.
+
+    Example:
+        ```python
+        with update_configuration() as config:
+            config.meaning = 42
+        ```
+    """
+    configuration = load_configuration()
+    try:
+        yield configuration
+    finally:
+        save_configuration(configuration)
+
+
+### config.py ends here