Metadata-Version: 2.4
Name: zimerate
Version: 0.1.0
Summary: A ZIM file reader for the terminal
Author-email: Skylar Gallup <me@skyebound.gay>
License-Expression: MIT
Project-URL: Homepage, https://git.skyebound.gay/skylar/zimerate
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Zimerate

Zimerate is a ZIM file reader for the terminal. This project is designed to allow users of terminal-only systems to quickly search through Wikipedia and other archives [from Kiwix](https://get.kiwix.org/en/solutions/catalog/) or elsewhere.


## Installation

To run from source on Linux-based systems:

```bash
# Clone the repository
git clone https://git.skyebound.gay/skylar/zimerate.git
cd zimerate

# Optional (but recommended): Create a virtual environment to store packages
python -m venv .env
source .env/bin/activate
# (end optional)

# Install required dependencies
python -m pip install -r requirements.txt

# Optional: Install Xapian to enable better full-text search.
# Zimerate is usable without this; the underlying python-zim library will fall back to title-only search.
# However, title-only search is less featureful and is **case-sensitive**.
apt install -y libxapian30
python -m pip install xapian-bindings  # TODO: Document how this works better after doing some testing
# (end optional)

# Run project (see below for detailed help info)
python src/zimerate.py <ZIM file> <query>
```


## Usage

```
zimerate [-h] [-f {markdown,html}] [-v] filename query

positional arguments:
  filename              The path to the ZIM file to read.
  query                 A query to search the ZIM file for. This is case-sensitive if the Xapian
                        search library is not installed.

options:
  -h, --help            show this help message and exit
  -f {markdown,html}, --format {markdown,html}
                        The format to return data in. Defaults to Markdown if not specified.
  -v, --verbose         Makes zimerate verbose during the operation to assist with debugging.
```

### Examples

```bash
# Search for a term in a Wikipedia ZIM file
zimerate path/to/wikipedia.zim Apple
```


## License and acknowledgements

All code is licensed under the [MIT License](./LICENSE).

Zimerate relies heavily on the work of the [`pyzim` library](https://github.com/IMayBeABitShy/pyzim), which is also licensed under the [MIT license](https://raw.githubusercontent.com/IMayBeABitShy/pyzim/refs/heads/master/LICENSE). I thank the contributors of that library for their excellent Python implementation of the ZIM file format.
