mkdocs-ultralytics-plugin 0.2.3__tar.gz → 0.2.4__tar.gz

{mkdocs_ultralytics_plugin-0.2.3 → mkdocs_ultralytics_plugin-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-ultralytics-plugin
-Version: 0.2.3
+Version: 0.2.4
 Summary: An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.
 Author-email: Glenn Jocher <hello@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>

{mkdocs_ultralytics_plugin-0.2.3 → mkdocs_ultralytics_plugin-0.2.4}/mkdocs_ultralytics_plugin.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-ultralytics-plugin
-Version: 0.2.3
+Version: 0.2.4
 Summary: An MkDocs plugin that provides Ultralytics Docs customizations at https://docs.ultralytics.com.
 Author-email: Glenn Jocher <hello@ultralytics.com>
 Maintainer-email: Ultralytics <hello@ultralytics.com>

{mkdocs_ultralytics_plugin-0.2.3 → mkdocs_ultralytics_plugin-0.2.4}/plugin/__init__.py

@@ -1,6 +1,6 @@
 # Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 
 from .main import MetaPlugin
 from .postprocess import postprocess_site

{mkdocs_ultralytics_plugin-0.2.3 → mkdocs_ultralytics_plugin-0.2.4}/plugin/postprocess.py

@@ -16,6 +16,7 @@ except ImportError:
 
 import plugin.processor as processor
 from plugin.processor import process_html
+from plugin.utils import resolve_all_authors
 
 # Shared worker state for process pools (avoids re-pickling large read-only data per task)
 _WORKER_STATE: dict[str, Any] | None = None
@@ -37,7 +38,6 @@ def _process_file(html_file: Path) -> bool:
         _WORKER_STATE["repo_url"],
         site_url=_WORKER_STATE["site_url"],
         default_image=_WORKER_STATE["default_image"],
-        default_author=_WORKER_STATE["default_author"],
         add_desc=_WORKER_STATE["add_desc"],
         add_image=_WORKER_STATE["add_image"],
         add_keywords=_WORKER_STATE["add_keywords"],
@@ -59,7 +59,6 @@ def process_html_file(
     repo_url: str | None,
     site_url: str = "",
     default_image: str | None = None,
-    default_author: str | None = None,
     add_desc: bool = True,
     add_image: bool = True,
     add_keywords: bool = True,
@@ -114,7 +113,6 @@ def process_html_file(
         git_data=git_data,
         repo_url=repo_url,
         default_image=default_image,
-        default_author=default_author,
         keywords=keywords,
         add_desc=add_desc,
         add_image=add_image,
@@ -184,6 +182,9 @@ def postprocess_site(
     git_data = None
     if (add_authors or add_json_ld) and md_index:
         repo_url, git_data = processor.build_git_map(list(md_index.values()))
+        # Resolve all authors ONCE in main process before spawning workers
+        # This prevents race conditions when workers try to write to the cache file
+        git_data = resolve_all_authors(git_data, default_author=default_author, repo_url=repo_url, verbose=verbose)
 
     progress = TQDM(total=len(html_files), desc="Postprocessing", unit="file", disable=not verbose) if TQDM else None
     # Enable logging only for the synchronous path; pools run without per-task log_fn to remain pickle-safe.
@@ -196,7 +197,6 @@ def postprocess_site(
         repo_url=repo_url,
         site_url=site_url,
         default_image=default_image,
-        default_author=default_author,
         add_desc=add_desc,
         add_image=add_image,
         add_keywords=add_keywords,

{mkdocs_ultralytics_plugin-0.2.3 → mkdocs_ultralytics_plugin-0.2.4}/plugin/processor.py

@@ -13,11 +13,7 @@ from urllib.parse import quote
 
 from bs4 import BeautifulSoup
 
-from plugin.utils import (
-    calculate_time_difference,
-    get_github_usernames_from_file,
-    get_youtube_video_ids,
-)
+from plugin.utils import calculate_time_difference, get_youtube_video_ids
 
 today = datetime.now()
 DEFAULT_CREATION_DATE = (today - timedelta(days=365)).strftime("%Y-%m-%d %H:%M:%S +0000")
@@ -30,11 +26,9 @@ CHECK_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path
 def get_git_info(
     file_path: str,
     add_authors: bool = True,
-    default_author: str | None = None,
     git_data: dict[str, dict[str, Any]] | None = None,
-    repo_url: str | None = None,
 ) -> dict[str, Any]:
-    """Retrieve git information (dates + optional authors) from precomputed git data."""
+    """Retrieve git information (dates + pre-resolved authors) from precomputed git data."""
     file_path = str(Path(file_path).resolve())
     git_info = {
         "creation_date": DEFAULT_CREATION_DATE,
@@ -45,29 +39,12 @@ def get_git_info(
         return git_info
 
     cached = git_data[file_path]
-    git_info.update(
-        {
-            "creation_date": cached.get("creation_date", DEFAULT_CREATION_DATE),
-            "last_modified_date": cached.get("last_modified_date", DEFAULT_MODIFIED_DATE),
-        }
-    )
-
-    if add_authors and cached.get("emails"):
-        git_info["authors"] = sorted(
-            [
-                (
-                    author,
-                    info["url"],
-                    info["changes"],
-                    info["avatar"],
-                )
-                for author, info in get_github_usernames_from_file(
-                    file_path, default_user=default_author, emails=cached["emails"], repo_url=repo_url
-                ).items()
-            ],
-            key=lambda x: x[2],
-            reverse=True,
-        )
+    git_info["creation_date"] = cached.get("creation_date", DEFAULT_CREATION_DATE)
+    git_info["last_modified_date"] = cached.get("last_modified_date", DEFAULT_MODIFIED_DATE)
+
+    # Authors are pre-resolved by resolve_all_authors() in the main process
+    if add_authors and "authors" in cached:
+        git_info["authors"] = cached["authors"]
 
     return git_info
 
@@ -309,7 +286,6 @@ def process_html(
     git_data: dict[str, dict[str, Any]] | None = None,
     repo_url: str | None = None,
     default_image: str | None = None,
-    default_author: str | None = None,
     keywords: str | None = None,
     add_desc: bool = True,
     add_image: bool = True,
@@ -493,9 +469,7 @@ def process_html(
     needs_git = (add_authors or add_json_ld) and src_path
 
     if needs_git:
-        git_info = get_git_info(
-            src_path, add_authors=add_authors, default_author=default_author, git_data=git_data, repo_url=repo_url
-        )
+        git_info = get_git_info(src_path, add_authors=add_authors, git_data=git_data)
 
         # Only render git footer if we have real git history (not placeholder defaults)
         has_real_git_data = (

mkdocs_ultralytics_plugin-0.2.4/plugin/utils.py

@@ -0,0 +1,223 @@
+# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import requests
+import yaml
+
+WARNING = "WARNING (mkdocs_ultralytics_plugin):"
+TIMEOUT = 10  # seconds for network requests
+DEFAULT_AVATAR_URL = "https://github.com/github.png"
+_default_avatar_cache: str | None = None
+
+
+def get_default_avatar() -> str:
+    """Get the default avatar URL, lazily fetching the resolved URL on first call."""
+    global _default_avatar_cache
+    if _default_avatar_cache is None:
+        try:
+            _default_avatar_cache = requests.head(DEFAULT_AVATAR_URL, allow_redirects=True, timeout=TIMEOUT).url
+        except Exception:
+            _default_avatar_cache = DEFAULT_AVATAR_URL  # fallback to original URL
+    return _default_avatar_cache
+
+
+def calculate_time_difference(date_string: str) -> tuple[str, str]:
+    """Calculate the time difference between a given date and the current date in a human-readable format.
+
+    Args:
+        date_string (str): Date and time string in the format "%Y-%m-%d %H:%M:%S %z".
+
+    Returns:
+        difference (str): Time difference in days, months, or years (e.g., "5 days", "2 months", "1 year").
+        pretty_date (str): Given date formatted as "Month Day, Year" (e.g., "January 01, 2023").
+
+    Examples:
+        >>> calculate_time_difference("2023-01-01 00:00:00 +0000")
+        ("5 months", "January 01, 2023")
+    """
+    date = datetime.strptime(date_string, "%Y-%m-%d %H:%M:%S %z")
+    pretty_date = date.strftime("%B %d, %Y")
+    now = datetime.now(date.tzinfo)
+    diff = now - date
+    days = diff.days
+
+    if days < 30:
+        difference = f"{days} day{'s' if days != 1 else ''}"
+    elif days < 365:
+        months = days // 30
+        difference = f"{months} month{'s' if months != 1 else ''}"
+    else:
+        years = days // 365
+        difference = f"{years} year{'s' if years != 1 else ''}"
+    return difference, pretty_date
+
+
+def get_youtube_video_ids(soup) -> list[str]:
+    """Extract YouTube video IDs from iframe elements present in the provided BeautifulSoup object.
+
+    Args:
+        soup (BeautifulSoup): A BeautifulSoup object containing the HTML content.
+
+    Returns:
+        (List[str]): A list containing YouTube video IDs extracted from the HTML content.
+    """
+    youtube_ids = []
+    iframes = soup.find_all("iframe", src=True)
+    for iframe in iframes:
+        if match := re.search(r"youtube\.com/embed/([a-zA-Z0-9_-]+)", iframe["src"]):
+            youtube_ids.append(match[1])
+    return youtube_ids
+
+
+def _get_cache_file() -> Path:
+    """Get the path to the GitHub author cache file."""
+    return Path("docs" if Path("docs").is_dir() else "") / "mkdocs_github_authors.yaml"
+
+
+def load_author_cache() -> dict[str, dict[str, str | None]]:
+    """Load the GitHub author cache from disk."""
+    cache_file = _get_cache_file()
+    try:
+        return yaml.safe_load(cache_file.read_text()) or {} if cache_file.is_file() else {}
+    except Exception:
+        return {}
+
+
+def save_author_cache(cache: dict[str, dict[str, str | None]]) -> None:
+    """Save the GitHub author cache to disk."""
+    try:
+        _get_cache_file().write_text(yaml.safe_dump(cache))
+    except Exception as e:
+        print(f"{WARNING} Failed to save author cache: {e}")
+
+
+def resolve_github_user(
+    email: str, cache: dict[str, dict[str, str | None]], verbose: bool = True
+) -> dict[str, str | None]:
+    """Resolve a single email to GitHub username and avatar, updating cache in-place.
+
+    Args:
+        email (str): The email address to resolve.
+        cache (dict): The author cache dict (modified in-place if new entry added).
+        verbose (bool): Whether to print API call info.
+
+    Returns:
+        dict with 'username' and 'avatar' keys (values may be None if not found).
+    """
+    if not email or not email.strip():
+        return {"username": None, "avatar": None}
+
+    # Return cached result if available
+    if email in cache:
+        return cache[email]
+
+    # Parse username directly from GitHub noreply emails
+    if email.endswith("@users.noreply.github.com"):
+        username = email.split("+")[-1].split("@")[0]
+        try:
+            avatar = requests.head(f"https://github.com/{username}.png", allow_redirects=True, timeout=TIMEOUT).url
+        except Exception:
+            avatar = None
+        cache[email] = {"username": username, "avatar": avatar}
+        return cache[email]
+
+    # Query GitHub REST API
+    if verbose:
+        print(f"Running GitHub REST API for author {email}")
+    try:
+        response = requests.get(
+            f"https://api.github.com/search/users?q={email}+in:email&sort=joined&order=asc", timeout=TIMEOUT
+        )
+        if response.status_code == 200:
+            data = response.json()
+            if data.get("total_count", 0) > 0:
+                username = data["items"][0]["login"]
+                avatar = requests.head(data["items"][0]["avatar_url"], allow_redirects=True, timeout=TIMEOUT).url
+                cache[email] = {"username": username, "avatar": avatar}
+                return cache[email]
+    except Exception:
+        pass
+
+    if verbose:
+        print(f"{WARNING} No username found for {email}")
+    cache[email] = {"username": None, "avatar": None}
+    return cache[email]
+
+
+def resolve_all_authors(
+    git_data: dict[str, dict[str, Any]],
+    default_author: str | None = None,
+    repo_url: str | None = None,
+    verbose: bool = True,
+) -> dict[str, dict[str, Any]]:
+    """Pre-resolve all unique emails from git_data to GitHub usernames.
+
+    This should be called ONCE in the main process before spawning workers. It collects all unique emails, resolves
+    them, saves the cache, and returns git_data with 'authors' pre-populated for each file.
+
+    Args:
+        git_data (dict): The git metadata dict from build_git_map().
+        default_author (str, optional): Default author email if no git info.
+        repo_url (str, optional): Repository URL for fallback links.
+        verbose (bool): Whether to print progress info.
+
+    Returns:
+        dict: Updated git_data with 'authors' list added to each entry.
+    """
+    if not git_data:
+        return git_data
+
+    # Collect all unique emails across all files
+    all_emails: set[str] = set()
+    for entry in git_data.values():
+        all_emails.update(entry.get("emails", {}).keys())
+    if default_author:
+        all_emails.add(default_author)
+    all_emails.discard("")
+
+    if not all_emails:
+        return git_data
+
+    # Load cache, resolve all emails, save cache (single disk write)
+    cache = load_author_cache()
+    cache_modified = False
+
+    for email in sorted(all_emails):
+        if email not in cache:
+            resolve_github_user(email, cache, verbose=verbose)
+            cache_modified = True
+
+    if cache_modified:
+        save_author_cache(cache)
+
+    # Build authors list for each file entry
+    github_repo_url = repo_url or "https://github.com/ultralytics/ultralytics"
+
+    for file_path, entry in git_data.items():
+        emails = entry.get("emails", {})
+        if not emails and default_author:
+            emails = {default_author: 1}
+
+        authors = []
+        for email, changes in emails.items():
+            email = email.strip() if email else ""
+            if not email:
+                email = default_author or ""
+            if not email:
+                continue
+            info = cache.get(email, {"username": None, "avatar": None})
+            username = info.get("username")
+            avatar = info.get("avatar") or get_default_avatar()
+            user_url = f"https://github.com/{username}" if username else github_repo_url
+            authors.append((username or email, user_url, changes, avatar))
+
+        # Sort by number of changes (descending)
+        entry["authors"] = sorted(authors, key=lambda x: x[2], reverse=True)
+
+    return git_data

mkdocs_ultralytics_plugin-0.2.3/plugin/utils.py

@@ -1,236 +0,0 @@
-# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license
-
-from __future__ import annotations
-
-import re
-import threading
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-
-import requests
-import yaml  # YAML is used for its readability and consistency with MkDocs ecosystem
-from bs4 import BeautifulSoup
-
-WARNING = "WARNING (mkdocs_ultralytics_plugin):"
-DEFAULT_AVATAR = requests.head("https://github.com/github.png", allow_redirects=True).url
-
-# Shared, thread-safe cache to avoid duplicate API lookups and YAML thrash when running in parallel
-_AUTHOR_CACHE: dict[str, dict[str, str | None]] | None = None
-_AUTHOR_CACHE_MTIME: float | None = None
-_CACHE_LOCK = threading.Lock()
-
-
-def calculate_time_difference(date_string: str) -> tuple[str, str]:
-    """Calculate the time difference between a given date and the current date in a human-readable format.
-
-    Args:
-        date_string (str): Date and time string in the format "%Y-%m-%d %H:%M:%S %z".
-
-    Returns:
-        difference (str): Time difference in days, months, or years (e.g., "5 days", "2 months", "1 year").
-        pretty_date (str): Given date formatted as "Month Day, Year" (e.g., "January 01, 2023").
-
-    Examples:
-        >>> calculate_time_difference("2023-01-01 00:00:00 +0000")
-        ("5 months", "January 01, 2023")
-    """
-    date = datetime.strptime(date_string, "%Y-%m-%d %H:%M:%S %z")
-    pretty_date = date.strftime("%B %d, %Y")
-    now = datetime.now(date.tzinfo)
-    diff = now - date
-    days = diff.days
-
-    if days < 30:
-        difference = f"{days} day{'s' if days != 1 else ''}"
-    elif days < 365:
-        months = days // 30
-        difference = f"{months} month{'s' if months != 1 else ''}"
-    else:
-        years = days // 365
-        difference = f"{years} year{'s' if years != 1 else ''}"
-    return difference, pretty_date
-
-
-def get_youtube_video_ids(soup: BeautifulSoup) -> list[str]:
-    """Extract YouTube video IDs from iframe elements present in the provided BeautifulSoup object.
-
-    Args:
-        soup (BeautifulSoup): A BeautifulSoup object containing the HTML content from which YouTube video IDs need to be
-            extracted.
-
-    Returns:
-        (List[str]): A list containing YouTube video IDs extracted from the HTML content.
-
-    Examples:
-        >>> from bs4 import BeautifulSoup
-        >>> html_content = '''
-        ... <html>
-        ...     <body>
-        ...         <iframe src="https://www.youtube.com/embed/example_id1"></iframe>
-        ...         <iframe src="https://www.youtube.com/embed/example_id2"></iframe>
-        ...     </body>
-        ... </html>
-        ... '''
-        >>> soup = BeautifulSoup(html_content, 'html.parser')
-        >>> video_ids = get_youtube_video_ids(soup)
-        >>> print(video_ids)
-        ['example_id1', 'example_id2']
-    """
-    youtube_ids = []
-    iframes = soup.find_all("iframe", src=True)
-    for iframe in iframes:
-        if match := re.search(r"youtube\.com/embed/([a-zA-Z0-9_-]+)", iframe["src"]):
-            youtube_ids.append(match[1])
-    return youtube_ids
-
-
-def get_github_username_from_email(
-    email: str, cache: dict, file_path: str = "", verbose: bool = True
-) -> tuple[str | None, str | None]:
-    """Retrieve the GitHub username and avatar URL associated with the given email address.
-
-    Args:
-        email (str): The email address to retrieve the GitHub username for.
-        cache (Dict): A dictionary containing cached email-GitHub username mappings.
-        file_path (str, optional): Name of the file the user authored.
-        verbose (bool, optional): Whether to print verbose output.
-
-    Returns:
-        username (str | None): GitHub username if found, None otherwise.
-        avatar (str | None): Avatar URL if found, None otherwise.
-
-    Notes:
-        If the email ends with "@users.noreply.github.com", the function will parse the username directly from the
-        email address. Uses the GitHub REST API to query the username if it's not found in the local cache. Ensure
-        you comply with GitHub's rate limits and authentication requirements when querying their API.
-    """
-    # First, check if the email exists in the local cache file
-    with _CACHE_LOCK:
-        if email in cache:
-            return cache[email].get("username"), cache[email].get("avatar")
-    if not email.strip():
-        if verbose:
-            print(f"{WARNING} No author found for {file_path}")
-        return None, None
-
-    # If the email ends with "@users.noreply.github.com", parse the username directly
-    if email.endswith("@users.noreply.github.com"):
-        username = email.split("+")[-1].split("@")[0]
-        avatar = f"https://github.com/{username}.png"
-        avatar_url = requests.head(avatar, allow_redirects=True).url
-        with _CACHE_LOCK:
-            cache[email] = {
-                "username": username,
-                "avatar": avatar_url,
-            }
-        return username, avatar
-
-    # Fallback to GitHub REST API when not cached
-    url = f"https://api.github.com/search/users?q={email}+in:email&sort=joined&order=asc"
-    if verbose:
-        print(f"Running GitHub REST API for author {email}")
-    response = requests.get(url)
-    if response.status_code == 200:
-        data = response.json()
-        if data["total_count"] > 0:
-            username = data["items"][0]["login"]
-            avatar = data["items"][0]["avatar_url"]  # avatar_url key is correct here
-            avatar_url = requests.head(avatar, allow_redirects=True).url
-            with _CACHE_LOCK:
-                cache[email] = {
-                    "username": username,
-                    "avatar": avatar_url,
-                }
-            return username, avatar
-
-    if verbose:
-        print(f"{WARNING} No username found for {email}")
-    with _CACHE_LOCK:
-        cache[email] = {"username": None, "avatar": None}
-    return None, None
-
-
-def get_github_usernames_from_file(
-    file_path: str,
-    default_user: str | None = None,
-    emails: dict[str, int] | None = None,
-    repo_url: str | None = None,
-    force_reload: bool = False,
-) -> dict[str, dict[str, Any]]:
-    """Fetch GitHub usernames associated with a file using provided Git email counts.
-
-    Args:
-        file_path (str): The path to the file for which GitHub usernames are to be retrieved.
-        default_user (str, optional): Default GitHub user email to use if no authors found.
-
-    Returns:
-        (Dict[str, Dict[str, any]]): A dictionary where keys are GitHub usernames or emails (if username is not
-            found) and values are dictionaries containing:
-            - 'email' (str): The email address of the author.
-            - 'url' (str): The GitHub profile URL of the author.
-            - 'changes' (int): The number of changes (commits) made by the author.
-            - 'avatar' (str): The URL of the author's GitHub avatar.
-
-    Examples:
-        >>> print(get_github_usernames_from_file('mkdocs.yml', emails={'user@example.com': 2}))
-        {'username1': {'email': 'user@example.com', 'url': 'https://github.com/username1', 'changes': 2, 'avatar': '...'}}
-    """
-    if emails is None:
-        emails = {}
-    else:
-        emails = dict(emails)  # shallow copy to avoid mutating caller data
-
-    # If no git info found but default_user provided, use default_user
-    if not emails and default_user:
-        emails[default_user] = 1
-
-    # Load the local cache of GitHub usernames once per process (thread-safe, reload if changed)
-    local_cache_file = Path("docs" if Path("docs").is_dir() else "") / "mkdocs_github_authors.yaml"
-    global _AUTHOR_CACHE, _AUTHOR_CACHE_MTIME
-    with _CACHE_LOCK:
-        current_mtime = local_cache_file.stat().st_mtime if local_cache_file.is_file() else None
-        needs_reload = (
-            force_reload
-            or _AUTHOR_CACHE is None
-            or (_AUTHOR_CACHE_MTIME is not None and current_mtime is not None and _AUTHOR_CACHE_MTIME != current_mtime)
-        )
-        if needs_reload:
-            if local_cache_file.is_file():
-                with local_cache_file.open("r") as f:
-                    _AUTHOR_CACHE = yaml.safe_load(f) or {}
-                _AUTHOR_CACHE_MTIME = local_cache_file.stat().st_mtime
-            else:
-                _AUTHOR_CACHE = {}
-                _AUTHOR_CACHE_MTIME = None
-        cache = _AUTHOR_CACHE
-
-    github_repo_url = repo_url or "https://github.com/ultralytics/ultralytics"
-
-    info = {}
-    cache_updated = False
-    for email, changes in emails.items():
-        if not email and default_user:
-            email = default_user
-        was_cached = email in cache
-        prev_entry = cache.get(email)
-        username, avatar = get_github_username_from_email(email, cache, file_path)
-        # If we can't determine the user URL, revert to the GitHub file URL
-        user_url = f"https://github.com/{username}" if username else github_repo_url
-        info[username or email] = {
-            "email": email,
-            "url": user_url,
-            "changes": changes,
-            "avatar": avatar or DEFAULT_AVATAR,
-        }
-        cache_updated = cache_updated or (email in cache and not was_cached) or cache.get(email) != prev_entry
-
-    # Save the local cache of GitHub usernames and avatar URLs if updated
-    if cache_updated:
-        with _CACHE_LOCK:
-            _AUTHOR_CACHE = cache
-            with local_cache_file.open("w") as f:
-                yaml.safe_dump(cache, f)
-            _AUTHOR_CACHE_MTIME = local_cache_file.stat().st_mtime
-
-    return info