04 Integration

Integration in andere Projekte

manuscript-tools laesst sich als Library in eigene Python-Projekte einbinden. Drei Wege, je nach Situation.

Variante 1: Aus PyPI (nach dem Publish)

cd mein-buchprojekt
poetry add manuscript-tools

Danach im Code:

from manuscript_tools.checker import check_file, check_files, DEFAULT_RULES
from manuscript_tools.sanitizer import sanitize_text, sanitize_file
from manuscript_tools.metrics import count_words, file_metrics, batch_metrics
from manuscript_tools.io import resolve_files
from manuscript_tools.models import StyleViolation, FileReport

Die CLI-Kommandos ms-check, ms-sanitize und ms-metrics sind nach der Installation ebenfalls global verfuegbar.

Variante 2: Lokale Path-Dependency (Entwicklung)

Wenn manuscript-tools und dein Projekt nebeneinander auf der Festplatte liegen:

projekte/
├── manuscript-tools/
└── mein-buchprojekt/

cd mein-buchprojekt
poetry add ../manuscript-tools --editable

Erzeugt in pyproject.toml:

[tool.poetry.dependencies]
manuscript-tools = { path = "../manuscript-tools", develop = true }

develop = true bedeutet: Aenderungen an manuscript-tools wirken sofort, kein Rebuild noetig. Ideal waehrend der Entwicklung.

Variante 3: Direkt aus Git

poetry add git+https://github.com/dein-user/manuscript-tools.git

Mit spezifischem Tag:

poetry add git+https://github.com/dein-user/manuscript-tools.git#v0.1.0

Mit Branch:

poetry add git+https://github.com/dein-user/manuscript-tools.git#main

Anwendungsbeispiele

Build-Skript fuer ein Buchprojekt

#!/usr/bin/env python3
"""build.py - Validiert und misst das Manuskript vor dem Export."""

import sys
from pathlib import Path

from manuscript_tools.checker import ALL_RULES_DE, check_files
from manuscript_tools.io import resolve_files
from manuscript_tools.metrics import batch_readability, flesch_de_label
from manuscript_tools.sanitizer import sanitize_file


def main() -> None:
    root = Path("manuscript")
    files = resolve_files(root)

    if not files:
        print("Keine Markdown-Dateien gefunden.")
        sys.exit(1)

    # 1) Bereinigen
    for f in files:
        result = sanitize_file(f, backup=True)
        if result.changed:
            print(f"Bereinigt: {f}")

    # 2) Style-Check (alle Regeln)
    reports = check_files(files, rules=ALL_RULES_DE)
    violations = [v for r in reports for v in r.violations]

    if violations:
        for v in violations:
            print(f"FAIL: {v.file}:{v.line} [{v.rule}] {v.message}")
        print(f"\n{len(violations)} Verstoesse gefunden. Abbruch.")
        sys.exit(1)

    # 3) Lesbarkeit
    results = batch_readability(files)
    total_words = sum(r.readability.words for r in results if not r.error)
    total_sentences = sum(r.readability.sentences for r in results if not r.error)
    total_syllables = sum(r.readability.syllables for r in results if not r.error)

    if total_sentences > 0:
        from manuscript_tools.metrics import flesch_de

        score = flesch_de(total_words, total_sentences, total_syllables)
        label = flesch_de_label(score)
        print(f"\nManuskript OK. {len(files)} Dateien, {total_words:,} Woerter.")
        print(f"Lesbarkeit: Flesch-DE {score:.1f} ({label})")


if __name__ == "__main__":
    main()

Pre-Commit-Hook mit der Library

#!/usr/bin/env python3
"""pre-commit hook: prueft nur geaenderte .md Dateien."""

import subprocess
import sys
from pathlib import Path

from manuscript_tools.checker import check_files


def staged_md_files() -> list[Path]:
    result = subprocess.run(
        ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"],
        capture_output=True,
        text=True,
    )
    return [Path(f) for f in result.stdout.splitlines() if f.endswith(".md")]


def main() -> None:
    files = staged_md_files()
    if not files:
        sys.exit(0)

    reports = check_files(files)
    failed = [r for r in reports if not r.ok]

    if failed:
        for r in failed:
            for v in r.violations:
                print(f"{v.file}:{v.line} [{v.rule}] {v.message}")
        sys.exit(1)


if __name__ == "__main__":
    main()

Jenkins-Pipeline-Stage

stage('Manuscript Validation') {
    steps {
        sh '''
            cd manuscript-tools
            poetry install
            poetry run ms-validate manuscript/
        '''
    }
}

Alternativ mit automatischer Bereinigung:

stage('Manuscript Validation') {
    steps {
        sh '''
            cd manuscript-tools
            poetry install
            poetry run ms-validate manuscript/ --fix
        '''
    }
}

---

Zurueck: Eigene Regeln | Weiter: Publishing