Metadata-Version: 2.3
Name: edwh-gokapi-plugin
Version: 0.1.0
Summary: `edwh` plugin for gokapi.edwh.nl
Keywords: 
Author: Remco Boerma, Robin van der Noord
Author-email: Remco Boerma <remco.b@educationwarehouse.nl>, Robin van der Noord <robin.vdn@educationwarehouse.nl>
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: httpx2
Requires-Dist: rich
Requires-Dist: progress
Requires-Dist: pwinput
Requires-Dist: threadful
Requires-Dist: termcolor
Requires-Dist: edwh[test] ; extra == 'dev'
Requires-Python: >=3.11
Project-URL: Documentation, https://github.com/educationwarehouse/edwh-gokapi-plugin#readme
Project-URL: Issues, https://github.com/educationwarehouse/edwh-gokapi-plugin/issues
Project-URL: Source, https://github.com/educationwarehouse/edwh-gokapi-plugin
Provides-Extra: dev
Description-Content-Type: text/markdown

# edwh-gokapi-plugin

[![PyPI - Version](https://img.shields.io/pypi/v/edwh-gokapi-plugin.svg)](https://pypi.org/project/edwh-gokapi-plugin)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/edwh-gokapi-plugin.svg)](https://pypi.org/project/edwh-gokapi-plugin)

`edwh` plugin to share files via [Gokapi](https://github.com/Forceu/Gokapi) (`gokapi.edwh.nl` by default).
The commands mirror those of [`edwh-files-plugin`](https://github.com/educationwarehouse/edwh-files-plugin).

-----

**Table of Contents**

- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Development](#development)
- [License](#license)

## Installation

```console
pip install edwh-gokapi-plugin
```

Or inject it into an existing `uvenv` installation of `edwh`:

```console
uvenv inject edwh edwh-gokapi-plugin
```

Requires Gokapi 2.0 or newer on the server.

## Configuration

Most commands need a Gokapi API key. Create one in the Gokapi admin interface (`/apiKeys`) with the permissions
you need (upload, view, download, delete) and store it with:

```bash
edwh gokapi.login [--server <url>] [--new]
```

The key is stored as `GOKAPI_API_KEY` in `~/.config/edwh/.env`. A non-default server is stored as `GOKAPI_SERVER`.
Both can also be set as environment variables, which take precedence over the file.

## Usage

(Arguments between `< >` are required, arguments between `[ ]` are optional)

Every command accepts `--server [str]` to use another Gokapi instance than the configured one.
Wherever a file is expected, both its id (`oNleRD3pUZgaDKn`) and its download url
(`https://gokapi.edwh.nl/d?id=oNleRD3pUZgaDKn`) work.

### Upload

```bash
edwh gokapi.upload <path> --max-downloads [int] --max-days [int] --password [str] --rename [str] --compression [str] --compression-level [int]
```

- `path`: which file or directory to upload
- `max-downloads`: how often can the file be downloaded? (server default: 1, `0` = unlimited)
- `max-days`: for how long can the file be downloaded? (server default: 14, `0` = unlimited)
- `password`: password required to download the file via its public url.
  Note: unlike `file.upload --encrypt`, the file itself is not encrypted.
- `rename`: upload with a different filename
- `compression`: `auto` (default), `gzip`, `zip` or `none`.
  Files are uploaded as-is unless a method is chosen; directories are always archived
  (`auto` tries pigz, gzip, then zip; `none` creates a plain `.tar`).
- `compression-level`: 1 (fastest) - 9 (smallest)

Files are uploaded in chunks (like the Gokapi web interface does), so large files also work behind a reverse proxy
that limits the request size.
This command outputs the same JSON as `file.upload`: the status code, download url, the value to delete it with (the
file id) and the commands to download or delete it.

### Download

```bash
edwh gokapi.download <id_or_url> --output-file [str] --unpack
```

- `id_or_url`: file id or download url from `gokapi.upload` or `gokapi.list`
- `output-file`: where to store the download (default: original filename in the current directory)
- `unpack`: unpack the archive, removing it afterwards

With an API key the file is downloaded via the API, which counts towards `--max-downloads`.
Without one, the public url is used, which only works for files without a password.

### Delete

```bash
edwh gokapi.delete <id_or_url> --delay [int] --quiet
```

- `delay`: wait this many seconds before actually deleting the file

### List

```bash
edwh gokapi.list [--json]
```

Shows all files that are currently available, with their id, size, remaining downloads, expiry and url.
Use `--json` for the complete file metadata as a JSON array, sorted by upload date. An empty list is output as `[]`.

### Temporary upload

```bash
edwh gokapi.tmp <path> --password [str] --compression [str] --compression-level [int]
```

Uploads a file (max 2 downloads, 1 day) and deletes it as soon as you press enter or ctrl-c.

### Unpack

```bash
edwh gokapi.unpack <filename> --remove
```

## Development

```bash
uv venv venv && source venv/bin/activate
uv pip install -e .[dev]
edwh test.run   # pytest with coverage; tests/test_compression.py is slow (1GB files)
edwh fmt lint
```

Releases are made with [vommit](https://pypi.org/project/vommit/), configured under `[tool.vommit]` in `pyproject.toml`.

## License

`edwh-gokapi-plugin` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
