update(plugin): factorize image fetching and page and RSS item related models

Author: Guts

mkdocs_rss_plugin/integrations/theme_material_social_plugin.py

@@ -23,6 +23,7 @@
 from mkdocs_rss_plugin.integrations.theme_material_blog_plugin import (
     IntegrationMaterialBlog,
 )
+from mkdocs_rss_plugin.models import MkdocsPageSubset
 
 # conditional
 try:
@@ -167,18 +168,18 @@ def is_social_plugin_and_cards_enabled_mkdocs(
         return True
 
     def is_social_plugin_enabled_page(
-        self, mkdocs_page: Page, fallback_value: bool = True
+        self, mkdocs_page: MkdocsPageSubset, fallback_value: bool = True
     ) -> bool:
         """Check if the social plugin is enabled or disabled for a specific page. Plugin
             has to be enabled in Mkdocs configuration before.
 
         Args:
-            mkdocs_page (Page): Mkdocs page object.
-            fallback_value (bool, optional): fallback value. It might be the
+            mkdocs_page: Mkdocs page object.
+            fallback_value: fallback value. It might be the
                 'plugins.social.cards.enabled' option in Mkdocs config. Defaults to True.
 
         Returns:
-            bool: True if the social cards are enabled for a page.
+            True if the social cards are enabled for a page.
         """
         return mkdocs_page.meta.get("social", {"cards": fallback_value}).get(
             "cards", fallback_value
@@ -374,18 +375,18 @@ def get_social_card_cache_path_for_page(self, mkdocs_page: Page) -> Optional[Pat
 
     def get_social_card_url_for_page(
         self,
-        mkdocs_page: Page,
+        mkdocs_page: MkdocsPageSubset,
         mkdocs_site_url: Optional[str] = None,
     ) -> str:
         """Get social card URL for a specific page in documentation.
 
         Args:
-            mkdocs_page (Page): Mkdocs page object.
-            mkdocs_site_url (Optional[str], optional): Mkdocs site URL. If None, the
+            mkdocs_page: subset of Mkdocs page object.
+            mkdocs_site_url: Mkdocs site URL. If None, the
                 'class.mkdocs_site_url' is used. is Defaults to None.
 
         Returns:
-            str: URL to the image once published
+            URL to the image once published
         """
         if mkdocs_site_url is None and self.mkdocs_site_url:
             mkdocs_site_url = self.mkdocs_site_url
@@ -394,7 +395,7 @@ def get_social_card_url_for_page(
         # matching src path in the build folder, regardless of the page type.
         page_social_card = (
             f"{mkdocs_site_url}{self.social_cards_dir}/"
-            f"{Path(mkdocs_page.file.src_uri).with_suffix('.png')}"
+            f"{Path(mkdocs_page.src_uri).with_suffix('.png')}"
         )
         logger.debug(f"Use social card url: {page_social_card}")
 

mkdocs_rss_plugin/models.py

@@ -4,14 +4,15 @@
 # ########## Libraries #############
 # ##################################
 
+# for class autoref typing
+from __future__ import annotations
 
 # standard
 from collections.abc import MutableMapping
 from dataclasses import dataclass, field
 from datetime import datetime
-from email.utils import format_datetime
 from pathlib import Path
-from typing import Any, Literal, Optional
+from typing import Any
 
 # 3rd party
 from mkdocs.structure.pages import Page
@@ -28,19 +29,21 @@
 class MkdocsPageSubset:
     """Minimal subset of a Mkdocs Page with only necessary attributes for plugin needs."""
 
+    abs_src_path: str
     dest_uri: str
     src_uri: str
-    title: Optional[str] = None
-    meta: Optional[MutableMapping[str, Any]] = None
+    title: str | None = None
+    meta: MutableMapping[str, Any] | None = None
 
     @classmethod
-    def from_page(cls, page: Page) -> "MkdocsPageSubset":
+    def from_page(cls, page: Page) -> MkdocsPageSubset:
         """Create a PageSubset from a Mkdocs page.
 
         Args:
             page: MkDocs Page object
         """
         return cls(
+            abs_src_path=page.file.abs_src_path,
             meta=page.meta,
             title=page.title,
             src_uri=page.file.src_uri,
@@ -52,34 +55,40 @@ def from_page(cls, page: Page) -> "MkdocsPageSubset":
 class PageInformation:
     """Object describing a page information gathered from Mkdocs and used as feed's item."""
 
-    abs_path: Optional[Path] = None
-    categories: Optional[list] = None
-    authors: Optional[tuple] = None
-    created: Optional[datetime] = None
-    description: Optional[str] = None
-    guid: Optional[str] = None
-    image: Optional[str] = None
-    title: Optional[str] = None
-    updated: Optional[datetime] = None
-    url_comments: Optional[str] = None
-    url_full: Optional[str] = None
-    _mkdocs_page_ref: Optional[MkdocsPageSubset] = field(
+    abs_path: Path | None = None
+    categories: list | None = None
+    authors: tuple | None = None
+    comments_url: str | None = None
+    created: datetime | None = None
+    description: str | None = None
+    guid: str | None = None
+    image: tuple[str, str, int] | None = None
+    link: str | None = None
+    pub_date: str | None = None
+    pub_date_3339: str | None = None
+    title: str | None = None
+    updated: datetime | None = None
+    # private
+    _mkdocs_page_ref: MkdocsPageSubset | None = field(
         default=None, repr=False, compare=False
     )
 
-    def as_rss_item(self, date_type: Literal["created", "updated"]) -> dict:
-        """Return the object as a dictionary formatted for RSS item."""
-        pub_date: datetime = getattr(self, date_type)
+    def as_rss_item(self) -> dict:
+        """Return the object as a dictionary formatted for RSS item.
+
+        Returns:
+            page as RSS item dict
+        """
         return {
             "authors": self.authors,
             "categories": self.categories,
-            "comments_url": self.url_comments,
+            "comments_url": self.comments_url,
             "description": self.description,
             "guid": self.guid,
             "image": self.image,
-            "link": self.url_full,
-            "pubDate": format_datetime(dt=pub_date),
-            "pubDate3339": pub_date.isoformat("T"),
+            "link": self.link,
+            "pub_date": self.pub_date,
+            "pubd_date_3339": self.pub_date_3339,
             "title": self.title,
         }
 
@@ -88,18 +97,18 @@ def as_rss_item(self, date_type: Literal["created", "updated"]) -> dict:
 class RssFeedBase:
     """Object describing a feed."""
 
-    author: Optional[str] = None
-    buildDate: Optional[str] = None
-    copyright: Optional[str] = None
-    description: Optional[str] = None
+    author: str | None = None
+    buildDate: str | None = None
+    copyright: str | None = None
+    description: str | None = None
     entries: list[PageInformation] = field(default_factory=list)
     generator: str = f"{__title__} - v{__version__}"
-    html_url: Optional[str] = None
-    json_url: Optional[str] = None
-    language: Optional[str] = None
-    logo_url: Optional[str] = None
-    pubDate: Optional[str] = None
-    repo_url: Optional[str] = None
-    rss_url: Optional[str] = None
-    title: Optional[str] = None
-    ttl: Optional[int] = None
+    html_url: str | None = None
+    json_url: str | None = None
+    language: str | None = None
+    logo_url: str | None = None
+    pubDate: str | None = None
+    repo_url: str | None = None
+    rss_url: str | None = None
+    title: str | None = None
+    ttl: int | None = None

mkdocs_rss_plugin/plugin.py

@@ -9,7 +9,7 @@
 from copy import deepcopy
 from dataclasses import asdict
 from datetime import datetime
-from email.utils import formatdate
+from email.utils import format_datetime, formatdate
 from pathlib import Path
 from re import compile as re_compile
 from typing import Literal, Optional
@@ -24,7 +24,7 @@
 from mkdocs.utils import get_build_timestamp
 
 # package modules
-from mkdocs_rss_plugin.__about__ import __title__, __uri__, __version__
+from mkdocs_rss_plugin.__about__ import __title__, __version__
 from mkdocs_rss_plugin.config import RssPluginConfig
 from mkdocs_rss_plugin.constants import (
     DEFAULT_TEMPLATE_FILENAME,
@@ -331,22 +331,18 @@ def on_page_content(
                 categories=self.util.get_categories_from_meta(
                     in_page=page, categories_labels=self.config.categories
                 ),
+                comments_url=page_url_comments,
                 created=page_dates[0],
                 description=self.util.get_description_or_abstract(
                     in_page=page,
                     chars_count=self.config.abstract_chars_count,
                     abstract_delimiter=self.config.abstract_delimiter,
                 ),
                 guid=page.canonical_url,
-                image=self.util.get_image(
-                    in_page=page,
-                    # below let it as old dict get method to handle custom fallback value
-                    base_url=config.get("site_url", __uri__),
-                ),
+                link=page_url_full,
                 title=page.title,
                 updated=page_dates[1],
-                url_comments=page_url_comments,
-                url_full=page_url_full,
+                # for later fetch
                 _mkdocs_page_ref=MkdocsPageSubset.from_page(page),
             )
         )
@@ -400,6 +396,32 @@ def on_post_build(self, config: config_options.Config) -> None:
             )
         )
 
+        # load RSS items images (enclosures)
+        logger.debug(
+            f"Loading images for {len(self.feed_created.entries)} pages by creation "
+            f"and {len(self.feed_updated.entries)} pages by update"
+        )
+
+        for page in self.feed_created.entries:
+            # set pub date
+            page.pub_date = format_datetime(dt=page.created)
+            page.pub_date_3339 = page.created.isoformat("T")
+            # fetch image
+            if page.image is None:
+                page.image = self.util.get_image(
+                    in_page=page._mkdocs_page_ref, base_url=config.site_url
+                )
+
+        for page in self.feed_updated.entries:
+            # set pub date
+            page.pub_date = format_datetime(dt=page.updated)
+            page.pub_date_3339 = page.updated.isoformat("T")
+            # fetch image
+            if page.image is None:
+                page.image = self.util.get_image(
+                    in_page=page._mkdocs_page_ref, base_url=config.site_url
+                )
+
         # RSS
         if self.config.rss_feed_enabled:
             # write feeds according to the pretty print option
@@ -456,14 +478,14 @@ def on_post_build(self, config: config_options.Config) -> None:
         if self.config.json_feed_enabled:
             with out_json_created.open(mode="w", encoding="UTF8") as fp:
                 json.dump(
-                    self.util.feed_to_json(asdict(self.feed_created)),
+                    self.util.feed_to_json(self.feed_created),
                     fp,
                     indent=4 if self.config.pretty_print else None,
                 )
 
             with out_json_updated.open(mode="w", encoding="UTF8") as fp:
                 json.dump(
-                    self.util.feed_to_json(asdict(self.feed_updated), updated=True),
+                    self.util.feed_to_json(self.feed_updated, updated=True),
                     fp,
                     indent=4 if self.config.pretty_print else None,
                 )

mkdocs_rss_plugin/templates/rss.xml.jinja2

@@ -47,7 +47,7 @@
       {% endif %}
       <description>{{ item.description|e }}</description>
       {% if item.link is not none %}<link>{{ item.link|e }}</link>{% endif %}
-      <pubDate>{{ item.pubDate }}</pubDate>
+      <pubDate>{{ item.pub_date }}</pubDate>
       {% if item.link is not none %}<source url="{{ feed.rss_url }}">{{ feed.title }}</source>{% endif %}
       {% if item.comments_url is not none %}<comments>{{ item.comments_url|e }}</comments>{% endif %}
       {% if item.guid is not none %}<guid isPermaLink="true">{{ item.guid }}</guid>{% endif %}