Metadata-Version: 2.1
Name: EVECelery
Version: 0.19
Summary: Task queue framework for building tools that interact with the EVE Online ESI API using Celery, RabbitMQ, and Redis.
Home-page: https://github.com/NullsecSpace/EVECelery
Author-email: maintainers@nullsec.space
License: MIT License
Project-URL: Documentation, https://EVECelery.nullsec.space
Project-URL: Source, https://github.com/NullsecSpace/EVECelery
Project-URL: Tracker, https://github.com/NullsecSpace/EVECelery/issues
Keywords: eve online rabbitmq esi redis message queue broker
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Games/Entertainment
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Celery (~=5.2)
Requires-Dist: pika (~=1.3)
Requires-Dist: python-dateutil (~=2.8.2)
Requires-Dist: redis (~=4.1)
Requires-Dist: requests (~=2.27)
Requires-Dist: pydantic (~=1.10)

# EVECelery
[![PyPI](https://img.shields.io/pypi/v/EVECelery)](https://pypi.org/project/EVECelery)
[![Documentation Status](https://readthedocs.org/projects/evecelery/badge/?version=latest)](https://evecelery.nullsec.space/en/latest/?badge=latest)
[![EVECelery](https://github.com/NullsecSpace/EVECelery/actions/workflows/github-actions.yml/badge.svg)](https://github.com/NullsecSpace/EVECelery/actions/workflows/github-actions.yml)
[![GitHub](https://img.shields.io/github/license/NullsecSpace/EVECelery)](https://github.com/NullsecSpace/EVECelery/blob/main/LICENSE)

EVECelery is a distributed task queue framework for building tools that interact with the [EVE Online ESI API](https://esi.evetech.net/ui) using Celery, RabbitMQ, and Redis.

With EVECelery you can easily distribute ESI calls across task queues built on top of [Celery](https://docs.celeryq.dev/) with a fleet of worker nodes.
You can build on top of EVECelery to create your own tools defining custom tasks and scheduled jobs.

NOTE: This software is in development and may rapidly change or have breaking bugs until the v1.0 release is ready.
Ensure you use version pinning in your ```requirements.txt```.

# Installation
```
pip install EVECelery
```

# Requirements
EVECelery requires RabbitMQ for the message broker service and Redis for distributed locks, cache, and Celery's result backend (fetching the result of completed tasks).

Deploying these two servers through the official Docker images for [RabbitMQ](https://hub.docker.com/_/rabbitmq) and [Redis](https://hub.docker.com/_/redis) is recommended.

# Quickstart and Usage
EVECelery has two components:
* Celery Worker - The Celery worker server that processes tasks from the message broker and makes requests to ESI on behalf of the client applications 
* Task api - Collection of Celery tasks to make ESI requests from your client application

You can deploy multiple worker servers that process tasks in the message queues. These worker nodes share locks, error limiting info, and cache requests for clients.
From your application you make requests using the task api.


## Starting the Celery Worker
You can start the worker server from either the CLI or your own Python script.
It is recommended to use the CLI unless you plan on registering your own tasks to the celery worker.

### From CLI

Ensure the following environmental variables are set and run the application via bash:
* EVECelery_RabbitMQ_User
* EVECelery_RabbitMQ_Password
* EVECelery_RabbitMQ_Host
* EVECelery_RabbitMQ_Port
* EVECelery_RabbitMQ_Vhost
* EVECelery_Redis_ResultBackend_User
* EVECelery_Redis_ResultBackend_Password
* EVECelery_Redis_ResultBackend_Host
* EVECelery_Redis_ResultBackend_Port
* EVECelery_Redis_ResultBackend_DB

```shell
$ eve-celery
```

### From your code
You can also start the worker from a Python script if you don't want to set environmental variables.

```python
from EVECelery.CeleryApps import CeleryWorker

c = CeleryWorker(broker_user="user", broker_password="pass", broker_host="host", broker_port=5672, broker_vhost="esi",
                 result_user="user", result_password="pass", result_host="host", result_port=6379, result_db=0)

c.start()
```

## Using the task API from your code
From another Python script you can send tasks to the queues and receive results:

```python
from EVECelery.CeleryApps import CeleryWorker
from EVECelery.tasks.Universe import SystemInfo

# only need to make one CeleryWorker in our code to init the tasks and setup connections to RabbitMQ and Redis
# by not passing connection params to CeleryWorker() the connection info will be read from environmental variables
c = CeleryWorker()

# note we don't call c.start() here as this is not a worker node script.
# we are calling the task api to submit requests to the message queue which run on the Celery worker nodes

r = SystemInfo().get_sync(timeout=5, system_id=30000142)
# r is a response dictionary containing system info obtained from ESI.
# subsequent calls for the same system ID will return results from the cache regardless of requesting client
```

# Copyright Notice

See [CCP.md](https://github.com/NullsecSpace/EVECelery/blob/main/CCP.md)

