mkdocs-document-dates 3.1.6__tar.gz → 3.2__tar.gz

{mkdocs_document_dates-3.1.6/mkdocs_document_dates.egg-info → mkdocs_document_dates-3.2}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.1.6
+Version: 3.2
 Summary: An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents.
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
 Author-email: aaronwqt@gmail.com
 License: MIT
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
@@ -118,9 +117,9 @@ email: e-name@gmail.com
 
 ## Customization
 
-The plugin supports deep customization, such as **icon style, font style, theme color, animation type, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
+The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
 
-|        Function：        | Location：                               |
+|        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
 |     **Style & Theme**     | `docs/assets/document_dates/user.config.css` |
 | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
@@ -129,7 +128,7 @@ The plugin supports deep customization, such as **icon style, font style, theme
 **Tip**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
 
 - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
-- In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
+- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to load all languages at once
     ```yaml
     extra_javascript:
       - assets/document_dates/core/timeago.full.min.js

{mkdocs_document_dates-3.1.6 → mkdocs_document_dates-3.2}/README.md

@@ -91,9 +91,9 @@ email: e-name@gmail.com
 
 ## Customization
 
-The plugin supports deep customization, such as **icon style, font style, theme color, animation type, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
+The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
 
-|        Function：        | Location：                               |
+|        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
 |     **Style & Theme**     | `docs/assets/document_dates/user.config.css` |
 | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
@@ -102,7 +102,7 @@ The plugin supports deep customization, such as **icon style, font style, theme
 **Tip**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
 
 - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
-- In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
+- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to load all languages at once
     ```yaml
     extra_javascript:
       - assets/document_dates/core/timeago.full.min.js

mkdocs_document_dates-3.2/mkdocs_document_dates/cache_manager.py

@@ -0,0 +1,126 @@
+import logging
+import subprocess
+from pathlib import Path
+from .utils import read_json_cache, read_jsonl_cache, write_jsonl_cache, get_file_creation_time, get_git_first_commit_time
+
+logger = logging.getLogger("mkdocs.plugins.document_dates")
+logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+def find_mkdocs_projects():
+    projects = []
+    try:
+        git_root = Path(subprocess.check_output(
+            ['git', 'rev-parse', '--show-toplevel'],
+            text=True, encoding='utf-8'
+        ).strip())
+
+        # 遍历 git_root 及子目录, 寻找 mkdocs.yml 文件
+        for config_file in git_root.rglob('mkdocs.y*ml'):
+            if config_file.name.lower() in ('mkdocs.yml', 'mkdocs.yaml'):
+                projects.append(config_file.parent)
+
+        if not projects:
+            logger.warning("No MkDocs projects found in the repository")
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Failed to find the Git repository root: {e}")
+    except Exception as e:
+        logger.error(f"Unexpected error while searching for MkDocs projects: {e}")
+    
+    return projects
+
+def setup_gitattributes(docs_dir: Path):
+    try:
+        gitattributes_path = docs_dir / '.gitattributes'
+        union_merge_line = ".dates_cache.jsonl merge=union"
+        # custom_merge_line = ".dates_cache.json merge=custom_json_merge"
+        content = gitattributes_path.read_text(encoding='utf-8') if gitattributes_path.exists() else ""
+        if union_merge_line not in content:
+            if content and not content.endswith('\n'):
+                content += '\n'
+            content += f"{union_merge_line}\n"
+            gitattributes_path.write_text(content, encoding='utf-8')
+            subprocess.run(["git", "add", str(gitattributes_path)], check=True)
+            logger.info(f"Updated .gitattributes file: {gitattributes_path}")
+            return True
+    except (IOError, OSError) as e:
+        logger.error(f"Failed to read/write .gitattributes file: {e}")
+    except Exception as e:
+        logger.error(f"Failed to add .gitattributes to git: {e}")
+    return False
+
+def update_cache():
+    global_updated = False
+
+    for project_dir in find_mkdocs_projects():
+        try:
+            project_updated = False
+
+            docs_dir = project_dir / 'docs'
+            if not docs_dir.exists():
+                logger.error(f"Document directory does not exist: {docs_dir}")
+                continue
+
+            # 设置.gitattributes文件
+            global_updated = setup_gitattributes(docs_dir)
+
+            # 获取docs目录下已跟踪(tracked)的markdown文件
+            cmd = ["git", "ls-files", "*.md"]
+            result = subprocess.run(cmd, cwd=docs_dir, capture_output=True, text=True)
+            tracked_files = result.stdout.splitlines() if result.stdout else []
+
+            if not tracked_files:
+                logger.info(f"No tracked markdown files found in {docs_dir}")
+                continue
+
+            # 读取旧的JSON缓存文件（如果存在）
+            json_cache_file = docs_dir / '.dates_cache.json'
+            json_dates_cache = read_json_cache(json_cache_file)
+
+            # 读取新的JSONL缓存文件（如果存在）
+            jsonl_cache_file = docs_dir / '.dates_cache.jsonl'
+            jsonl_dates_cache = read_jsonl_cache(jsonl_cache_file)
+
+            # 根据 git已跟踪的文件来更新
+            for rel_path in tracked_files:
+                try:
+                    # 如果文件已在JSONL缓存中，跳过
+                    if rel_path in jsonl_dates_cache:
+                        continue
+
+                    full_path = docs_dir / rel_path
+                    # 处理新文件或迁移旧JSON缓存
+                    if rel_path in json_dates_cache:
+                        jsonl_dates_cache[rel_path] = json_dates_cache[rel_path]
+                        project_updated = True
+                    elif full_path.exists():
+                        created_time = get_file_creation_time(full_path)
+                        if not jsonl_cache_file.exists() and not json_cache_file.exists():
+                            git_time = get_git_first_commit_time(full_path)
+                            if git_time:
+                                created_time = min(created_time, git_time)
+                        jsonl_dates_cache[rel_path] = {
+                            "created": created_time.isoformat()
+                        }
+                        project_updated = True
+                except Exception as e:
+                    logger.error(f"Error processing file {rel_path}: {e}")
+                    continue
+
+            # 标记删除不再跟踪的文件
+            if len(jsonl_dates_cache) > len(tracked_files):
+                project_updated = True
+
+            # 如果有更新，写入JSONL缓存文件
+            if project_updated or not jsonl_cache_file.exists():
+                global_updated = write_jsonl_cache(jsonl_cache_file, jsonl_dates_cache, tracked_files)
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Failed to execute git command: {e}")
+            continue
+        except Exception as e:
+            logger.error(f"Error processing project directory {project_dir}: {e}")
+            continue
+    return global_updated
+
+
+if __name__ == "__main__":
+    update_cache()

