Claude
d2dd837f26
A Python CLI tool for generating financial reports from Paperless-ngx: - Phase 1 (MVP): Config handling, Paperless API client with auth and pagination, custom fields extraction, tag-based summation, CLI output - Phase 2 (Grouping): Multiple grouping criteria (tag, correspondent, category, payment type, month, quarter, year), percentage distribution - Phase 3 (Reports): HTML reports with Chart.js diagrams (doughnut, bar, line charts), PDF export via WeasyPrint, JSON and CSV export - Phase 4 (Comfort): Automatic tag ID resolution, disk caching with diskcache, colorized logging, comprehensive error handling Features: - Flexible date filtering (year, month, date range) - Period comparison with change analysis - Swiss franc formatting (CHF with apostrophe separators) - Interactive HTML reports with sortable tables and document links - Multiple output formats (CLI, HTML, PDF, JSON, CSV)
4.6 KiB
4.6 KiB
Paperless Finance Report
Ein Python-basiertes CLI-Tool, das über die Paperless-ngx REST-API Dokumente abruft, Beträge und Custom Fields extrahiert und daraus Finanzberichte generiert.
Features
- Basis-Auswertung: Summe aller Beträge nach Tags, Kategorien, Korrespondenten
- Zeiträume: Filter nach Jahr, Monat oder beliebigem Datumsbereich
- Gruppierung: Nach Tag, Kategorie, Korrespondent, Zahlungsart, Monat, Quartal
- Vergleichsberichte: Jahresvergleiche mit Veränderungsanalyse
- Mehrere Ausgabeformate: CLI, HTML (mit Chart.js Diagrammen), PDF, JSON, CSV
- Caching: Optionaler Festplatten-Cache für bessere Performance
- Flexibel: Konfigurierbare Custom Field Namen
Installation
Voraussetzungen
- Python 3.8+
- Paperless-ngx Installation mit REST-API Zugriff
- API-Token (erstellen unter: Paperless → Einstellungen → Authentifizierungs-Tokens)
Installation
# Repository klonen
git clone https://github.com/yourusername/paperless-report.git
cd paperless-report
# Virtuelle Umgebung erstellen
python3 -m venv venv
source venv/bin/activate # Linux/macOS
# oder: venv\Scripts\activate # Windows
# Dependencies installieren
pip install -r requirements.txt
# Optional: Vollinstallation mit PDF-Support
pip install -e ".[full]"
Konfiguration
# Beispiel-Konfiguration erstellen
cp config.yaml.example config.yaml
# Konfiguration anpassen
nano config.yaml
Mindestens erforderlich:
paperless:
url: "http://localhost:8000" # Deine Paperless URL
token: "YOUR_API_TOKEN" # API Token
Alternativ kann der Token auch als Umgebungsvariable gesetzt werden:
export PAPERLESS_TOKEN="your_api_token"
Verwendung
Verbindung testen
python main.py test
Jahresbericht
# CLI-Ausgabe
python main.py report --year 2024
# Mit Details
python main.py report --year 2024 --detail
# HTML-Bericht
python main.py report --year 2024 --format html
# PDF-Bericht
python main.py report --year 2024 --format pdf
Mit Filtern
# Nach Tag filtern
python main.py report --year 2024 --tag rechnung
# Nach Korrespondent filtern
python main.py report --year 2024 --correspondent "Swisscom"
# Nach Monat filtern
python main.py report --year 2024 --month 6
Gruppierung
# Nach Tag gruppieren (Standard)
python main.py report --year 2024 --group-by tag
# Nach Korrespondent gruppieren
python main.py report --year 2024 --group-by correspondent
# Nach Kategorie und Monat gruppieren
python main.py report --year 2024 --group-by category --group-by month
Jahresvergleich
# CLI-Vergleich
python main.py compare 2023 2024
# HTML-Vergleichsbericht
python main.py compare 2023 2024 --format html
Weitere Befehle
# Dokumente auflisten
python main.py list-docs --tag rechnung --limit 50
# Cache löschen
python main.py clear-cache
# Hilfe anzeigen
python main.py --help
python main.py report --help
Custom Fields in Paperless
Für die volle Funktionalität sollten folgende Custom Fields in Paperless angelegt werden:
| Feldname | Typ | Beschreibung |
|---|---|---|
betrag |
Währung | Rechnungsbetrag |
rechnungsdatum |
Datum | Datum der Rechnung |
kategorie |
Auswahl | Wohnen, Gesundheit, Mobilität, etc. |
zahlungsart |
Auswahl | Bar, Einzahlung, LSV, eBill |
Die Feldnamen können in der config.yaml angepasst werden.
Ausgabeformate
CLI
Einfache tabellarische Ausgabe im Terminal.
HTML
Interaktiver Bericht mit:
- Zusammenfassungskarten
- Chart.js Diagramme (Doughnut, Bar, Line)
- Sortierbare Tabellen
- Links zu Paperless-Dokumenten
- Export-Button für CSV
Druckfertiger PDF-Bericht (benötigt WeasyPrint).
JSON
Maschinenlesbares Format für weitere Verarbeitung.
CSV
Excel-kompatibles Format mit BOM für korrekte Umlaute.
Projektstruktur
paperless-report/
├── config.yaml.example # Beispiel-Konfiguration
├── config.py # Konfigurationsmanagement
├── paperless_client.py # API-Client
├── extractor.py # Datenextraktion und -aggregation
├── report_generator.py # Berichtsgenerierung
├── main.py # CLI-Einstiegspunkt
├── templates/
│ └── report.html # HTML-Template
├── output/ # Generierte Berichte
├── requirements.txt
├── setup.py
└── README.md
Lizenz
MIT License