Metadata-Version: 2.4
Name: nl.export
Version: 1.5.0
Summary: Einfaches Tool für den Zugriff auf ein NL-CMS
Project-URL: PyPI, https://pypi.python.org/pypi/nl.export
Project-URL: Source, https://github.com/gbv/nl.export
Project-URL: Tracker, https://github.com/gbv/nl.export/issues
Author-email: "Marc-J. Tegethoff" <tegethoff@gbv.de>
License: GNU Affero General Public License v3
License-File: LICENSE.txt
Keywords: Nationallizenzen,Plone,Python,VZG
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: lxml
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: zope-interface>=8.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: requests-mock; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://pypi.org/project/nl.export/) verfügbar.

### Endnutzer

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

# Mit pip
pip install nl.export
```

### Entwicklung (lokales Repository)

```sh
# 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
pip install -e ".[dev]"
```

## Konfiguration

Vor der ersten Nutzung muss eine Konfigurationsdatei angelegt werden:

```sh
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:

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

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

```sh
nl-export konfig --show
nl-export konfig --force
```

## Nutzung

### Lizenznehmer exportieren (`lzn`)

```sh
# 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`)

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

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

### Allgemeine Optionen

```sh
# 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

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

### Linting und Formatierung

```sh
ruff check --fix src/
ruff format src/
```

## Lizenz

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

Siehe [COPYING](COPYING) oder [GNU AGPL v3](https://www.gnu.org/licenses/agpl-3.0.html).