mkdocs_document_dates-3.2/mkdocs_document_dates/hooks_installer.py

@@ -0,0 +1,109 @@
+import os
+import sys
+import logging
+import subprocess
+from pathlib import Path
+import platform
+
+logger = logging.getLogger("mkdocs.plugins.document_dates")
+logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+def get_config_dir():
+    if platform.system().lower().startswith('win'):
+        return Path(os.getenv('APPDATA', str(Path.home() / 'AppData' / 'Roaming')))
+    else:
+        return Path.home() / '.config'
+
+def check_python_version(interpreter):
+    try:
+        result = subprocess.run(
+            [interpreter, "-c", "import sys; print(sys.version_info >= (3, 7))"],
+            capture_output=True, text=True)
+        if result.returncode == 0 and result.stdout.strip().lower() == 'true':
+            return True
+        else:
+            logger.warning(f"Low python version, requires python_requires >=3.7")
+    except Exception as e:
+        logger.info(f"Failed to check {interpreter}: {str(e)}")
+    return False
+
+def detect_python_interpreter():
+    # 检查可能的Python解释器
+    python_interpreters = ['python3', 'python']
+    for interpreter in python_interpreters:
+        if check_python_version(interpreter):
+            return f'#!/usr/bin/env {interpreter}'
+    
+    # 如果都失败了，使用当前运行的Python解释器
+    return f'#!{sys.executable}'
+
+def setup_hooks_directory():
+    config_dir = get_config_dir() / 'mkdocs-document-dates' / 'hooks'
+    try:
+        config_dir.mkdir(parents=True, exist_ok=True)
+        os.chmod(config_dir, 0o755)
+        return config_dir
+    except PermissionError:
+        logger.error(f"No permission to create directory: {config_dir}")
+    except Exception as e:
+        logger.error(f"Failed to create directory {config_dir}: {str(e)}")
+    return None
+
+def install_hook_file(source_dir: Path, target_dir: Path):
+    try:
+        shebang = detect_python_interpreter()
+        for item in source_dir.iterdir():
+            # 跳过隐藏文件和目录
+            if item.name.startswith('.') or not item.is_file():
+                continue
+            # 添加 shebang 行
+            content = item.read_text(encoding='utf-8')
+            if content.startswith('#!'):
+                content = shebang + os.linesep + content[content.find('\n')+1:]
+            else:
+                content = shebang + os.linesep + content
+
+            target_hook_path = target_dir / item.name
+            target_hook_path.write_text(content, encoding='utf-8')
+            os.chmod(target_hook_path, 0o755)
+
+        return True
+    except Exception as e:
+        logger.error(f"Failed to create hook file {target_hook_path}: {str(e)}")
+    return False
+
+def configure_git_hooks(hooks_dir):
+    try:
+        # 配置自定义合并驱动
+        # script_path = hooks_dir / 'json_merge_driver.py'
+        # subprocess.run(['git', 'config', '--global', 'merge.custom_json_merge.name', 'Custom JSON merge driver'], check=True)
+        # subprocess.run(['git', 'config', '--global', 'merge.custom_json_merge.driver', f'"{sys.executable}" "{script_path}" %O %A %B'], check=True)
+
+        subprocess.run(['git', 'config', '--global', 'core.hooksPath', str(hooks_dir)], check=True)
+        logger.info(f"Git hooks successfully installed in: {hooks_dir}")
+        return True
+    except Exception:
+        logger.warning("Git not detected, using plugin in a no-Git environment")
+    return False
+
+def install():
+    try:
+        # 创建hooks目录
+        target_dir = setup_hooks_directory()
+        if not target_dir:
+            return False
+
+        # 安装hook文件
+        source_dir = Path(__file__).parent / 'hooks'
+        if not install_hook_file(source_dir, target_dir):
+            return False
+
+        # 配置git hooks路径
+        return configure_git_hooks(target_dir)
+
+    except Exception as e:
+        logger.error(f"Unexpected error during hooks installation: {str(e)}")
+        return False
+
+if __name__ == '__main__':
+    install()

