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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-ultralytics-plugin
-Version: 0.2.2
+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.2 → 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.2
+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.2 → 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.2"
+__version__ = "0.2.4"
 
 from .main import MetaPlugin
 from .postprocess import postprocess_site

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

@@ -3,8 +3,11 @@
 
 from __future__ import annotations
 
+import os
 from collections.abc import Callable
+from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor, as_completed
 from pathlib import Path
+from typing import Any
 
 try:
     from ultralytics.utils import TQDM  # progress bars
@@ -13,6 +16,39 @@ 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
+
+
+def _set_worker_state(state: dict[str, Any]) -> None:
+    global _WORKER_STATE
+    _WORKER_STATE = state
+
+
+def _process_file(html_file: Path) -> bool:
+    if _WORKER_STATE is None:
+        raise RuntimeError("Worker state not initialized")
+    return process_html_file(
+        html_file,
+        _WORKER_STATE["site_dir"],
+        _WORKER_STATE["md_index"],
+        _WORKER_STATE["git_data"],
+        _WORKER_STATE["repo_url"],
+        site_url=_WORKER_STATE["site_url"],
+        default_image=_WORKER_STATE["default_image"],
+        add_desc=_WORKER_STATE["add_desc"],
+        add_image=_WORKER_STATE["add_image"],
+        add_keywords=_WORKER_STATE["add_keywords"],
+        add_share_buttons=_WORKER_STATE["add_share_buttons"],
+        add_authors=_WORKER_STATE["add_authors"],
+        add_json_ld=_WORKER_STATE["add_json_ld"],
+        add_css=_WORKER_STATE["add_css"],
+        add_copy_llm=_WORKER_STATE["add_copy_llm"],
+        verbose=_WORKER_STATE["verbose"],
+        log=None,
+    )
 
 
 def process_html_file(
@@ -23,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,
@@ -78,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,
@@ -115,6 +149,8 @@ def postprocess_site(
     add_css: bool = True,
     add_copy_llm: bool = True,
     verbose: bool = True,
+    use_processes: bool = True,
+    workers: int | None = None,
 ) -> None:
     """Process all HTML files in the site directory."""
     site_dir = Path(site_dir)
@@ -129,47 +165,86 @@ def postprocess_site(
         print(f"No HTML files found in {site_dir}")
         return
 
+    worker_count = min(os.cpu_count() or 1, workers or os.cpu_count() or 1)
+
     # Build markdown index once (O(N) instead of O(N²)) using relative paths as keys
-    md_index = {}
-    if docs_dir.exists():
-        for md_file in docs_dir.rglob("*.md"):
-            rel_path = md_file.relative_to(docs_dir).with_suffix("").as_posix()
-            md_index[rel_path] = str(md_file)
+    md_index = (
+        {md.relative_to(docs_dir).with_suffix("").as_posix(): str(md) for md in docs_dir.rglob("*.md")}
+        if docs_dir.exists()
+        else {}
+    )
 
-    print(f"Processing {len(html_files)} HTML files in {site_dir}")
+    mode = "process" if use_processes else "thread"
+    print(f"Processing {len(html_files)} HTML files in {site_dir} with {worker_count} {mode} worker(s)")
 
     processed = 0
     repo_url = None
     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.
+    log_fn = (progress.write if verbose and progress else print if verbose else None) if worker_count == 1 else None
+
+    task_kwargs = dict(
+        site_dir=site_dir,
+        md_index=md_index,
+        git_data=git_data,
+        repo_url=repo_url,
+        site_url=site_url,
+        default_image=default_image,
+        add_desc=add_desc,
+        add_image=add_image,
+        add_keywords=add_keywords,
+        add_share_buttons=add_share_buttons,
+        add_authors=add_authors,
+        add_json_ld=add_json_ld,
+        add_css=add_css,
+        add_copy_llm=add_copy_llm,
+        verbose=verbose,
+    )
+
+    if worker_count == 1:
+        for html_file in html_files:
+            success = process_html_file(html_file, **task_kwargs, log=log_fn)
+            processed += bool(success)
+            if progress:
+                progress.update(1)
+    else:
+        if use_processes:
+            state = {**task_kwargs}
+            executor_context = ProcessPoolExecutor(
+                max_workers=worker_count, initializer=_set_worker_state, initargs=(state,)
+            )
+
+            def submit_fn(ex, f):
+                return ex.submit(_process_file, f)
+        else:
+            executor_context = ThreadPoolExecutor(max_workers=worker_count)
+
+            def submit_fn(ex, f):
+                return ex.submit(process_html_file, f, **task_kwargs, log=log_fn)
+
+        with executor_context as executor:
+            future_to_file = {submit_fn(executor, html_file): html_file for html_file in html_files}
+
+            for future in as_completed(future_to_file):
+                html_file = future_to_file[future]
+                try:
+                    success = future.result()
+                except Exception as e:
+                    success = False
+                    if verbose:
+                        (log_fn or print)(f"Error processing {html_file}: {e}")
+                if success:
+                    processed += 1
+                if progress:
+                    progress.update(1)
 
-    progress = TQDM(html_files, desc="Postprocessing", unit="file", disable=not verbose) if TQDM else None
-    log_fn = (progress.write if verbose and progress else print) if verbose else None
-    iterator = progress if progress else html_files
-    for html_file in iterator:
-        success = process_html_file(
-            html_file,
-            site_dir,
-            md_index,
-            git_data,
-            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,
-            add_share_buttons=add_share_buttons,
-            add_authors=add_authors,
-            add_json_ld=add_json_ld,
-            add_css=add_css,
-            add_copy_llm=add_copy_llm,
-            verbose=verbose,
-            log=log_fn,
-        )
-        if success:
-            processed += 1
     if progress:
         progress.close()
 

{mkdocs_ultralytics_plugin-0.2.2 → 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.2/plugin/utils.py

@@ -1,203 +0,0 @@
-# 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  # 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
-
-
-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
-    if email in cache:
-        return cache[email].get("username"), cache[email].get("avatar")
-    elif 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"
-        cache[email] = {
-            "username": username,
-            "avatar": requests.head(avatar, allow_redirects=True).url,
-        }
-        return username, avatar
-
-    # If the email is not found in the cache, query GitHub REST API
-    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
-            cache[email] = {
-                "username": username,
-                "avatar": requests.head(avatar, allow_redirects=True).url,
-            }
-            return username, avatar
-
-    if verbose:
-        print(f"{WARNING} No username found for {email}")
-    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,
-) -> 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
-    local_cache_file = Path("docs" if Path("docs").is_dir() else "") / "mkdocs_github_authors.yaml"
-    if local_cache_file.is_file():
-        with local_cache_file.open("r") as f:
-            cache = yaml.safe_load(f) or {}
-    else:
-        cache = {}
-
-    github_repo_url = repo_url or "https://github.com/ultralytics/ultralytics"
-
-    info = {}
-    for email, changes in emails.items():
-        if not email and default_user:
-            email = default_user
-        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,
-        }
-
-    # Save the local cache of GitHub usernames and avatar URLs
-    with local_cache_file.open("w") as f:
-        yaml.safe_dump(cache, f)
-
-    return info