Add high level OPML import/export API. #165

Author: lemon24

docs/api.rst

@@ -67,6 +67,13 @@ Data objects
 .. autoclass:: EntryUpdateStatus
     :members:
 
+.. autoclass:: FeedImportResult
+    :members:
+
+.. autoclass:: FeedExport
+    :members:
+
+
 
 Exceptions
 ----------
@@ -159,6 +166,9 @@ Exceptions
 .. autoexception:: ReaderWarning
     :show-inheritance:
 
+.. autoexception:: FeedImportError
+    :show-inheritance:
+
 
 .. _exctree:
 

docs/conf.py

@@ -23,7 +23,6 @@
     sys.modules[name] = unittest.mock.Mock()
 
 import reader
-import reader.opml
 
 extensions = [
     'sphinx_rtd_theme',

src/reader/__init__.py

@@ -64,6 +64,8 @@
     UpdateResult as UpdateResult,
     UpdatedFeed as UpdatedFeed,
     EntryUpdateStatus as EntryUpdateStatus,
+    FeedImportResult as FeedImportResult,
+    FeedExport as FeedExport,
 )
 
 from .exceptions import (
@@ -91,6 +93,7 @@
     InvalidPluginError as InvalidPluginError,
     PluginInitError as PluginInitError,
     ReaderWarning as ReaderWarning,
+    FeedImportError as FeedImportError,
 )
 
 # Constants.

src/reader/_app/__init__.py

@@ -167,18 +167,8 @@ def feeds():
         feeds = reader.get_feeds(**kwargs)
 
     if request.args.get('format', '').lower() == 'opml':
