<!--
SPDX-FileCopyrightText: © 2026 scy

SPDX-License-Identifier: MIT
-->

# evel

_A simple library for pub/sub-style events._

➡️ **Quick Links:** [Repository](https://codeberg.org/scy/evel) · [Issues](https://codeberg.org/scy/evel/issues)

evel is pronounced _ee-VELL,_ basically like "event" but with and L instead of NT.


## 🌱 Status

evel is pretty new and still under development.
The API is not yet stable and **will** change.
If you're using it in one of your projects, make sure to pin the version.

### Drivers

The idea is that evel is going to support multiple pub/sub implementations under a single API at some point.
We're not there yet.

These are the planned and implemented drivers:

- [x] [Python asyncio queues](https://docs.python.org/3/library/asyncio-queue.html) (no external dependencies, single thread only)
- [ ] [Valkey Pub/Sub](https://valkey.io/topics/pubsub/) (using a Valkey server)
- [ ] [MQTT](https://en.wikipedia.org/wiki/MQTT) (using an MQTT server)


## 📚 Documentation

There's no documentation yet, but you can have a look at the `test_two_topics` function in [the asyncio queue tests](tests/test_async_queue.py) to get an idea.


## 🗃️ Installation

Simply install the `evel` package from PyPI via your preferred package manager.

For example, to add it as a dependency to your [uv](https://docs.astral.sh/uv/)-managed project, use this:

```sh
uv add evel
```


## 🧑‍💻 Development

### Preparation

We're using [uv](https://docs.astral.sh/uv/) to manage this project and its dependencies.
After cloning the repository using Git, a simple `uv sync` should get everything you need.

```sh
git clone https://codeberg.org/scy/evel.git evel
cd evel
uv sync
```

### direnv

We recommend using [direnv](https://direnv.net/) to add installed dependencies to your `$PATH`, so that you don't need to prepend `uv run` to every command.
For example, after installing direnv, you can use `direnv edit` in this repository's directory and add the following line:

```sh
PATH_add .venv/bin
```

**The rest of this readme assumes that you have `.venv/bin` in your `$PATH`.**

### EditorConfig

Make sure your editor or IDE supports the [EditorConfig](https://editorconfig.org/) standard, so that your code adheres to the project's [preferred](.editorconfig) indentation, line lengths, etc.

### Makefile

There is a [`Makefile`](Makefile) that contains frequently used commands to speed up development, but it's optional to use.
The following targets exist:

- `fmt`: Use [Ruff](https://docs.astral.sh/ruff/) to format and lint the code.
- `qa`: Use [mypy](https://mypy.readthedocs.io/) for static type analysis.
- `reuse`: Use [`reuse lint`](https://codeberg.org/fsfe/reuse-tool) to make sure every file contains licensing information.
- `test`: Use [pytest](https://pytest.org/) for automated testing and code coverage.
- `noqa`: Add `noqa` statements to ignore everything Ruff complains about. Only use this after fixing everything that needs fixing.

`make all`, or simply `make`, will run `fmt`, `qa`, `reuse`, and `test`.
You should do this before every commit and fix all issues that are reported.


## 📃 License

This project is licensed under the terms of the [MIT License](https://spdx.org/licenses/MIT.html).

The project also conforms to the [REUSE Specification, version 3.3](https://reuse.software/spec-3.3/).
You can use [the `reuse` tool](https://codeberg.org/fsfe/reuse-tool) to interpret the machine-readable licensing information.