{mkdocs_document_dates-3.1.6 → mkdocs_document_dates-3.2}/mkdocs_document_dates/plugin.py

@@ -2,36 +2,15 @@ import os
 import json
 import shutil
 import logging
-import subprocess
 from datetime import datetime
 from pathlib import Path
 from mkdocs.plugins import BasePlugin
 from mkdocs.config import config_options
-from .cache_manager import read_json_cache, read_jsonl_cache, get_file_creation_time, get_git_first_commit_time
-
-# 配置日志等级 (INFO WARNING ERROR)
-logging.basicConfig(
-    level=logging.WARNING,
-    format='%(levelname)s: %(message)s'
-)
-
-
-class Author:
-    def __init__(self, name="", email="", **kwargs):
-        self.name = name
-        self.email = email
-        # 扩展属性
-        self.attributes = kwargs
-    
-    def __getattr__(self, name):
-        return self.attributes.get(name)
-    
-    def to_dict(self):
-        return {
-            'name': self.name,
-            'email': self.email,
-            **self.attributes
-        }
+from mkdocs.structure.pages import Page
+from .utils import Author, read_json_cache, read_jsonl_cache, check_git_repo, get_file_creation_time, get_git_first_commit_time, get_git_authors
+
+logger = logging.getLogger("mkdocs.plugins.document_dates")
+logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
 
 
 class DocumentDatesPlugin(BasePlugin):
@@ -66,12 +45,7 @@ class DocumentDatesPlugin(BasePlugin):
             self.config['locale'] = 'en'
 
         # 检查是否为 Git 仓库
-        try:
-            check_git = subprocess.run(['git', 'rev-parse', '--is-inside-work-tree'], capture_output=True, text=True)
-            if check_git.returncode == 0:
-                self.is_git_repo = True
-        except Exception as e:
-            logging.info(f"Not a Git repository: {str(e)}")
+        self.is_git_repo = check_git_repo()
 
         docs_dir_path = Path(config['docs_dir'])
 
@@ -158,7 +132,7 @@ class DocumentDatesPlugin(BasePlugin):
 
         return config
 
-    def on_page_markdown(self, markdown, page, config, files):
+    def on_page_markdown(self, markdown, page: Page, config, files):
         # 获取相对路径，src_uri 总是以"/"分隔
         rel_path = getattr(page.file, 'src_uri', None)
         if not rel_path:
@@ -194,7 +168,7 @@ class DocumentDatesPlugin(BasePlugin):
         return self._insert_date_info(markdown, info_html)
 
 
-    def _load_translation(self, docs_dir_path):
+    def _load_translation(self, docs_dir_path: Path):
         # 内置语言文件目录
         builtin_dir = Path(__file__).parent / 'static' / 'languages'
         # 用户自定义语言文件目录
@@ -214,16 +188,16 @@ class DocumentDatesPlugin(BasePlugin):
             en_json = builtin_dir / 'en.json'
             shutil.copy2(en_json, custom_en_json)
 
-    def _load_lang_file(self, lang_dir):
+    def _load_lang_file(self, lang_dir: Path):
         try:
             locale_file = lang_dir / f"{self.config['locale']}.json"
             if locale_file.exists():
                 with locale_file.open('r', encoding='utf-8') as f:
                     self.translation = json.load(f)
         except json.JSONDecodeError as e:
-            logging.error(f"Invalid JSON format in language file {locale_file}: {str(e)}")
+            logger.error(f"Invalid JSON format in language file {locale_file}: {str(e)}")
         except Exception as e:
-            logging.error(f"Error loading language file {locale_file}: {str(e)}")
+            logger.error(f"Error loading language file {locale_file}: {str(e)}")
 
 
     def _is_excluded(self, rel_path):
@@ -233,7 +207,7 @@ class DocumentDatesPlugin(BasePlugin):
                 return True
         return False
 
-    def _matches_exclude_pattern(self, rel_path, pattern):
+    def _matches_exclude_pattern(self, rel_path: str, pattern: str):
         if '*' not in pattern:
             return rel_path == pattern
         else:
@@ -268,19 +242,9 @@ class DocumentDatesPlugin(BasePlugin):
         return fs_time
 
     def _get_file_modification_time(self, file_path):
