nl-export

nl-export ist ein Kommandozeilen-Tool, um Daten aus einem NL-CMS (Plone) via REST-API zu exportieren.

Entwickelt von der Verbundzentrale des GBV (VZG) für die Nutzung im Kontext der Nationallizenzen.

Funktionen

• konfig — Konfiguration mit API-Zugangsdaten erstellen und anzeigen
• lzn — Lizenznehmer zu einem oder mehreren Lizenzmodellen/Produkten exportieren
  • Ausgabeformate: CSV, XML, JSON (v1/v2/v3 Schema)
• proxy — Einzelnutzer-Lizenzmodelle für den Proxy-Betrieb exportieren (CSV)

Voraussetzungen

• Python ≥ 3.12
• Zugriff auf ein NL-CMS mit gültigem Access-Token

Installation

Das Paket ist auf PyPI verfügbar.

Endnutzer

# Mit uv (empfohlen)
uv tool install nl.export

# Mit pip (in einer isolierten Umgebung)
mkdir nl-export && cd nl-export
python3 -m venv .venv
source .venv/bin/activate
pip install nl.export

Entwicklung (lokales Repository)

# Repository klonen
git clone https://github.com/gbv/nl.export.git
cd nl.export

# Mit uv
uv tool install .
uv pip install -e ".[dev]"

# Mit pip (in einer isolierten Umgebung)
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Konfiguration

Vor der ersten Nutzung muss eine Konfigurationsdatei angelegt werden:

nl-export konfig

Das Tool fragt nach Access-Token und CMS-URL und legt die Konfiguration unter folgendem Pfad an:

$XDG_CONFIG_HOME/nl_export.conf

Falls $XDG_CONFIG_HOME nicht gesetzt ist, wird ~/.config/nl_export.conf verwendet.

Die Datei hat folgendes Format:

[plone]
access-token = IhrTokenHier
base-url = https://cms.example.com

Mit --show wird die vorhandene Konfiguration angezeigt, mit --force wird sie überschrieben:

nl-export konfig --show
nl-export konfig --force

Nutzung

Lizenznehmer exportieren (lzn)

# CSV-Export (Standard)
nl-export lzn https://cms.example.de/lizenzmodell/eindeutige-id

# XML-Export mit Schema v2
nl-export lzn --format xml --version 2 https://cms.example.de/lizenzmodell/eindeutige-id

# JSON-Export in ein bestimmtes Verzeichnis
nl-export lzn --format json --ablage /pfad/zum/exportverzeichnis \
    https://cms.example.de/lizenzmodell/eindeutige-id

# Nur ASCII-Zeichen in Dateinamen verwenden
nl-export lzn --only-ascii https://cms.example.de/lizenzmodell/eindeutige-id

# Nach Status filtern (mehrfach möglich)
nl-export lzn --status published --status expired https://cms.example.de/lizenzmodell/eindeutige-id

# Mit UUID statt voller URL
nl-export lzn 123e4567-e89b-12d3-a456-426614174000

# Mehrere Lizenzmodelle auf einmal
nl-export lzn https://cms.example.de/lizenzmodell/1 https://cms.example.de/lizenzmodell/2

Die Exportdateien werden standardmäßig im aktuellen Verzeichnis abgelegt (ä̈nderbar mit --ablage).

Versionen des Export-Schemas

Version	Beschreibung
v1	Basis-Schema
v2	Erweitertes Schema
v3	Schema mit ip_proxy_server und use_theipregistry_org-Feldern

Proxy-Konfiguration exportieren (proxy)

# Standard-Ausgabe nach ./lmodels_singleuser.csv
nl-export proxy

# Ausgabe in eine bestimmte Datei
nl-export proxy --csvdatei /pfad/zur/datei.csv

Allgemeine Optionen

# Ausführliche Ausgabe
nl-export -v

Ausgabeformate

CSV

• Trennzeichen: Semikolon (;)
• Alle Felder in Anführungszeichen (QUOTE_ALL)
• UTF-8-Kodierung

XML

• Namespace: http://www.nationallizenzen.de/ns/nl
• UTF-8-Kodierung

JSON

• Strukturierte JSON-Dateien
• UTF-8-Kodierung

Entwicklung

Tests ausführen

python3 -m pytest src/nl/export/test/ -v

Linting und Formatierung

ruff check --fix src/
ruff format src/

Lizenz

GNU Affero General Public License v3 (AGPL-3.0).

Siehe COPYING oder GNU AGPL v3.