Metadata-Version: 2.3
Name: ziphttpd
Version: 1.1.0
Summary: Serve the contents of a Zip file over HTTP.
Author: Benoit Hamelin
Author-email: Benoit Hamelin <benoit@benoithamelin.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# ziphttpd: serve Zip files over HTTP

This runs a small web server that serves the contents of a Zip file.
URLs mapping to directories within the Zip files are mapped to the `index.html`
file if the directory contains it,
otherwise it generates (very bare) listing of the directory.

## Install

```sh
pip install ziphttpd
```

## Example uses

```sh
ziphttpd archive.zip
```

Serves the contents of `archive.zip` over an automatically-selected ephemeral port,
over the loopback interface (`localhost`).

```sh
ziphttpd -p 18888 archive.zip
```

Serves the file over the loopback interface, at port 18888.

```sh
ziphttpd -b 192.168.1.45 -p 18888 archive.zip
```

Serves the file over one's a network-exposed interface associated to one's
IP address, port 18888.

```sh
python -m ziphttpd -B -b "" -p 18888 archive.zip
```

Serves over all of the host's network interfaces, port 18888, and skips starting
a the host's web browser to `http://0.0.0.0:18888/`
(path `/` at the server's location).
Notice how one can use `python -m ziphttpd` as an alternative to short-form entry point.

## Command line arguments

Command line schema:

```sh
ziphttpd [options] ZIPFILE
```

| Argument | Description | Example |
|----------|-------------|---------|
| `ZIPFILE`                           | The file whose contents to distribute with this server.      | `myfile.zip` |
| `-b ADDRESS`<br>`--address ADDRESS` | Address to the IP interface to which the server should bind. | `localhost`<br>`10.2.1.18`<br>`0.0.0.0` (all interfaces bound) |
| `-p PORT`<br>`--port PORT`          | Port to which to bind the server.                            | `10080`<br>`80` (careful with [privileged ports](https://www.baeldung.com/linux/bind-process-privileged-port))<br>`0` (autochoose an ephemeral port) |
| `-B`<br>`--no-browser`              | By default, once the web server is set up, Ziphttpd opens a web browser tab to the server's URL on the host. This option omits this browser action. | |
| `-v`<br>`--verbose`                 | Increases the verbosity level of the server log. Use twice for debugging trace. | |

## In the wild...

### Interactive standalone data maps generated using [DataMapPlot](https://datamapplot.readthedocs.io/en/latest/intro_splash.html#interactive-plot-examples)

The [DataMapPlot](https://github.com/TutteInstitute/datamapplot) Python package,
made by the Tutte Institute,
enables the production of standalone [interactive viewers](https://datamapplot.readthedocs.io/en/latest/interactive_intro.html)
for data embedded into vector spaces.
These small web apps can be [saved to Zip files](https://datamapplot.readthedocs.io/en/latest/interactive_customization_options.html)
for sharing.
When downloaded to your own computer,
use ziphttpd to view them.
(The following example is slightly contrived,
but it does demonstrate the composition satisfyingly.)

```sh
curl -L -o datamapplot_examples.zip https://github.com/lmcinnes/datamapplot_examples/archive/refs/heads/master.zip
ziphttpd datamapplot_examples.zip
```

Then browse through `datamapplot_examples` and `arXiv` to enjoy an interactive
 map of some 2.6 million papers made available on ArXiV between 1996 and January 2025.
