Metadata-Version: 2.4
Name: mds-exporter
Version: 0.1.1
Summary: A CLI tool for bulk downloading from museum data service API with rich progress tracking.
Project-URL: Homepage, https://github.com/wrmthorne/mds-exporter
Project-URL: Bug Reports, https://github.com/wrmthorne/mds-exporter/issues
Project-URL: Source, https://github.com/wrmthorne/mds-exporter
Author-email: William Thorne <wthorne1@sheffield.ac.uk>
License: MIT
License-File: LICENSE
Keywords: api,bulk-download,cli,data,museum
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: click>=8.2.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: requests>=2.32.4
Requires-Dist: rich>=14.1.0
Requires-Dist: zstandard>=0.23.0
Description-Content-Type: text/markdown

# MDS Exporter

A simple CLI tool, written in Python, to manage [Museum Data Service](https://museumdata.uk/) (MDS) resume API tokens and download data from the MDS API.

## Installation

The recommended way to install the tool is to use the `pipx` package manager. This will make the `mds` command available system-wide.

```bash
pipx install mds-exporter
```

It can also be installed to a specific environment:

```bash
pip install mds-exporter
```

## Usage

### Token Versions

Each stored token keeps track of three versions to help you pick up where you left off:

`base`: Your original starting token (never changes) - lets you restart the whole download from scratch if needed <br/>
`last`: Whatever token was used most recently - keeps track of where you are in any current download <br/>
`latest`: The token from your most complete download (the one that got the farthest) <br/>

This setup gives you options when things go wrong or go missing. You can always use `base` to redownload the whole dataset from the start. If a download gets interrupted, `last` lets you resume right where you stopped. And `latest` stays safe and untouched, so you can always go back to refreshing your best/most complete dataset without messing up your current download progress.


### Token Management

Store and manage MDS API tokens:

```bash
# Add a token with auto-generated name (e.g., "ancient-river")
mds token add YOUR_MDS_TOKEN

# Add a token with custom name
mds token add --name my-token YOUR_MDS_TOKEN

# List all stored tokens
mds token list

# Remove a token
mds token remove my-token
```

### Downloading Data

Download MDS data using stored tokens or direct tokens:

```bash
# Download using stored token (uses 'last' version by default)
mds download --name my-token

# Download using specific token version
mds download --name my-token:latest
mds download --name my-token:base

# Download using direct token
mds download --token YOUR_MDS_TOKEN

# Specify output file
mds download --name my-token --output my-data.jsonl

# Compress output using zstd (recommended for large datasets)
mds download --name my-token --compress --output my-data
```
