codex
887 lines
33 KiB
Python
887 lines
33 KiB
Python
#! python3 # noqa: E265
|
|
|
|
# ############################################################################
|
|
# ########## Libraries #############
|
|
# ##################################
|
|
|
|
# standard library
|
|
from collections.abc import Iterable
|
|
from datetime import date, datetime
|
|
from functools import lru_cache
|
|
from mimetypes import guess_type
|
|
from pathlib import Path
|
|
from typing import Any, Literal
|
|
from urllib.parse import urlencode, urlparse, urlunparse
|
|
|
|
# 3rd party
|
|
import markdown
|
|
import urllib3
|
|
from cachecontrol import CacheControl
|
|
from cachecontrol.caches.file_cache import SeparateBodyFileCache
|
|
from git import (
|
|
GitCommandError,
|
|
GitCommandNotFound,
|
|
InvalidGitRepositoryError,
|
|
Optional,
|
|
Repo,
|
|
)
|
|
from mkdocs.config.defaults import MkDocsConfig
|
|
from mkdocs.plugins import get_plugin_logger
|
|
from mkdocs.structure.pages import Page
|
|
from mkdocs.utils import get_build_datetime
|
|
from requests import Session
|
|
from requests.exceptions import ConnectionError, HTTPError
|
|
|
|
# package
|
|
from mkdocs_rss_plugin.constants import (
|
|
DEFAULT_CACHE_FOLDER,
|
|
MKDOCS_LOGGER_NAME,
|
|
REMOTE_REQUEST_HEADERS,
|
|
)
|
|
from mkdocs_rss_plugin.git_manager.ci import CiHandler
|
|
from mkdocs_rss_plugin.integrations.theme_material_blog_plugin import (
|
|
IntegrationMaterialBlog,
|
|
)
|
|
from mkdocs_rss_plugin.integrations.theme_material_social_plugin import (
|
|
IntegrationMaterialSocialCards,
|
|
)
|
|
from mkdocs_rss_plugin.models import MkdocsPageSubset, PageInformation, RssFeedBase
|
|
from mkdocs_rss_plugin.timezoner import set_datetime_zoneinfo
|
|
|
|
# ############################################################################
|
|
# ########## Globals #############
|
|
# ################################
|
|
|
|
logger = get_plugin_logger(MKDOCS_LOGGER_NAME)
|
|
urllib3.disable_warnings() # disable warnings for unverified requests
|
|
|
|
# ############################################################################
|
|
# ########## Classes #############
|
|
# ################################
|
|
|
|
|
|
class Util:
|
|
"""Plugin logic."""
|
|
|
|
git_is_valid: bool = False
|
|
|
|
def __init__(
|
|
self,
|
|
cache_dir: Path = DEFAULT_CACHE_FOLDER,
|
|
integration_material_blog: Optional[IntegrationMaterialBlog] = None,
|
|
integration_material_social_cards: Optional[
|
|
IntegrationMaterialSocialCards
|
|
] = None,
|
|
mkdocs_command_is_on_serve: bool = False,
|
|
path: str = ".",
|
|
use_git: bool = True,
|
|
) -> None:
|
|
"""Class hosting the plugin logic.
|
|
|
|
Args:
|
|
cache_dir: _description_. Defaults to DEFAULT_CACHE_FOLDER.
|
|
integration_material_blog (bool, optional): option to enable
|
|
integration with Blog plugin from Material theme. \
|
|
Defaults to None.
|
|
integration_material_social_cards (bool, optional): option to enable
|
|
integration with Social Cards plugin from Material theme. \
|
|
Defaults to None.
|
|
mkdocs_command_is_on_serve: _description_. Defaults to False.
|
|
path (str, optional): path to the git repository to use. Defaults to ".".
|
|
use_git (bool, optional): flag to use git under the hood or not. \
|
|
Defaults to True.
|
|
"""
|
|
self.mkdocs_command_is_on_serve = mkdocs_command_is_on_serve
|
|
if self.mkdocs_command_is_on_serve:
|
|
logger.debug(
|
|
"Mkdocs serve - Fetching remote images length is disabled to avoid "
|
|
"HTTP errors."
|
|
)
|
|
|
|
if use_git:
|
|
logger.debug("Git use is enabled.")
|
|
try:
|
|
git_repo = Repo(path, search_parent_directories=True)
|
|
self.repo = git_repo.git
|
|
self.git_is_valid = True
|
|
except InvalidGitRepositoryError as err:
|
|
logger.warning(
|
|
f"Path '{path}' is not a valid git directory. "
|
|
"Only page.meta (YAML frontmatter will be used). "
|
|
"To disable this warning, set 'use_git: false' in plugin options. "
|
|
f"Trace: {err}"
|
|
)
|
|
self.git_is_valid = False
|
|
use_git = False
|
|
except Exception as err:
|
|
logger.warning(
|
|
f"Unrecognized git issue. "
|
|
"Only page.meta (YAML frontmatter will be used). "
|
|
"To disable this warning, set 'use_git: false' in plugin options. "
|
|
f"Trace: {err}"
|
|
)
|
|
self.git_is_valid = False
|
|
use_git = False
|
|
|
|
# Checks if user is running builds on CI and raise appropriate warnings
|
|
if self.git_is_valid:
|
|
CiHandler(git_repo.git).raise_ci_warnings()
|
|
else:
|
|
self.git_is_valid = False
|
|
logger.debug(
|
|
"Git use is disabled. Only page.meta (YAML frontmatter will be used). "
|
|
)
|
|
|
|
# save git enable/disable status
|
|
self.use_git = use_git
|
|
|
|
# save integrations
|
|
self.material_blog = integration_material_blog
|
|
self.social_cards = integration_material_social_cards
|
|
|
|
# http/s session
|
|
session = Session()
|
|
session.headers.update(REMOTE_REQUEST_HEADERS)
|
|
self.req_session = CacheControl(
|
|
sess=session,
|
|
cache=SeparateBodyFileCache(directory=cache_dir),
|
|
cacheable_methods=("GET", "HEAD"),
|
|
)
|
|
|
|
def build_url(
|
|
self, base_url: str, path: str, args_dict: Optional[dict] = None
|
|
) -> str:
|
|
"""Build URL using base URL, cumulating existing and passed path, then adding
|
|
URL arguments.
|
|
|
|
Args:
|
|
base_url (str): base URL with existing path to use
|
|
path (str): URL path to cumulate with existing
|
|
args_dict (dict | None, optional): URL arguments to add. Defaults to None.
|
|
|
|
Returns:
|
|
str: complete and valid URL
|
|
"""
|
|
if not base_url:
|
|
logger.error(
|
|
"Base url not set, probably because 'site_url' is not set "
|
|
"in Mkdocs configuration file. Using an empty string instead."
|
|
)
|
|
base_url = ""
|
|
|
|
# Returns a list in the structure of urlparse.ParseResult
|
|
url_parts = list(urlparse(base_url))
|
|
url_parts[2] += path
|
|
if args_dict:
|
|
url_parts[4] = urlencode(args_dict)
|
|
return urlunparse(url_parts)
|
|
|
|
def get_value_from_dot_key(self, data: dict, dot_key: str | bool) -> Any:
|
|
"""Retrieves a value from a dictionary using a dot notation key.
|
|
|
|
Args:
|
|
data (dict): the dictionary from which to retrieve the value.
|
|
dot_key (str | bool): The key in dot notation to specify the path in the
|
|
dictionary.
|
|
|
|
Returns:
|
|
Any: The value retrieved from the dictionary, or None if the key
|
|
does not exist.
|
|
"""
|
|
if not isinstance(dot_key, str):
|
|
return data.get(dot_key)
|
|
for key in dot_key.split("."):
|
|
if isinstance(data, dict) and key in data:
|
|
data = data[key]
|
|
else:
|
|
return None
|
|
return data
|
|
|
|
def get_file_dates(
|
|
self,
|
|
in_page: Page,
|
|
source_date_creation: str,
|
|
source_date_update: str,
|
|
meta_datetime_format: str,
|
|
meta_default_time: datetime,
|
|
meta_default_timezone: str,
|
|
) -> tuple[datetime, datetime]:
|
|
"""Extract creation and update dates from page metadata (yaml frontmatter) or
|
|
git log for given file.
|
|
|
|
Args:
|
|
in_page (Page): input page
|
|
source_date_creation (str): which source to use (git or meta tag) for
|
|
creation date
|
|
source_date_update (str): which source to use (git or meta tag) for update
|
|
date
|
|
meta_datetime_format (str): datetime string format
|
|
meta_default_time (datetime): fallback time to set if not specified
|
|
meta_default_timezone (str): timezone to use
|
|
|
|
Returns:
|
|
tuple[datetime, datetime]: tuple of timestamps (creation date, last commit date)
|
|
"""
|
|
logger.debug(f"Extracting dates for {in_page.file.src_uri}")
|
|
# empty vars
|
|
dt_created = dt_updated = None
|
|
if meta_default_time is None:
|
|
meta_default_time = self.meta_default_time = datetime.min
|
|
|
|
# if enabled, try to retrieve dates from page metadata
|
|
if not self.use_git or (
|
|
source_date_creation != "git"
|
|
and self.get_value_from_dot_key(in_page.meta, source_date_creation)
|
|
):
|
|
dt_created = self.get_date_from_meta(
|
|
date_metatag_value=self.get_value_from_dot_key(
|
|
in_page.meta, source_date_creation
|
|
),
|
|
meta_datetime_format=meta_datetime_format,
|
|
meta_datetime_timezone=meta_default_timezone,
|
|
meta_default_time=meta_default_time,
|
|
)
|
|
if isinstance(dt_created, str):
|
|
logger.info(
|
|
f"Creation date of {in_page.file.abs_src_path} is an "
|
|
f"a character string: {dt_created} ({type(dt_created)})"
|
|
)
|
|
|
|
elif dt_created is None:
|
|
logger.info(
|
|
f"Creation date of {in_page.file.abs_src_path} has not "
|
|
"been recognized."
|
|
)
|
|
|
|
if not self.use_git or (
|
|
source_date_update != "git"
|
|
and self.get_value_from_dot_key(in_page.meta, source_date_update)
|
|
):
|
|
dt_updated = self.get_date_from_meta(
|
|
date_metatag_value=self.get_value_from_dot_key(
|
|
in_page.meta, source_date_update
|
|
),
|
|
meta_datetime_format=meta_datetime_format,
|
|
meta_datetime_timezone=meta_default_timezone,
|
|
meta_default_time=meta_default_time,
|
|
)
|
|
|
|
if isinstance(dt_updated, str):
|
|
logger.debug(
|
|
f"Update date of {in_page.file.abs_src_path} is a "
|
|
f"character string: {dt_updated} ({type(dt_updated)})"
|
|
)
|
|
|
|
elif dt_updated is None:
|
|
logger.debug(
|
|
f"Update date of {in_page.file.abs_src_path} is an "
|
|
f"unrecognized type: {dt_updated} ({type(dt_updated)})"
|
|
)
|
|
|
|
# explore git log
|
|
if self.git_is_valid:
|
|
try:
|
|
# only if dates have not been retrieved from page meta
|
|
if not dt_created:
|
|
dt_created = self.repo.log(
|
|
in_page.file.abs_src_path,
|
|
n=1,
|
|
date="short",
|
|
format="%at",
|
|
diff_filter="AR",
|
|
)
|
|
if not dt_updated:
|
|
dt_updated = self.repo.log(
|
|
in_page.file.abs_src_path,
|
|
n=1,
|
|
date="short",
|
|
format="%at",
|
|
)
|
|
except GitCommandError as err:
|
|
logger.info(
|
|
f"Unable to read git logs of '{in_page.file.abs_src_path}'. "
|
|
"Is git log readable? Falling back to build date. "
|
|
"To disable this warning, set 'use_git: false' in plugin options. "
|
|
f"Trace: {err}"
|
|
)
|
|
except GitCommandNotFound as err:
|
|
logger.warning(
|
|
"Unable to perform command 'git log'. Is git installed? "
|
|
"Falling back to build date. "
|
|
"To disable this warning, set 'use_git: false' in plugin options. "
|
|
f"Trace: {err}"
|
|
)
|
|
self.git_is_valid = False
|
|
# convert timestamps into datetimes
|
|
if isinstance(dt_created, (str, float, int)) and dt_created:
|
|
dt_created = set_datetime_zoneinfo(
|
|
datetime.fromtimestamp(float(dt_created)), meta_default_timezone
|
|
)
|
|
if isinstance(dt_updated, (str, float, int)) and dt_updated:
|
|
dt_updated = set_datetime_zoneinfo(
|
|
datetime.fromtimestamp(float(dt_updated)), meta_default_timezone
|
|
)
|
|
|
|
# results
|
|
if all([dt_created, dt_updated]):
|
|
return (
|
|
dt_created,
|
|
dt_updated,
|
|
)
|
|
elif dt_created:
|
|
log_msg = (
|
|
"Updated date could not be retrieved for page: "
|
|
f"{in_page.file.abs_src_path}. Fallback to build date."
|
|
)
|
|
if self.use_git:
|
|
log_msg += "Maybe it has never been committed yet?"
|
|
logger.debug(log_msg)
|
|
return (
|
|
dt_created,
|
|
get_build_datetime(),
|
|
)
|
|
elif dt_updated:
|
|
log_msg = (
|
|
"Creation date could not be retrieved for page: "
|
|
f"{in_page.file.abs_src_path}. Fallback to build date."
|
|
)
|
|
if self.use_git:
|
|
log_msg += "Maybe it has never been committed yet?"
|
|
logger.debug(log_msg)
|
|
return (
|
|
get_build_datetime(),
|
|
dt_updated,
|
|
)
|
|
else:
|
|
logger.info(
|
|
f"Dates could not be retrieved for page: {in_page.file.abs_src_path}."
|
|
)
|
|
return (
|
|
get_build_datetime(),
|
|
get_build_datetime(),
|
|
)
|
|
|
|
def get_authors_from_meta(self, in_page: Page) -> Optional[tuple[str]]:
|
|
"""Returns authors from page meta. It handles 'author' and 'authors' for keys, \
|
|
str and iterable as values types.
|
|
|
|
Args:
|
|
in_page (Page): input page to look into
|
|
|
|
Returns:
|
|
tuple[str] | None: tuple of authors names
|
|
"""
|
|
# identify the key
|
|
if "author" in in_page.meta:
|
|
if isinstance(in_page.meta.get("author"), str):
|
|
return (in_page.meta.get("author"),)
|
|
elif isinstance(in_page.meta.get("author"), (list, tuple)):
|
|
return tuple(in_page.meta.get("author"))
|
|
else:
|
|
logger.warning(
|
|
"Type of author value in page.meta "
|
|
f"({in_page.file.abs_src_path}) is not valid. "
|
|
"It should be str, list or tuple, "
|
|
f"not: {type(in_page.meta.get('author'))}."
|
|
)
|
|
return None
|
|
elif "authors" in in_page.meta:
|
|
if isinstance(in_page.meta.get("authors"), str):
|
|
return (in_page.meta.get("authors"),)
|
|
elif isinstance(in_page.meta.get("authors"), (list, tuple)):
|
|
if (
|
|
self.material_blog.IS_ENABLED
|
|
and self.material_blog.is_page_a_blog_post(in_page)
|
|
):
|
|
return [
|
|
self.material_blog.author_name_from_id(author_id)
|
|
for author_id in in_page.meta.get("authors")
|
|
]
|
|
else:
|
|
return tuple(in_page.meta.get("authors"))
|
|
else:
|
|
logger.warning(
|
|
"Type of authors value in page.meta (%s) is not valid. "
|
|
"It should be str, list or tuple, not: %s."
|
|
% in_page.file.abs_src_path,
|
|
type(in_page.meta.get("authors")),
|
|
)
|
|
return None
|
|
|
|
def get_categories_from_meta(
|
|
self, in_page: Page, categories_labels: Iterable
|
|
) -> Optional[list]:
|
|
"""Returns category from page meta.
|
|
|
|
Args:
|
|
in_page (Page): input page to parse
|
|
categories_labels (Iterable): meta tags to look into
|
|
|
|
Returns:
|
|
list | None: found categories
|
|
"""
|
|
if not categories_labels:
|
|
return None
|
|
|
|
output_categories = []
|
|
for category_label in categories_labels:
|
|
if category_label in in_page.meta:
|
|
if isinstance(in_page.meta.get(category_label), (list, tuple)):
|
|
output_categories.extend(in_page.meta.get(category_label))
|
|
elif isinstance(in_page.meta.get(category_label), str):
|
|
output_categories.append(in_page.meta.get(category_label))
|
|
else:
|
|
continue
|
|
return sorted(output_categories)
|
|
|
|
def get_date_from_meta(
|
|
self,
|
|
date_metatag_value: str,
|
|
meta_datetime_format: str,
|
|
meta_datetime_timezone: str,
|
|
meta_default_time: datetime,
|
|
) -> datetime:
|
|
"""Get date from page.meta handling str with associated datetime format and
|
|
date already transformed by MkDocs.
|
|
|
|
Args:
|
|
date_metatag_value (str): value of page.meta.{tag_for_date}
|
|
meta_datetime_format (str): expected format of datetime
|
|
meta_datetime_timezone (str): timezone to use
|
|
meta_default_time (datetime): time to set if not specified
|
|
|
|
Returns:
|
|
datetime: page datetime value
|
|
"""
|
|
out_date = None
|
|
try:
|
|
if isinstance(date_metatag_value, str):
|
|
out_date = datetime.strptime(date_metatag_value, meta_datetime_format)
|
|
# datetime being a subclass of date, the following elif order matters
|
|
# see: https://stackoverflow.com/a/68743663/2556577
|
|
elif isinstance(date_metatag_value, datetime):
|
|
# if datetime, use it directly
|
|
out_date = date_metatag_value
|
|
elif isinstance(date_metatag_value, date):
|
|
out_date = datetime.combine(
|
|
date=date_metatag_value, time=meta_default_time.time()
|
|
)
|
|
else:
|
|
logger.debug(
|
|
f"Incompatible date type: {type(date_metatag_value)}. It must be: "
|
|
"date, datetime or str (complying with defined strftime format)."
|
|
)
|
|
return out_date
|
|
except ValueError as err:
|
|
logger.error(
|
|
f"Incompatible date found: {date_metatag_value=} "
|
|
f"{type(date_metatag_value)}. Trace: {err}"
|
|
)
|
|
return out_date
|
|
except Exception as err:
|
|
logger.error(
|
|
f"Unable to retrieve creation date: {date_metatag_value=} "
|
|
f"{type(date_metatag_value)}. Trace: {err}"
|
|
)
|
|
return out_date
|
|
|
|
if not out_date.tzinfo:
|
|
out_date = set_datetime_zoneinfo(out_date, meta_datetime_timezone)
|
|
|
|
return out_date
|
|
|
|
def get_description_or_abstract(
|
|
self,
|
|
in_page: Page,
|
|
chars_count: int = 160,
|
|
abstract_delimiter: Optional[str] = None,
|
|
) -> str:
|
|
"""Returns description from page meta. If it doesn't exist, use the page
|
|
content up to {abstract_delimiter} or the {chars_count} first characters
|
|
from page content (in markdown).
|
|
|
|
Args:
|
|
in_page (Page): page to look at
|
|
chars_count (int, optional): if page.meta.description is not set, number of
|
|
chars of the content to use. Defaults to 160.
|
|
abstract_delimiter (str, optional): description delimiter (also called
|
|
excerpt). Defaults to None.
|
|
|
|
Returns:
|
|
str: page description to use
|
|
"""
|
|
if in_page.meta.get("rss", {}).get("feed_description"):
|
|
description = in_page.meta["rss"]["feed_description"]
|
|
else:
|
|
description = in_page.meta.get("description")
|
|
|
|
# If the full page is wanted (unlimited chars count)
|
|
if chars_count == -1 and (in_page.content or in_page.markdown):
|
|
if in_page.content:
|
|
return in_page.content
|
|
else:
|
|
return markdown.markdown(in_page.markdown, output_format="html5")
|
|
# If the description is explicitly given
|
|
elif description:
|
|
return description
|
|
# If the abstract is cut by the delimiter
|
|
elif (
|
|
abstract_delimiter
|
|
and (
|
|
excerpt_separator_position := in_page.markdown.find(abstract_delimiter)
|
|
)
|
|
> -1
|
|
):
|
|
return markdown.markdown(
|
|
in_page.markdown[:excerpt_separator_position],
|
|
output_format="html5",
|
|
)
|
|
# Use first chars_count from the markdown
|
|
elif chars_count > 0 and in_page.markdown:
|
|
if len(in_page.markdown) <= chars_count:
|
|
return markdown.markdown(in_page.markdown, output_format="html5")
|
|
else:
|
|
return markdown.markdown(
|
|
f"{in_page.markdown[: chars_count - 3]}...",
|
|
output_format="html5",
|
|
)
|
|
# No explicit description and no (or empty) abstract found
|
|
else:
|
|
logger.warning(
|
|
f"No description generated from metadata or content of the page {in_page.file.src_uri}, "
|
|
"therefore the feed won't be compliant, "
|
|
"because an item must have a description."
|
|
)
|
|
return ""
|
|
|
|
def load_images_for_pages(
|
|
self,
|
|
pages: list[PageInformation],
|
|
base_url: str,
|
|
processed_refs: Optional[set] = None,
|
|
) -> None:
|
|
"""Load images for a list of pages (mutation in-place).
|
|
|
|
Args:
|
|
pages: list of PageInformation
|
|
base_url: final website base URL
|
|
processed_refs: deduplication set
|
|
"""
|
|
if processed_refs is None:
|
|
processed_refs = set()
|
|
|
|
for page_info in pages:
|
|
if (
|
|
page_info._mkdocs_page_ref
|
|
and id(page_info._mkdocs_page_ref) not in processed_refs
|
|
):
|
|
logger.debug(
|
|
f"Get image for '{page_info.title}' ({page_info.abs_path})"
|
|
)
|
|
page_info.image = self.get_image(
|
|
in_page=page_info._mkdocs_page_ref, base_url=base_url
|
|
)
|
|
processed_refs.add(id(page_info._mkdocs_page_ref))
|
|
|
|
def get_image(
|
|
self, in_page: MkdocsPageSubset, base_url: str
|
|
) -> Optional[tuple[str, str, int]]:
|
|
"""Get page's image from page meta or social cards and returns properties.
|
|
|
|
Args:
|
|
in_page: page to parse
|
|
base_url: website URL to resolve absolute URLs for images referenced
|
|
with local path.
|
|
|
|
Returns:
|
|
(image url, mime type, image length) or None if there is no image set
|
|
"""
|
|
if in_page.meta.get("image"):
|
|
img_url = in_page.meta.get("image").strip()
|
|
logger.debug(
|
|
f"Image found ({img_url}) in page.meta.image for page: "
|
|
f"{in_page.src_uri}"
|
|
)
|
|
elif in_page.meta.get("illustration"):
|
|
img_url = in_page.meta.get("illustration").strip()
|
|
logger.debug(
|
|
f"Image found ({img_url}) in page.meta.illustration for page: "
|
|
f"{in_page.src_uri}"
|
|
)
|
|
elif (
|
|
isinstance(self.social_cards, IntegrationMaterialSocialCards)
|
|
and self.social_cards.IS_ENABLED
|
|
and self.social_cards.IS_SOCIAL_PLUGIN_CARDS_ENABLED
|
|
and self.social_cards.is_social_plugin_enabled_page(
|
|
mkdocs_page=in_page,
|
|
fallback_value=self.social_cards.IS_SOCIAL_PLUGIN_CARDS_ENABLED,
|
|
)
|
|
):
|
|
img_url = self.social_cards.get_social_card_url_for_page(
|
|
mkdocs_page=in_page
|
|
)
|
|
if img_local_cache_path := self.social_cards.get_social_card_cache_path_for_page(
|
|
mkdocs_page=in_page
|
|
):
|
|
img_length = img_local_cache_path.stat().st_size
|
|
img_type = guess_type(url=img_local_cache_path, strict=False)[0]
|
|
elif img_local_build_path := self.social_cards.get_social_card_build_path_for_page(
|
|
mkdocs_page=in_page
|
|
):
|
|
img_length = img_local_build_path.stat().st_size
|
|
img_type = guess_type(url=img_local_build_path, strict=False)[0]
|
|
else:
|
|
logger.debug(
|
|
"Social card still not exists locally. Trying to "
|
|
f"retrieve length from remote image: {img_url}. "
|
|
"Note that would work only if the social card image has been "
|
|
"already published before the build."
|
|
)
|
|
img_length = self.get_remote_image_length(image_url=img_url)
|
|
img_type = guess_type(url=img_url, strict=False)[0]
|
|
|
|
return (
|
|
img_url,
|
|
img_type,
|
|
img_length,
|
|
)
|
|
|
|
else:
|
|
return None
|
|
|
|
# guess mimetype
|
|
mime_type = guess_type(url=img_url, strict=False)[0]
|
|
|
|
# if path, resolve absolute url
|
|
if not img_url.startswith("http"):
|
|
img_length = self.get_local_image_length(
|
|
page_path=in_page.abs_src_path, path_to_append=img_url
|
|
)
|
|
img_url = self.build_url(base_url=base_url, path=img_url)
|
|
else:
|
|
img_length = self.get_remote_image_length(image_url=img_url)
|
|
|
|
# return final tuple
|
|
return (img_url, mime_type, img_length)
|
|
|
|
def get_local_image_length(
|
|
self, page_path: str, path_to_append: str
|
|
) -> Optional[int]:
|
|
"""Calculates local image size in octets.
|
|
|
|
Args:
|
|
page_path (str): source path to the Mkdocs page
|
|
path_to_append (str): path to append
|
|
|
|
Returns:
|
|
int: size in octets
|
|
"""
|
|
image_path = Path(page_path).parent / Path(path_to_append)
|
|
if not image_path.is_file():
|
|
logger.debug(f"{image_path} not found")
|
|
return None
|
|
|
|
return image_path.stat().st_size
|
|
|
|
@lru_cache(maxsize=512)
|
|
def get_remote_image_length(
|
|
self,
|
|
image_url: str,
|
|
http_method: str = "HEAD",
|
|
attempt: int = 0,
|
|
req_timeout: tuple[float, float] = (5, 30),
|
|
ssl_verify: bool = True,
|
|
) -> Optional[int]:
|
|
"""Retrieve length for remote images (starting with 'http').
|
|
|
|
Firstly, it tries to perform a HEAD request and get the length from the headers. \
|
|
If it fails, it tries again with a GET and disabling SSL verification.
|
|
|
|
Args:
|
|
image_url (str): image URL
|
|
http_method (str, optional): HTTP method to use for the request.
|
|
Defaults to "HEAD".
|
|
attempt (int, optional): request tries counter. Defaults to 0.
|
|
req_timeout (tuple[float, float], optional): (connect, read) timeout in \
|
|
secondes. Defaults to (5, 30).
|
|
ssl_verify (bool, optional): option to perform SSL verification or not.
|
|
Defaults to True.
|
|
|
|
Returns:
|
|
int | None: image length as int or None
|
|
"""
|
|
if self.mkdocs_command_is_on_serve:
|
|
return None
|
|
|
|
# first, try HEAD request to avoid downloading the image
|
|
try:
|
|
attempt += 1
|
|
logger.debug(
|
|
f"Get remote image length (attempt {attempt}/2) - "
|
|
f"Sending {http_method} request to {image_url}"
|
|
)
|
|
req_response = self.req_session.request(
|
|
method=http_method,
|
|
timeout=req_timeout,
|
|
url=image_url,
|
|
verify=ssl_verify,
|
|
)
|
|
req_response.raise_for_status()
|
|
img_length = req_response.headers.get("content-length")
|
|
except (ConnectionError, HTTPError) as err:
|
|
logger.debug(
|
|
f"Remote image could not been reached: {image_url}. "
|
|
f"Trying again with {http_method} and disabling SSL verification. "
|
|
f"Attempt: {attempt}/2. Trace: {err}"
|
|
)
|
|
if attempt < 2:
|
|
return self.get_remote_image_length(
|
|
image_url, http_method="GET", attempt=attempt, ssl_verify=False
|
|
)
|
|
else:
|
|
logger.info(
|
|
f"Remote image is not reachable: {image_url} after "
|
|
f"{attempt} attempts. Trace: {err}"
|
|
)
|
|
return None
|
|
|
|
return int(img_length) if img_length else None
|
|
|
|
@staticmethod
|
|
def get_site_url(mkdocs_config: MkDocsConfig) -> Optional[str]:
|
|
"""Extract site URL from MkDocs configuration and enforce the behavior to ensure
|
|
returning a str with length > 0 or None. If exists, it adds an ending slash.
|
|
|
|
Args:
|
|
mkdocs_config (MkDocsConfig): configuration object
|
|
|
|
Returns:
|
|
str | None: site url
|
|
"""
|
|
# this method exists because the following line returns an empty string instead
|
|
# of None (because the key always exists)
|
|
defined_site_url = mkdocs_config.site_url
|
|
|
|
# cases
|
|
if defined_site_url is None or not len(defined_site_url):
|
|
# in case of mkdocs's behavior change
|
|
site_url = None
|
|
else:
|
|
site_url = defined_site_url
|
|
# handle trailing slash
|
|
if not site_url.endswith("/"):
|
|
site_url = site_url + "/"
|
|
|
|
return site_url
|
|
|
|
def guess_locale(self, mkdocs_config: MkDocsConfig) -> Optional[str]:
|
|
"""Extract language code from MkDocs or Theme configuration.
|
|
|
|
Args:
|
|
mkdocs_config (MkDocsConfig): configuration object
|
|
|
|
Returns:
|
|
str | None: language code
|
|
"""
|
|
# MkDocs locale settings - might be added in future mkdocs versions
|
|
# see: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/issues/24
|
|
if mkdocs_config.get("locale"):
|
|
logger.warning(
|
|
DeprecationWarning(
|
|
"Mkdocs does not support locale option at the "
|
|
"configuration root but under theme sub-configuration. It won't be "
|
|
"supported anymore by the plugin in the next version."
|
|
)
|
|
)
|
|
return mkdocs_config.get("locale")
|
|
|
|
# Some themes implement a locale or a language settings
|
|
if "theme" in mkdocs_config:
|
|
if (
|
|
self.social_cards.IS_THEME_MATERIAL
|
|
and "language" in mkdocs_config.theme
|
|
):
|
|
# TODO: remove custom behavior when Material theme switches to locale
|
|
# see: https://github.com/squidfunk/mkdocs-material/discussions/6453
|
|
logger.debug(
|
|
"Language detected in Material theme "
|
|
f"('{mkdocs_config.theme.name}') settings: "
|
|
f"{mkdocs_config.theme.get('language')}"
|
|
)
|
|
return mkdocs_config.theme.get("language")
|
|
|
|
elif "locale" in mkdocs_config.theme:
|
|
locale = mkdocs_config.theme.locale
|
|
logger.debug(
|
|
"Locale detected in theme "
|
|
f"('{mkdocs_config.theme.name}') settings: {locale=}"
|
|
)
|
|
return (
|
|
f"{locale.language}-{locale.territory}"
|
|
if locale.territory
|
|
else f"{locale.language}"
|
|
)
|
|
else:
|
|
logger.debug(
|
|
"Nor locale or language detected in theme settings "
|
|
f"('{mkdocs_config.theme.name}')."
|
|
)
|
|
|
|
return None
|
|
|
|
@staticmethod
|
|
def filter_pages(
|
|
pages: list[PageInformation],
|
|
filter_attribute: Literal["created", "updated"],
|
|
length: int,
|
|
) -> list[PageInformation]:
|
|
"""Filter pages based on an attribute and a max number of items.
|
|
|
|
Args:
|
|
pages: pages to filter
|
|
filter_attribute: page attribute to use as filter variable
|
|
length: max number of pages to return
|
|
|
|
Returns:
|
|
list of filtered pages
|
|
"""
|
|
return sorted(
|
|
pages, key=lambda page: getattr(page, filter_attribute), reverse=True
|
|
)[:length]
|
|
|
|
@staticmethod
|
|
def feed_to_json(feed: RssFeedBase) -> dict:
|
|
"""Format internal feed representation as a JSON Feed compliant dict.
|
|
|
|
Args:
|
|
feed (dict): internal feed structure, i. e. GitRssPlugin.feed_created or
|
|
feed_updated value
|
|
|
|
Returns:
|
|
dict: dict that can be passed to json.dump
|
|
"""
|
|
return {
|
|
"version": "https://jsonfeed.org/version/1.1",
|
|
"title": feed.title,
|
|
"home_page_url": feed.html_url,
|
|
"feed_url": feed.json_url,
|
|
"description": feed.description,
|
|
"icon": feed.logo_url,
|
|
"authors": ([{"name": feed.author}] if feed.author is not None else []),
|
|
"language": str(feed.language),
|
|
"items": [
|
|
{
|
|
"id": item.guid,
|
|
"url": item.link,
|
|
"title": item.title,
|
|
"content_html": item.description,
|
|
"image": (item.image or (None,))[0],
|
|
"date_modified": item.updated.isoformat("T"),
|
|
"date_published": item.created.isoformat("T"),
|
|
"authors": [{"name": name} for name in (item.authors or ())],
|
|
"tags": item.categories,
|
|
}
|
|
for item in feed.entries
|
|
],
|
|
}
|