-        """
         # 从git获取最后修改时间
-        if self.is_git_repo:
-            try:
-                # 获取文件最后修改时间
-                cmd = f'git log -1 --format="%aI" --date=iso -- "{file_path}"'
-                process = subprocess.run(cmd, shell=True, capture_output=True, text=True)
-                if process.returncode == 0 and process.stdout.strip():
-                    git_time = process.stdout.strip()
-                    return datetime.fromisoformat(git_time).replace(tzinfo=None)
-            except Exception as e:
-                logging.warning(f"Failed to get git modification time: {str(e)}")
-        """
+        # if self.is_git_repo:
+        #     return get_git_last_commit_time(file_path)
 
         # 从文件系统获取最后修改时间
         stat = os.stat(file_path)
@@ -295,9 +259,10 @@ class DocumentDatesPlugin(BasePlugin):
         if authors:
             return authors
         # 2. git author
-        authors = self._get_git_authors(file_path)
-        if authors:
-            return authors
+        if self.is_git_repo:
+            authors = get_git_authors(file_path)
+            if authors:
+                return authors
         # 3. site_author 或 PC username
         return [Author(name=config.get('site_author') or Path.home().name)]
 
@@ -336,43 +301,18 @@ class DocumentDatesPlugin(BasePlugin):
                     name = email.partition('@')[0]
                 return [Author(name=name, email=email)]
         except Exception as e:
-            logging.warning(f"Error processing author meta: {e}")
-        return None
-
-    def _get_git_authors(self, file_path):
-        if not self.is_git_repo:
-            return None
-        try:
-            # 获取作者信息（为了兼容性，不采用管道命令，在 python 中处理去重）
-            # git_log_cmd = f'git log --format="%an|%ae" -- {file_path} | sort | uniq'
-            # git_log_cmd = f'git log --format="%an|%ae" -- {file_path} | grep -vE "bot|noreply|ci|github-actions|dependabot|renovate" | sort | uniq'            
-            git_log_cmd = ['git', 'log', '--format=%an|%ae', '--', file_path]
-            git_log_result = subprocess.run(git_log_cmd, capture_output=True, text=True, check=False)
-            if git_log_result.returncode != 0 or not git_log_result.stdout.strip():
-                return None
-            
-            # 使用字典去重和存储作者
-            authors_map = {}
-            for line in git_log_result.stdout.splitlines():
-                if not line.strip() or line in authors_map:
-                    continue
-                name, email = line.split('|')
-                authors_map[line] = Author(name=name, email=email)
-
-            return list(authors_map.values()) or None
-        except Exception as e:
-            logging.warning(f"Failed to get git author info: {str(e)}")
+            logger.warning(f"Error processing author meta: {e}")
         return None
 
 
-    def _get_formatted_date(self, date):
+    def _get_formatted_date(self, date: datetime):
         if self.config['type'] == 'timeago':
             return ""
         elif self.config['type'] == 'datetime':
             return date.strftime(f"{self.config['date_format']} {self.config['time_format']}")
         return date.strftime(self.config['date_format'])
 
-    def _generate_html_info(self, created, modified, authors=None):
+    def _generate_html_info(self, created: datetime, modified: datetime, authors=None):
         html = ""
         try:
             locale = 'zh_CN' if self.config['locale'] == 'zh' else self.config['locale']
@@ -405,7 +345,6 @@ class DocumentDatesPlugin(BasePlugin):
                     # 多个作者的情况
                     authors_info = ', '.join(a.name for a in authors if a.name)
                     authors_tooltip = ',&nbsp;'.join(f'<a href="mailto:{a.email}">{a.name}</a>' if a.email else a.name for a in authors)
