packaging: restore Python 3.8 and 3.9 (#304)

Author: Guts

.github/workflows/lint-and-tests.yml

@@ -22,6 +22,8 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
+          - "3.8"
+          - "3.9"
           - "3.10"
           - "3.11"
           - "3.12"

.pre-commit-config.yaml

@@ -35,15 +35,15 @@ repos:
     hooks:
       - id: pyupgrade
         args:
-          - "--py310-plus"
+          - "--py38-plus"
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: "v0.4.7"
     hooks:
       - id: ruff
         args:
           - --fix-only
-          - --target-version=py310
+          - --target-version=py38
 
   - repo: https://github.com/pycqa/isort
     rev: 5.13.2
@@ -59,7 +59,7 @@ repos:
     hooks:
       - id: black
         args:
-          - --target-version=py310
+          - --target-version=py38
 
   - repo: https://github.com/pycqa/flake8
     rev: 7.0.0

mkdocs_rss_plugin/__about__.py

@@ -1,9 +1,9 @@
 #! python3  # noqa: E265
 
 """
-    Metadata about the package to easily retrieve informations about it.
+Metadata about the package to easily retrieve informations about it.
 
-    See: https://packaging.python.org/guides/single-sourcing-package-version/
+See: https://packaging.python.org/guides/single-sourcing-package-version/
 """
 
 # ############################################################################

mkdocs_rss_plugin/config.py

@@ -4,9 +4,6 @@
 # ########## Libraries #############
 # ##################################
 
-# standard
-from typing import Union
-
 # 3rd party
 from mkdocs.config import config_options
 from mkdocs.config.base import Config
@@ -21,8 +18,8 @@ class _DateFromMeta(Config):
 
     #  TODO: remove deprecated code in future version. Only str values will be accepted
     # for as_creation and as_update
-    as_creation = config_options.Type(Union[bool, str], default="git")
-    as_update = config_options.Type(Union[bool, str], default="git")
+    as_creation = config_options.Type(str, default="git")
+    as_update = config_options.Type(str, default="git")
     datetime_format = config_options.Type(str, default="%Y-%m-%d %H:%M")
     default_time = config_options.Type(str, default="00:00")
     default_timezone = config_options.Type(str, default="UTC")

mkdocs_rss_plugin/integrations/theme_material_social_plugin.py

@@ -8,6 +8,7 @@
 import json
 from hashlib import md5
 from pathlib import Path
+from typing import Optional
 
 # 3rd party
 from mkdocs.config.defaults import MkDocsConfig
@@ -41,7 +42,7 @@ class IntegrationMaterialSocialCards:
     IS_SOCIAL_PLUGIN_CARDS_ENABLED: bool = True
     IS_THEME_MATERIAL: bool = False
     IS_INSIDERS: bool = False
-    CARDS_MANIFEST: dict | None = None
+    CARDS_MANIFEST: Optional[dict] = None
 
     def __init__(self, mkdocs_config: MkDocsConfig, switch_force: bool = True) -> None:
         """Integration instantiation.
@@ -103,7 +104,7 @@ def is_mkdocs_theme_material(self, mkdocs_config: MkDocsConfig) -> bool:
         self.IS_THEME_MATERIAL = mkdocs_config.theme.name == "material"
         return self.IS_THEME_MATERIAL
 
-    def is_mkdocs_theme_material_insiders(self) -> bool | None:
+    def is_mkdocs_theme_material_insiders(self) -> Optional[bool]:
         """Check if the material theme is community or insiders edition.
 
         Returns:
@@ -195,7 +196,7 @@ def is_social_plugin_enabled_page(
             "cards", fallback_value
         )
 
-    def load_cache_cards_manifest(self) -> dict | None:
+    def load_cache_cards_manifest(self) -> Optional[dict]:
         """Load social cards manifest if the file exists.
 
         Returns:
@@ -258,8 +259,8 @@ def get_social_cards_cache_dir(self, mkdocs_config: MkDocsConfig) -> Path:
         return self.social_cards_cache_dir
 
     def get_social_card_build_path_for_page(
-        self, mkdocs_page: Page, mkdocs_site_dir: str | None = None
-    ) -> Path | None:
+        self, mkdocs_page: Page, mkdocs_site_dir: Optional[str] = None
+    ) -> Optional[Path]:
         """Get social card path in Mkdocs build dir for a specific page.
 
         Args:
@@ -287,7 +288,7 @@ def get_social_card_build_path_for_page(
             logger.debug(f"Not found: {expected_built_card_path}")
             return None
 
-    def get_social_card_cache_path_for_page(self, mkdocs_page: Page) -> Path | None:
+    def get_social_card_cache_path_for_page(self, mkdocs_page: Page) -> Optional[Path]:
         """Get social card path in social plugin cache folder for a specific page.
 
         Note:
@@ -346,7 +347,7 @@ def get_social_card_cache_path_for_page(self, mkdocs_page: Page) -> Path | None:
     def get_social_card_url_for_page(
         self,
         mkdocs_page: Page,
-        mkdocs_site_url: str | None = None,
+        mkdocs_site_url: Optional[str] = None,
     ) -> str:
         """Get social card URL for a specific page in documentation.
 

mkdocs_rss_plugin/models.py

@@ -7,7 +7,7 @@
 # standard
 from datetime import datetime
 from pathlib import Path
-from typing import NamedTuple
+from typing import NamedTuple, Optional
 
 
 # ############################################################################
@@ -16,14 +16,14 @@
 class PageInformation(NamedTuple):
     """Data type to set and get page information in order to produce the RSS feed."""
 
-    abs_path: Path | None = None
-    categories: list | None = None
-    authors: tuple | None = None
-    created: datetime | None = None
-    description: str | None = None
-    guid: str | None = None
-    image: str | None = None
-    title: str | None = None
-    updated: datetime | None = None
-    url_comments: str | None = None
-    url_full: str | None = None
+    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_rss_plugin/plugin.py

@@ -11,6 +11,7 @@
 from email.utils import formatdate
 from pathlib import Path
 from re import compile as re_compile
+from typing import List, Optional
 
 # 3rd party
 from jinja2 import Environment, FileSystemLoader, select_autoescape
@@ -57,7 +58,7 @@ class GitRssPlugin(BasePlugin[RssPluginConfig]):
     def __init__(self):
         """Instantiation."""
         # pages storage
-        self.pages_to_filter: list[PageInformation] = []
+        self.pages_to_filter: List[PageInformation] = []
         # prepare output feeds
         self.feed_created: dict = {}
         self.feed_updated: dict = {}
@@ -229,7 +230,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
     @event_priority(priority=-75)
     def on_page_content(
         self, html: str, page: Page, config: MkDocsConfig, files: Files
-    ) -> str | None:
+    ) -> Optional[str]:
         """The page_content event is called after the Markdown text is rendered to HTML
             (but before being passed to a template) and can be used to alter the HTML
             body of the page.

mkdocs_rss_plugin/timezoner.py

@@ -2,7 +2,7 @@
 
 
 """
-    Manage timezones for pages date(time)s using zoneinfo module, added in Python 3.9.
+Manage timezones for pages date(time)s using zoneinfo module, added in Python 3.9.
 
 """
 

mkdocs_rss_plugin/timezoner_pre39.py

@@ -0,0 +1,56 @@
+#! python3  # noqa: E265
+
+
+"""
+Manage timezones for pages date(time)s using pytz module.
+Meant to be dropped when Python 3.8 reaches EOL.
+"""
+
+# ############################################################################
+# ########## Libraries #############
+# ##################################
+
+# standard library
+from datetime import datetime
+
+# 3rd party
+import pytz
+from mkdocs.plugins import get_plugin_logger
+
+# package
+from mkdocs_rss_plugin.constants import MKDOCS_LOGGER_NAME
+
+# ############################################################################
+# ########## Globals #############
+# ################################
+
+
+logger = get_plugin_logger(MKDOCS_LOGGER_NAME)
+
+
+# ############################################################################
+# ########## Functions ###########
+# ################################
+
+
+def set_datetime_zoneinfo(
+    input_datetime: datetime, config_timezone: str = "UTC"
+) -> datetime:
+    """Apply timezone to a naive datetime.
+
+    :param input_datetime: offset-naive datetime
+    :type input_datetime: datetime
+    :param config_timezone: name of timezone as registered in IANA database,
+    defaults to "UTC". Example : Europe/Paris.
+    :type config_timezone: str, optional
+
+    :return: offset-aware datetime
+    :rtype: datetime
+    """
+    if input_datetime.tzinfo:
+        return input_datetime
+    elif not config_timezone:
+        return input_datetime.replace(tzinfo=pytz.utc)
+    else:
+        config_tz = pytz.timezone(config_timezone)
+        return config_tz.localize(input_datetime)