-        # TODO: good candidate for a Reader method
-        feeds = (f for f in feeds if not f.url.startswith('reader:'))
-
-        now = reader._now()
-        # TODO: title should contain branding
-        title = 'reader feeds'
-        filename = f"{title.replace(' ', '-')}-{now:%Y-%m-%d-%H-%M-%S}.opml"
-
-        return opml.unparse(feeds, title=title, created=now), {
-            'Content-Type': 'application/xml',
-            'Content-Disposition': f'attachment; filename="{filename}"',
-        }
+        export = reader.export_feeds(feeds)
+        return export.content, export.headers
 
     return stream_template(
         'feeds.html',
@@ -296,26 +286,12 @@ def import_feeds():
     if request.method == 'POST':
         if file := request.files.get('file'):
             try:
-                feeds = opml.parse(file.stream)
+                parsed_feeds = [asdict(f) for f in opml.parse(file.stream)]
             except opml.OPMLError as e:
                 error = str(e)
-            else:
-                # TODO: good candidate for a Reader method
-                feeds = (f for f in feeds if not f.url.startswith('reader:'))
-                parsed_feeds = [asdict(f) for f in feeds]
         else:
-            feeds = [opml.Feed(**json.loads(f)) for f in request.form.getlist('feed')]
-            # TODO: good candidate for a Reader method
-            imported_feeds = []
-            for feed in feeds:
-                try:
-                    reader.add_feed(feed)
-                except InvalidFeedURLError as e:
-                    imported_feeds.append((feed, False, f"invalid feed: {e}"))
-                except FeedExistsError:
-                    imported_feeds.append((feed, False, None))
-                else:
-                    imported_feeds.append((feed, True, None))
+            feeds = (opml.Feed(**json.loads(f)) for f in request.form.getlist('feed'))
+            imported_feeds = list(reader.import_feeds_iter(feeds))
             # TODO: out of band update (unlike add, there's too many to do here)
 
     return render_template(

src/reader/_app/templates/import_feeds.html

@@ -89,23 +89,24 @@ <h2 class="h5 mb-1" style="font-size: 1.125rem">
 
   <p>Imported feeds:</p>
 
-  {% for feed, added, error in imported_feeds %}
+  {% for result in imported_feeds %}
+  {%- set feed = result.feed %}
   <div class="mb-3">
 
     {#- NOTE similarity to feeds page feeds #}
     <h2 class="h5 mb-1" style="font-size: 1.125rem">
         {{ macros.title_href(
           feed.title or feed.url,
-          url_for('.entries', feed=feed.url) if not error else None,
+          url_for('.entries', feed=feed.url) if not result.error else None,
           external=feed.link,
           feed_url=feed.url,
         ) }}
     </h2>
 
-    {% if added %}
+    {% if result.added %}
       {{ macros.subtitle("feed added", 'text-success-emphasis') }}
-    {% elif error %}
-      {{ macros.subtitle(error, 'text-danger-emphasis') }}
+    {% elif result.error %}
+      {{ macros.subtitle("invalid feed: {}".format(result.error), 'text-danger-emphasis') }}
     {% else %}
       {{ macros.subtitle("feed already exists", 'text-secondary') }}
     {% endif %}

src/reader/core.py

@@ -13,6 +13,7 @@
 from datetime import timezone
 from types import MappingProxyType
 from typing import Any
+from typing import IO
 from typing import Literal
 from typing import overload
 from typing import Self
@@ -40,6 +41,7 @@
 from ._utils import MapContextManager
 from ._utils import zero_or_one
 from .exceptions import EntryNotFoundError
+from .exceptions import FeedError
 from .exceptions import FeedExistsError
 from .exceptions import FeedNotFoundError
 from .exceptions import ParseError
@@ -64,6 +66,8 @@
 from .types import EntryUpdateStatus
 from .types import Feed
 from .types import FeedCounts
+from .types import FeedExport
+from .types import FeedImportResult
 from .types import FeedInput
 from .types import FeedSort
 from .types import JSONType
@@ -76,6 +80,7 @@
 from .types import UpdateResult
 
 if TYPE_CHECKING:  # pragma: no cover
+    from . import opml
     from ._parser import Parser
 
 
@@ -2181,6 +2186,80 @@ def delete_tag(
             if not missing_ok:
                 raise
 
+    def import_feeds(self, file: IO[bytes], /) -> None:
+        """Import feeds from an OPML subscription list.
+
+        Existing and unsupported feeds are silently skipped.
+
+        Args:
+            file (file): A binary file.
+
+        Raises:
+            FeedImportError: If the file could not be parsed.
+            StorageError
+
+        .. versionadded:: 3.23
+
+        """
+        from . import opml
+
+        for _ in self.import_feeds_iter(opml.parse(file)):
+            pass
+
+    def import_feeds_iter(
+        self, feeds: Iterable[opml.Feed], /
+    ) -> Iterable[FeedImportResult]:
+        """Import feeds returned by :func:`reader.opml.parse`.
+
+        Args:
+            feeds (iterable(reader.opml.Feed)): The feeds to import.
+
+        Yields:
+            :class:`FeedImportResult`: The feed and whether it was added.
+
+        Raises:
+            StorageError
+
+        .. versionadded:: 3.23
+
+        """
+        for feed in feeds:
+            try:
+                self.add_feed(feed)
+            except FeedError as e:
+                yield FeedImportResult(feed, e)
+            else:
+                yield FeedImportResult(feed)
+
+    def export_feeds(self, feeds: Iterable[Feed] | None = None, /) -> FeedExport:
+        """Export all or some feeds as an OPML subscription list.
+
+        Args:
+            feeds (iterable(Feed)): The feeds to export; if None, export all feeds.
+
+        Returns:
+            FeedExport: The OPML export.
+
+        Raises:
+            StorageError
+
+        .. versionadded:: 3.23
+
+        """
+        from . import opml
+
+        if feeds is None:
+            feeds = self.get_feeds()
+
+        feeds = (f for f in feeds if not f.url.startswith('reader:'))
+
+        now = self._now()
+        title = 'reader feeds'
+        filename = f"{title.replace(' ', '-')}-{now:%Y-%m-%d-%H-%M-%S}.opml"
+        content = opml.unparse(feeds, title=title, created=now)
+
+        return FeedExport(content, filename)
+
     def make_reader_reserved_name(self, key: str, /) -> str:
         """Create a *reader*-reserved tag name.
         See :ref:`reserved names` for details.

src/reader/exceptions.py

@@ -407,3 +407,11 @@ class ChangeTrackingNotEnabledError(StorageError):
     """
 
     _default_message = "operation not supported with change tracking disabled"
+
+
+class FeedImportError(ReaderError):
+    """An error occured while parsing a feed import.
+
+    .. versionadded:: 3.23
+
+    """

src/reader/opml.py

@@ -58,7 +58,7 @@ class Feed:
     subtitle: str | None = None
 
 
-class OPMLError(reader.ReaderError):
+class OPMLError(reader.FeedImportError):
     """An error occurred while parsing an OPML subscription list."""
 
 
@@ -82,7 +82,7 @@ def parse(file: IO[bytes], max_depth: int = 10) -> list[Feed]:
     try:
         tree = etree.parse(file)
     except (etree.ParseError, LookupError) as e:
-        raise OPMLError(f"XML error: {e}") from e
+        raise OPMLError("XML error") from e
 
     root = tree.getroot()
     if root.tag.lower() != 'opml':

src/reader/types.py

@@ -19,15 +19,21 @@
 from typing import overload
 from typing import Protocol
 from typing import Self
+from typing import TYPE_CHECKING
 from typing import TypedDict
 from typing import Union
 
+from reader.exceptions import FeedError
+from reader.exceptions import FeedExistsError
 from reader.exceptions import UpdateError
 
 # can't be defined here because of circular imports
 from reader._utils import MISSING as MISSING  # isort: skip # noqa: F401
 from reader._utils import MissingType as MissingType  # isort: skip # noqa: F401
 
+if TYPE_CHECKING:
+    from . import opml
+
 
 class _namedtuple_compat:
     """Add namedtuple-like methods to a dataclass."""
@@ -1234,3 +1240,53 @@ class UpdateConfig(TypedDict, total=False):
 
     #: Update jitter, as a ratio of :attr:`interval`, between 0.0 and 1.0.
     jitter: float
+
+
+@dataclass(frozen=True)
+class FeedImportResult:
+    """The result of importing a single feed.
+
+    .. versionadded:: 3.23
+
+    """
+
+    #: The feed parsed from the import file.
+    feed: opml.Feed
+
+    #: Exception raised by :meth:`~add_feed`, if any.
+    exception: FeedError | None = None
+
+    @property
+    def added(self) -> bool:
+        """Whether the feed was added."""
+        return not self.exception
+
+    @property
+    def error(self) -> FeedError | None:
+        """Any error adding the feed (excluding already existing feed)."""
+        if not self.exception or isinstance(self.exception, FeedExistsError):
+            return None
+        return self.exception
+
+
+@dataclass(frozen=True)
+class FeedExport:
+    """A feed export.
+
+    .. versionadded:: 3.23
+
+    """
+
+    #: The export content.
+    content: bytes
+
+    #: Suggested filename (derived from the title and date in the content).
+    filename: str
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """Content-* HTTP headers describing the content."""
+        return {
+            'Content-Type': 'application/xml; charset=utf-8',
+            'Content-Disposition': f'attachment; filename="{self.filename}"',
+        }