-                    
                     html += (
                         f"<span data-tippy-content='{self.translation.get('authors', 'Authors')}: {authors_tooltip}'>"
                         f"<span class='material-icons' data-icon='doc_authors'></span>"
@@ -416,21 +355,15 @@ class DocumentDatesPlugin(BasePlugin):
             html += f"</div></div>"
         
         except Exception as e:
-            logging.warning(f"Error generating HTML info: {e}")
+            logger.warning(f"Error generating HTML info: {e}")
         return html
 
 
-    def _insert_date_info(self, markdown, date_info):
-        if not markdown.strip():
-            return markdown
-
+    def _insert_date_info(self, markdown: str, date_info: str):
         if self.config['position'] == 'top':
-            lines = markdown.splitlines()
-            for i, line in enumerate(lines):
-                if line.startswith('# '):
-                    lines.insert(i + 1, date_info)
-                else:
-                    lines.insert(0, date_info)
-                return '\n'.join(lines)
-            return f"{date_info}\n{markdown}"
+            before, _, after = markdown.lstrip().partition('\n')
+            if before.startswith('# '):
+                return f"{before}\n{date_info}\n{after}"
+            else:
+                return f"{date_info}\n{markdown}"
         return f"{markdown}\n\n{date_info}"

mkdocs_document_dates-3.2/mkdocs_document_dates/utils.py

@@ -0,0 +1,147 @@
+import os
+import platform
+import json
+import logging
+import subprocess
+from pathlib import Path
+from datetime import datetime
+
+logger = logging.getLogger("mkdocs.plugins.document_dates")
+logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+class Author:
+    def __init__(self, name="", email="", **kwargs):
+        self.name = name
+        self.email = email
+        # 扩展属性
+        self.attributes = kwargs
+    
+    def __getattr__(self, name):
+        return self.attributes.get(name)
+    
+    def to_dict(self):
+        return {
+            'name': self.name,
+            'email': self.email,
+            **self.attributes
+        }
+
+
+def get_file_creation_time(file_path):
+    try:
+        stat = os.stat(file_path)
+        system = platform.system().lower()
+        if system.startswith('win'):  # Windows
+            return datetime.fromtimestamp(stat.st_ctime)
+        elif system == 'darwin':  # macOS
+            try:
+                return datetime.fromtimestamp(stat.st_birthtime)
+            except AttributeError:
+                return datetime.fromtimestamp(stat.st_ctime)
+        else:  # Linux, 没有创建时间，使用修改时间
+            return datetime.fromtimestamp(stat.st_mtime)
+    except (OSError, ValueError) as e:
+        logger.error(f"Failed to get file creation time for {file_path}: {e}")
+        return datetime.now()
+
+def check_git_repo():
+    try:
+        check_git = subprocess.run(['git', 'rev-parse', '--is-inside-work-tree'], capture_output=True, text=True)
+        if check_git.returncode == 0:
+            return True
+    except Exception as e:
+        logger.info(f"Not a Git repository: {str(e)}")
+    return False
+
+def get_git_first_commit_time(file_path):
+    try:
+        # git log --reverse --format="%aI" -- {file_path} | head -n 1
+        cmd_list = ['git', 'log', '--reverse', '--format=%aI', '--', file_path]
+        process = subprocess.run(cmd_list, capture_output=True, text=True)
+        if process.returncode == 0 and process.stdout.strip():
+            first_line = process.stdout.partition('\n')[0].strip()
+            return datetime.fromisoformat(first_line).replace(tzinfo=None)
+    except Exception as e:
+        logger.info(f"Error getting git first commit time for {file_path}: {e}")
+    return None
+
+def get_git_last_commit_time(file_path):
+    try:
+        cmd_list = ['git', 'log', '-1', '--format=%aI', '--', file_path]
+        process = subprocess.run(cmd_list, capture_output=True, text=True)
+        if process.returncode == 0 and process.stdout.strip():
+            git_time = process.stdout.strip()
+            return datetime.fromisoformat(git_time).replace(tzinfo=None)
+    except Exception as e:
+        logger.info(f"Error getting git last commit time for {file_path}: {e}")
+    return None
+
+def get_git_authors(file_path):
+    try:
+        # 为了兼容性，不采用管道命令，在 python 中处理去重
+        # git log --format="%an|%ae" -- {file_path} | sort | uniq
+        # git log --format="%an|%ae" -- {file_path} | grep -vE "bot|noreply|ci|github-actions|dependabot|renovate" | sort | uniq
+        cmd_list = ['git', 'log', '--format=%an|%ae', '--', file_path]
+        process = subprocess.run(cmd_list, capture_output=True, text=True)
+        if process.returncode == 0 and process.stdout.strip():
+            # 使用字典去重和存储作者
+            authors_map = {}
+            for line in process.stdout.splitlines():
+                if not line.strip() or line in authors_map:
+                    continue
+                name, email = line.split('|')
+                authors_map[line] = Author(name=name, email=email)
+            return list(authors_map.values()) or None
+    except Exception as e:
+        logger.warning(f"Failed to get git author info: {str(e)}")
+    return None
+
+def read_json_cache(cache_file: Path):
+    dates_cache = {}
+    if cache_file.exists():
+        try:
+            with open(cache_file, "r", encoding='utf-8') as f:
+                dates_cache = json.load(f)
+        except (IOError, json.JSONDecodeError) as e:
+            logger.warning(f"Error reading from '.dates_cache.json': {str(e)}")
+    return dates_cache
+
+def read_jsonl_cache(jsonl_file: Path):
+    dates_cache = {}
+    if jsonl_file.exists():
+        try:
+            with open(jsonl_file, "r", encoding='utf-8') as f:
+                for line in f:
+                    try:
+                        entry = json.loads(line.strip())
+                        if entry and isinstance(entry, dict) and len(entry) == 1:
+                            file_path, file_info = next(iter(entry.items()))
+                            dates_cache[file_path] = file_info
+                    except (json.JSONDecodeError, StopIteration) as e:
+                        logger.warning(f"Skipping invalid JSONL line: {e}")
+        except IOError as e:
+            logger.warning(f"Error reading from '.dates_cache.jsonl': {str(e)}")
+    return dates_cache
+
+def write_jsonl_cache(jsonl_file: Path, dates_cache, tracked_files):
+    try:
+        # 使用临时文件写入，然后替换原文件，避免写入过程中的问题
+        temp_file = jsonl_file.with_suffix('.jsonl.tmp')
+        with open(temp_file, "w", encoding='utf-8') as f:
+            for file_path in tracked_files:
+                if file_path in dates_cache:
+                    entry = {file_path: dates_cache[file_path]}
+                    f.write(json.dumps(entry, ensure_ascii=False) + '\n')
+        
+        # 替换原文件
+        temp_file.replace(jsonl_file)
+        
+        # 将文件添加到git
+        subprocess.run(["git", "add", str(jsonl_file)], check=True)
+        logger.info(f"Successfully updated JSONL cache file: {jsonl_file}")
+        return True
+    except (IOError, json.JSONDecodeError) as e:
+        logger.error(f"Failed to write JSONL cache file {jsonl_file}: {e}")
+    except Exception as e:
+        logger.error(f"Failed to add JSONL cache file to git: {e}")
+    return False

{mkdocs_document_dates-3.1.6 → mkdocs_document_dates-3.2/mkdocs_document_dates.egg-info}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.1.6
+Version: 3.2
 Summary: An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents.
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
 Author-email: aaronwqt@gmail.com
 License: MIT
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
@@ -118,9 +117,9 @@ email: e-name@gmail.com
 
 ## Customization
 
-The plugin supports deep customization, such as **icon style, font style, theme color, animation type, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
+The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
 
-|        Function：        | Location：                               |
+|        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
 |     **Style & Theme**     | `docs/assets/document_dates/user.config.css` |
 | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
@@ -129,7 +128,7 @@ The plugin supports deep customization, such as **icon style, font style, theme
 **Tip**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
 
 - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
-- In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
+- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to load all languages at once
     ```yaml
     extra_javascript:
       - assets/document_dates/core/timeago.full.min.js

{mkdocs_document_dates-3.1.6 → mkdocs_document_dates-3.2}/mkdocs_document_dates.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ mkdocs_document_dates/__init__.py
 mkdocs_document_dates/cache_manager.py
 mkdocs_document_dates/hooks_installer.py
 mkdocs_document_dates/plugin.py
+mkdocs_document_dates/utils.py
 mkdocs_document_dates.egg-info/PKG-INFO
 mkdocs_document_dates.egg-info/SOURCES.txt
 mkdocs_document_dates.egg-info/dependency_links.txt

{mkdocs_document_dates-3.1.6 → mkdocs_document_dates-3.2}/setup.py

@@ -28,7 +28,7 @@ try:
 except FileNotFoundError:
     long_description = "An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents."
 
-VERSION = '3.1.6'
+VERSION = '3.2'
 
 setup(
     name="mkdocs-document-dates",
@@ -46,7 +46,6 @@ setup(
     ],
     classifiers=[
         "Programming Language :: Python :: 3",
-        "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ],
     cmdclass={

mkdocs_document_dates-3.1.6/mkdocs_document_dates/cache_manager.py

@@ -1,226 +0,0 @@
-import os
-import json
-import logging
-import platform
-import subprocess
-from datetime import datetime
-from pathlib import Path
-
-# 配置日志等级 (INFO WARNING ERROR)
-logging.basicConfig(
-    level=logging.WARNING,
-    format='%(levelname)s: %(message)s'
-)
-
-def find_mkdocs_projects():
-    projects = []
-    try:
-        git_root = Path(subprocess.check_output(
-            ['git', 'rev-parse', '--show-toplevel'],
-            text=True, encoding='utf-8'
-        ).strip())
-
-        # 遍历 git_root 及子目录, 寻找 mkdocs.yml 文件
-        for config_file in git_root.rglob('mkdocs.y*ml'):
-            if config_file.name.lower() in ('mkdocs.yml', 'mkdocs.yaml'):
-                projects.append(config_file.parent)
-
-        if not projects:
-            logging.warning("No MkDocs projects found in the repository")
-    except subprocess.CalledProcessError as e:
-        logging.error(f"Failed to find the Git repository root: {e}")
-    except Exception as e:
-        logging.error(f"Unexpected error while searching for MkDocs projects: {e}")
-    
-    return projects
-
-def get_file_creation_time(file_path):
-    try:
-        stat = os.stat(file_path)
-        system = platform.system().lower()
-        if system.startswith('win'):  # Windows
-            return datetime.fromtimestamp(stat.st_ctime)
-        elif system == 'darwin':  # macOS
-            try:
-                return datetime.fromtimestamp(stat.st_birthtime)
-            except AttributeError:
-                return datetime.fromtimestamp(stat.st_ctime)
-        else:  # Linux, 没有创建时间，使用修改时间
-            return datetime.fromtimestamp(stat.st_mtime)
-    except (OSError, ValueError) as e:
-        logging.error(f"Failed to get file creation time for {file_path}: {e}")
-        return datetime.now()
-
-def get_git_first_commit_time(file_path):
-    try:
-        # git log --reverse --format="%aI" --date=iso -- {file_path} | head -n 1
-        result = subprocess.run(['git', 'log', '--reverse', '--format=%aI', '--', file_path], capture_output=True, text=True)
-        if result.returncode == 0:
-            first_line = result.stdout.partition('\n')[0].strip()
-            if first_line:
-                return datetime.fromisoformat(first_line).replace(tzinfo=None)
-    except Exception as e:
-        logging.info(f"Error getting git first commit time for {file_path}: {e}")
-    return None
-
-def setup_gitattributes(docs_dir):
-    updated = False
-    try:
-        gitattributes_path = docs_dir / '.gitattributes'
-        union_config_line = ".dates_cache.jsonl merge=union"
-        if gitattributes_path.exists():
-            with open(gitattributes_path, 'r', encoding='utf-8') as f:
-                content = f.read()
-            
-            if union_config_line not in content:
-                with open(gitattributes_path, 'a', encoding='utf-8') as f:
-                    f.write(f"\n{union_config_line}\n")
-                updated = True
-        else:
-            with open(gitattributes_path, 'w', encoding='utf-8') as f:
-                f.write(f"{union_config_line}\n")
-            updated = True
-        
-        if updated:
-            subprocess.run(["git", "add", str(gitattributes_path)], check=True)
-            logging.info(f"Updated .gitattributes file: {gitattributes_path}")
-    except (IOError, OSError) as e:
-        logging.error(f"Failed to read/write .gitattributes file: {e}")
-    except Exception as e:
-        logging.error(f"Failed to add .gitattributes to git: {e}")
-    
-    return updated
-
-def read_json_cache(cache_file):
-    dates_cache = {}
-    if cache_file.exists():
-        try:
-            with open(cache_file, "r", encoding='utf-8') as f:
-                dates_cache = json.load(f)
-        except (IOError, json.JSONDecodeError) as e:
-            logging.warning(f"Error reading from '.dates_cache.json': {str(e)}")
-    return dates_cache
-
-def read_jsonl_cache(jsonl_file):
-    dates_cache = {}
-    if jsonl_file.exists():
-        try:
-            with open(jsonl_file, "r", encoding='utf-8') as f:
-                for line in f:
-                    try:
-                        entry = json.loads(line.strip())
-                        if entry and isinstance(entry, dict) and len(entry) == 1:
-                            file_path, file_info = next(iter(entry.items()))
-                            dates_cache[file_path] = file_info
-                    except (json.JSONDecodeError, StopIteration) as e:
-                        logging.warning(f"Skipping invalid JSONL line: {e}")
-        except IOError as e:
-            logging.warning(f"Error reading from '.dates_cache.jsonl': {str(e)}")
-    return dates_cache
-
-def write_jsonl_cache(jsonl_file, dates_cache, tracked_files):
-    try:
-        # 使用临时文件写入，然后替换原文件，避免写入过程中的问题
-        temp_file = jsonl_file.with_suffix('.jsonl.tmp')
-        with open(temp_file, "w", encoding='utf-8') as f:
-            for file_path in tracked_files:
-                if file_path in dates_cache:
-                    entry = {file_path: dates_cache[file_path]}
-                    f.write(json.dumps(entry, ensure_ascii=False) + '\n')
-        
-        # 替换原文件
-        temp_file.replace(jsonl_file)
-        
-        # 将文件添加到git
-        subprocess.run(["git", "add", str(jsonl_file)], check=True)
-        logging.info(f"Successfully updated JSONL cache file: {jsonl_file}")
-        return True
-    except (IOError, json.JSONDecodeError) as e:
-        logging.error(f"Failed to write JSONL cache file {jsonl_file}: {e}")
-        return False
-    except subprocess.CalledProcessError as e:
-        logging.error(f"Failed to add JSONL cache file to git: {e}")
-        return False
-
-def update_cache():
-    global_updated = False
-
-    for project_dir in find_mkdocs_projects():
-        try:
-            project_updated = False
-
-            docs_dir = project_dir / 'docs'
-            if not docs_dir.exists():
-                logging.error(f"Document directory does not exist: {docs_dir}")
-                continue
-
-            # 设置.gitattributes文件
-            gitattributes_updated = setup_gitattributes(docs_dir)
-            if gitattributes_updated:
-                global_updated = True
-
-            # 获取docs目录下已跟踪(tracked)的markdown文件
-            cmd = ["git", "ls-files", "*.md"]
-            result = subprocess.run(cmd, cwd=docs_dir, capture_output=True, text=True, check=True)
-            tracked_files = result.stdout.splitlines() if result.stdout else []
-
-            if not tracked_files:
-                logging.info(f"No tracked markdown files found in {docs_dir}")
-                continue
-
-            # 读取旧的JSON缓存文件（如果存在）
-            json_cache_file = docs_dir / '.dates_cache.json'
-            json_dates_cache = read_json_cache(json_cache_file)
-
-            # 读取新的JSONL缓存文件（如果存在）
-            jsonl_cache_file = docs_dir / '.dates_cache.jsonl'
-            jsonl_dates_cache = read_jsonl_cache(jsonl_cache_file)
-
-            # 根据 git已跟踪的文件来更新
-            for rel_path in tracked_files:
-                try:
-                    # 如果文件已在JSONL缓存中，跳过
-                    if rel_path in jsonl_dates_cache:
-                        continue
-
-                    full_path = docs_dir / rel_path
-                    # 处理新文件或迁移旧JSON缓存
-                    if rel_path in json_dates_cache:
-                        jsonl_dates_cache[rel_path] = json_dates_cache[rel_path]
-                        project_updated = True
-                    elif full_path.exists():
-                        created_time = get_file_creation_time(full_path)
-                        if not jsonl_cache_file.exists() and not json_cache_file.exists():
-                            git_time = get_git_first_commit_time(full_path)
-                            if git_time:
-                                created_time = min(created_time, git_time)
-                        jsonl_dates_cache[rel_path] = {
-                            "created": created_time.isoformat()
-                        }
-                        project_updated = True
-                except Exception as e:
-                    logging.error(f"Error processing file {rel_path}: {e}")
-                    continue
-
-            # 标记删除不再跟踪的文件
-            files_to_remove = set(jsonl_dates_cache.keys()) - set(tracked_files)
-            if files_to_remove:
-                project_updated = True
-                logging.info(f"Removing {len(files_to_remove)} untracked files from cache")
-
-            # 如果有更新，写入JSONL缓存文件
-            if project_updated or not jsonl_cache_file.exists():
-                if write_jsonl_cache(jsonl_cache_file, jsonl_dates_cache, tracked_files):
-                    global_updated = True
-        except subprocess.CalledProcessError as e:
-            logging.error(f"Failed to execute git command: {e}")
-            continue
-        except Exception as e:
-            logging.error(f"Error processing project directory {project_dir}: {e}")
-            continue
-
-    return global_updated
-
-
-if __name__ == "__main__":
-    update_cache()

mkdocs_document_dates-3.1.6/mkdocs_document_dates/hooks_installer.py

@@ -1,114 +0,0 @@
-import os
-import sys
-import logging
-import subprocess
-from pathlib import Path
-import platform
-
-# 配置日志等级 (INFO WARNING ERROR)
-logging.basicConfig(
-    level=logging.WARNING,
-    format='%(levelname)s: %(message)s'
-)
-
-def get_config_dir():
-    if platform.system().lower().startswith('win'):
-        return Path(os.getenv('APPDATA', str(Path.home() / 'AppData' / 'Roaming')))
-    else:
-        return Path.home() / '.config'
-
-def check_python_version(interpreter):
-    try:
-        result = subprocess.run(
-            [interpreter, "-c", "import sys; print(sys.version_info >= (3, 7))"],
-            capture_output=True, text=True, check=False
-        )
-        if result.returncode == 0 and result.stdout.strip().lower() == 'true':
-            return True
-        else:
-            logging.warning(f"Low python version, requires python_requires >=3.7")
-            return False
-    except Exception as e:
-        logging.debug(f"Failed to check {interpreter}: {str(e)}")
-        return False
-
-def detect_python_interpreter():
-    # 检查可能的Python解释器
-    python_interpreters = ['python3', 'python']
-    
-    for interpreter in python_interpreters:
-        if check_python_version(interpreter):
-            return f'#!/usr/bin/env {interpreter}'
-    
-    # 如果都失败了，使用当前运行的Python解释器
-    return f'#!{sys.executable}'
-
-def setup_hooks_directory():
-    config_dir = get_config_dir() / 'mkdocs-document-dates' / 'hooks'
-    try:
-        config_dir.mkdir(parents=True, exist_ok=True)
-        os.chmod(config_dir, 0o755)
-        return config_dir
-    except PermissionError:
-        logging.error(f"No permission to create directory: {config_dir}")
-        return None
-    except Exception as e:
-        logging.error(f"Failed to create directory {config_dir}: {str(e)}")
-        return None
-
-def install_hook_file(source_hook, target_dir):
-    target_hook_path = target_dir / source_hook.name
-    try:
-        # 读取并更新hook文件内容
-        with open(source_hook, 'r', encoding='utf-8') as f_in:
-            content = f_in.read()
-        
-        # 更新shebang行
-        shebang = detect_python_interpreter()
-        if content.startswith('#!'):
-            content = shebang + os.linesep + content[content.find('\n'):]
-        else:
-            content = shebang + os.linesep + content
-        
-        # 写入并设置权限
-        with open(target_hook_path, 'w', encoding='utf-8') as f_out:
-            f_out.write(content)
-        os.chmod(target_hook_path, 0o755)
-        return True
-    except Exception as e:
-        logging.error(f"Failed to create hook file {target_hook_path}: {str(e)}")
-        return False
-
-def configure_git_hooks(hooks_dir):
-    try:
-        subprocess.run(
-            ['git', 'config', '--global', 'core.hooksPath', str(hooks_dir)],
-            check=True, capture_output=True, encoding='utf-8'
-        )
-        logging.info(f"Git hooks successfully installed in: {hooks_dir}")
-        return True
-    except Exception:
-        logging.warning("Git not detected, failed to set git hooks path")
-        return False
-
-def install():
-    try:
-        # 创建hooks目录
-        hooks_dir = setup_hooks_directory()
-        if not hooks_dir:
-            return False
-
-        # 安装hook文件
-        source_hook = Path(__file__).parent / 'hooks' / 'pre-commit'
-        if not install_hook_file(source_hook, hooks_dir):
-            return False
-
-        # 配置git hooks路径
-        return configure_git_hooks(hooks_dir)
-
-    except Exception as e:
-        logging.error(f"Unexpected error during hooks installation: {str(e)}")
-        return False
-
-if __name__ == '__main__':
-    install()