metadata-py 2.0.0
Утилита для управления метаданными в markdown-файлах с автоматическим контролем версий и определением автора
Requires Python: >=3.7

# metadata-py

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

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

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

## Установка.

```bash
pip install metadata-py
```

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

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

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

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

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

## Команды

### update

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

```bash
# Базовое использование
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             # Пропустить подтверждения
```

**Примеры:**

```bash
# Обновить все файлы с автоопределением автора
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

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

```bash
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` с настройками по умолчанию.

```bash
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-комментария:

```markdown
<!-- 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

```yaml
# .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

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

## Публикация в PYPI

https://pypi.org/project/metadata-py/

```Bash
git add .

git commit -m "Bump version to 1.1.0 and update workflow"

git tag -a v1.1.0 -m "Version 1.1.0"

git push origin v1.1.0
```


## Требования

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

## Лицензия

MIT License

## Поддержка

Для сообщения об ошибках и предложений используйте [GitHub Issues](https://github.com/your-repo/metadata-py/issues).

<!-- METADATA
{
  "created_at": "2025-08-04 04:09:00",
  "updated_at": "2025-08-04 07:50:08",
  "author": "woodg9461 <woodg9461@gmail.com>",
  "version": "2.0.0",
  "_fingerprint": "{\"content_hash\": \"272f7cbca455ec287c0dc5a24cfd465232d1275ec1c73e0e5888c0b7770a6166\", \"headers_hash\": \"f2037a39999cfaa1d972c6939c22ae1dfb2327b8f683838b6e89ff2f0643f765\", \"headers\": \"[\\\"2:\\\\u0418\\\\u0433\\\\u043d\\\\u043e\\\\u0440\\\\u0438\\\\u0440\\\\u043e\\\\u0432\\\\u0430\\\\u043d\\\\u0438\\\\u0435 \\\\u0444\\\\u0430\\\\u0439\\\\u043b\\\\u043e\\\\u0432\\\", \\\"2:Authors\\\", \\\"1:\\\\u041e\\\\u0431\\\\u0440\\\\u0430\\\\u0431\\\\u043e\\\\u0442\\\\u043a\\\\u0430 \\\\u0432\\\\u0441\\\\u0435\\\\u0445 markdown-\\\\u0444\\\\u0430\\\\u0439\\\\u043b\\\\u043e\\\\u0432 \\\\u0432 \\\\u0442\\\\u0435\\\\u043a\\\\u0443\\\\u0449\\\\u0435\\\\u0439 \\\\u0434\\\\u0438\\\\u0440\\\\u0435\\\\u043a\\\\u0442\\\\u043e\\\\u0440\\\\u0438\\\\u0438\\\", \\\"3:init-mdignore\\\", \\\"2:\\\\u041f\\\\u043e\\\\u0434\\\\u0434\\\\u0435\\\\u0440\\\\u0436\\\\u043a\\\\u0430\\\", \\\"1:\\\\u0423\\\\u0434\\\\u0430\\\\u043b\\\\u0438\\\\u0442\\\\u044c \\\\u043c\\\\u0435\\\\u0442\\\\u0430\\\\u0434\\\\u0430\\\\u043d\\\\u043d\\\\u044b\\\\u0435 \\\\u0438\\\\u0437 \\\\u0444\\\\u0430\\\\u0439\\\\u043b\\\\u0430\\\", \\\"1:\\\\u041a\\\\u043e\\\\u043c\\\\u043c\\\\u0435\\\\u043d\\\\u0442\\\\u0430\\\\u0440\\\\u0438\\\\u0438 \\\\u043d\\\\u0430\\\\u0447\\\\u0438\\\\u043d\\\\u0430\\\\u044e\\\\u0442\\\\u0441\\\\u044f \\\\u0441 #\\\", \\\"2:\\\\u0410\\\\u0432\\\\u0442\\\\u043e\\\\u043c\\\\u0430\\\\u0442\\\\u0438\\\\u0447\\\\u0435\\\\u0441\\\\u043a\\\\u043e\\\\u0435 \\\\u043e\\\\u043f\\\\u0440\\\\u0435\\\\u0434\\\\u0435\\\\u043b\\\\u0435\\\\u043d\\\\u0438\\\\u0435 \\\\u0430\\\\u0432\\\\u0442\\\\u043e\\\\u0440\\\\u0430\\\", \\\"2:\\\\u0411\\\\u044b\\\\u0441\\\\u0442\\\\u0440\\\\u044b\\\\u0439 \\\\u0441\\\\u0442\\\\u0430\\\\u0440\\\\u0442\\\", \\\"1:\\\\u041e\\\\u0431\\\\u043d\\\\u043e\\\\u0432\\\\u0438\\\\u0442\\\\u044c \\\\u0432\\\\u0441\\\\u0435 \\\\u0444\\\\u0430\\\\u0439\\\\u043b\\\\u044b \\\\u0441 \\\\u0430\\\\u0432\\\\u0442\\\\u043e\\\\u043e\\\\u043f\\\\u0440\\\\u0435\\\\u0434\\\\u0435\\\\u043b\\\\u0435\\\\u043d\\\\u0438\\\\u0435\\\\u043c \\\\u0430\\\\u0432\\\\u0442\\\\u043e\\\\u0440\\\\u0430\\\", \\\"2:\\\\u041b\\\\u0438\\\\u0446\\\\u0435\\\\u043d\\\\u0437\\\\u0438\\\\u044f\\\", \\\"1:\\\\u041e\\\\u0431\\\\u0440\\\\u0430\\\\u0431\\\\u043e\\\\u0442\\\\u043a\\\\u0430 \\\\u043a\\\\u043e\\\\u043d\\\\u043a\\\\u0440\\\\u0435\\\\u0442\\\\u043d\\\\u043e\\\\u0433\\\\u043e \\\\u0444\\\\u0430\\\\u0439\\\\u043b\\\\u0430\\\", \\\"2:\\\\u0421\\\\u0435\\\\u043c\\\\u0430\\\\u043d\\\\u0442\\\\u0438\\\\u0447\\\\u0435\\\\u0441\\\\u043a\\\\u043e\\\\u0435 \\\\u0432\\\\u0435\\\\u0440\\\\u0441\\\\u0438\\\\u043e\\\\u043d\\\\u0438\\\\u0440\\\\u043e\\\\u0432\\\\u0430\\\\u043d\\\\u0438\\\\u0435\\\", \\\"3:Pre-commit Hook\\\", \\\"2:\\\\u041e\\\\u0441\\\\u043d\\\\u043e\\\\u0432\\\\u043d\\\\u044b\\\\u0435 \\\\u0432\\\\u043e\\\\u0437\\\\u043c\\\\u043e\\\\u0436\\\\u043d\\\\u043e\\\\u0441\\\\u0442\\\\u0438\\\", \\\"1:.github/workflows/docs.yml\\\", \\\"1:\\\\u041e\\\\u043f\\\\u0446\\\\u0438\\\\u0438\\\", \\\"2:\\\\u0418\\\\u043d\\\\u0442\\\\u0435\\\\u0433\\\\u0440\\\\u0430\\\\u0446\\\\u0438\\\\u044f \\\\u0432 \\\\u043f\\\\u0440\\\\u043e\\\\u0446\\\\u0435\\\\u0441\\\\u0441\\\\u044b\\\", \\\"3:update\\\", \\\"1:\\\\u0411\\\\u0430\\\\u0437\\\\u043e\\\\u0432\\\\u043e\\\\u0435 \\\\u0438\\\\u0441\\\\u043f\\\\u043e\\\\u043b\\\\u044c\\\\u0437\\\\u043e\\\\u0432\\\\u0430\\\\u043d\\\\u0438\\\\u0435\\\", \\\"1:.pre-commit-config.yaml\\\", \\\"2:\\\\u0423\\\\u0441\\\\u0442\\\\u0430\\\\u043d\\\\u043e\\\\u0432\\\\u043a\\\\u0430\\\", \\\"2:\\\\u0422\\\\u0440\\\\u0435\\\\u0431\\\\u043e\\\\u0432\\\\u0430\\\\u043d\\\\u0438\\\\u044f\\\", \\\"1:metadata-py\\\", \\\"3:\\\\u041f\\\\u043e\\\\u043b\\\\u044f \\\\u043c\\\\u0435\\\\u0442\\\\u0430\\\\u0434\\\\u0430\\\\u043d\\\\u043d\\\\u044b\\\\u0445\\\", \\\"1:\\\\u0413\\\\u0435\\\\u043d\\\\u0435\\\\u0440\\\\u0430\\\\u0446\\\\u0438\\\\u044f \\\\u043e\\\\u0442\\\\u0447\\\\u0451\\\\u0442\\\\u0430\\\", \\\"1:\\\\u0423\\\\u0441\\\\u0442\\\\u0430\\\\u043d\\\\u043e\\\\u0432\\\\u0438\\\\u0442\\\\u044c \\\\u043a\\\\u043e\\\\u043d\\\\u043a\\\\u0440\\\\u0435\\\\u0442\\\\u043d\\\\u043e\\\\u0433\\\\u043e \\\\u0430\\\\u0432\\\\u0442\\\\u043e\\\\u0440\\\\u0430 \\\\u0438 \\\\u0432\\\\u0435\\\\u0440\\\\u0441\\\\u0438\\\\u044e\\\", \\\"1:\\\\u0418\\\\u0433\\\\u043d\\\\u043e\\\\u0440\\\\u0438\\\\u0440\\\\u043e\\\\u0432\\\\u0430\\\\u0442\\\\u044c \\\\u043e\\\\u043f\\\\u0440\\\\u0435\\\\u0434\\\\u0435\\\\u043b\\\\u0451\\\\u043d\\\\u043d\\\\u044b\\\\u0435 \\\\u0444\\\\u0430\\\\u0439\\\\u043b\\\\u044b\\\", \\\"2:Summary\\\", \\\"2:Version Distribution\\\", \\\"3:CI/CD\\\", \\\"3:report\\\", \\\"1:\\\\u041f\\\\u0440\\\\u0435\\\\u0434\\\\u0432\\\\u0430\\\\u0440\\\\u0438\\\\u0442\\\\u0435\\\\u043b\\\\u044c\\\\u043d\\\\u044b\\\\u0439 \\\\u043f\\\\u0440\\\\u043e\\\\u0441\\\\u043c\\\\u043e\\\\u0442\\\\u0440 \\\\u0438\\\\u0437\\\\u043c\\\\u0435\\\\u043d\\\\u0435\\\\u043d\\\\u0438\\\\u0439\\\", \\\"1:Markdown Files Metadata Report\\\", \\\"2:\\\\u0424\\\\u043e\\\\u0440\\\\u043c\\\\u0430\\\\u0442 \\\\u043c\\\\u0435\\\\u0442\\\\u0430\\\\u0434\\\\u0430\\\\u043d\\\\u043d\\\\u044b\\\\u0445\\\", \\\"2:\\\\u041a\\\\u043e\\\\u043c\\\\u0430\\\\u043d\\\\u0434\\\\u044b\\\"]\"}"
}
-->