metadata-py

metadata-py — это CLI-утилита для автоматического управления блоками метаданных в markdown-файлах. Она позволяет добавлять, обновлять и удалять метаданные, автоматически определять автора, вести контроль версий по семантическим правилам и массово обрабатывать файлы с учётом игнорирования по паттернам.

Основные возможности

• Автоматическое управление метаданными: Добавление, обновление и удаление блоков метаданных в markdown-файлах
• Семантическое версионирование: Автоматическое увеличение версий на основе типа изменений (major/minor/patch)
• Автоматическое определение автора: Умное определение автора из Git, переменных окружения или системной информации
• Массовая обработка: Обработка всех markdown-файлов в директории с поддержкой паттернов игнорирования
• Отчёты: Генерация подробных отчётов о состоянии метаданных в проекте
• Dry-run режим: Предварительный просмотр изменений без их применения

Установка

pip install metadata-py

Быстрый старт

# Обработка всех markdown-файлов в текущей директории
metadata-py update

# Обработка конкретного файла
metadata-py update README.md

# Предварительный просмотр изменений
metadata-py update --dry-run

# Генерация отчёта
metadata-py report

Команды

update

Обновление метаданных в markdown-файлах.

# Базовое использование
metadata-py update [файлы...]

# Опции
--verbose, -v         # Подробный вывод
--set KEY=VALUE       # Установка значений метаданных
--remove, -r          # Удаление метаданных
--overwrite, -o       # Полная перезапись метаданных
--dry-run, -n         # Предварительный просмотр
--ignore PATTERN      # Игнорирование по паттерну
--ignore-file FILE    # Файл с паттернами игнорирования
--exclude-root        # Исключить файлы из корня
--no-auto-author      # Отключить автоопределение автора
--yes, -y             # Пропустить подтверждения

Примеры:

# Обновить все файлы с автоопределением автора
metadata-py update

# Установить конкретного автора и версию
metadata-py update --set author="John Doe" --set version="2.0.0"

# Удалить метаданные из файла
metadata-py update --remove README.md

# Игнорировать определённые файлы
metadata-py update --ignore "drafts/*" --ignore "*.draft.md"

report

Генерация отчёта о состоянии метаданных в проекте.

metadata-py report

Пример вывода:

# Markdown Files Metadata Report

Generated on: 2025-08-04 07:45:17
Project directory: /path/to/project

## Summary
- Total markdown files: 7
- Files with metadata: 7
- Files without metadata: 0
- Coverage: 100.0%

## Authors
Total authors: 3
- John Doe: 4 files
- Jane Smith: 2 files
- Bot User: 1 files

## Version Distribution
- v1.0.0: 5 files
- v2.0.0: 2 files

init-mdignore

Создание файла .mdignore с настройками по умолчанию.

metadata-py init-mdignore [--force]

Семантическое версионирование

Система автоматически определяет тип изменений и увеличивает версию:

• Major версия (X.0.0): Изменения заголовков первого уровня (# Заголовок)
• Minor версия (0.X.0): Изменения подзаголовков (## Подзаголовок, ### Подзаголовок)
• Patch версия (0.0.X): Изменения содержимого без изменения структуры заголовков

Автоматическое определение автора

Скрипт определяет автора в следующем порядке приоритета:

1. Git информация:

   • Автор последнего коммита для конкретного файла
   • Настройки Git репозитория (user.name и user.email)

2. Переменные окружения:

   • AUTHOR_NAME
   • GIT_AUTHOR_NAME
   • USER
   • USERNAME

3. Системная информация:

   • Владелец файла в файловой системе
   • Текущий пользователь системы

Формат метаданных

Метаданные добавляются в конец markdown-файла в виде HTML-комментария:

<!-- METADATA
{
  "created_at": "2025-08-04 04:09:00",
  "updated_at": "2025-08-04 07:21:12",
  "author": "John Doe <john@example.com>",
  "version": "1.1.0",
  "_fingerprint": "{\"content_hash\": \"...\", \"headers_hash\": \"...\"}"
}
-->

Поля метаданных

• created_at: Дата и время создания метаданных
• updated_at: Дата и время последнего обновления
• author: Автор файла
• version: Версия документа (семантическое версионирование)
• _fingerprint: Цифровой отпечаток для отслеживания изменений

Игнорирование файлов

Создайте файл .mdignore для исключения файлов из обработки:

# Комментарии начинаются с #
*.draft.md
drafts/
temp/
node_modules/

Поддерживаются glob-паттерны:

• * — любые символы
• ? — один символ
• ** — рекурсивный поиск в поддиректориях

Интеграция в процессы

CI/CD

# .github/workflows/docs.yml
name: Update Documentation Metadata

on:
  push:
    paths:
      - '**/*.md'

jobs:
  update-metadata:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install metadata-py
        run: pip install metadata-py
      - name: Update metadata
        run: metadata-py update --yes
      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add -A
          git diff --staged --quiet || git commit -m "Update documentation metadata"
          git push

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: metadata-py
        name: Update markdown metadata
        entry: metadata-py update --yes
        language: system
        files: \.md$

Требования

• Python 3.6+
• Стандартные библиотеки Python

Лицензия

MIT License

Поддержка

Для сообщения об ошибках и предложений используйте GitHub Issues.