Oraculum

Data parser for Fedora Packager Dashboard.

Handles caching and querying resources from multiple services like Bodhi, Pagure (dist-git) and many more.

Requirements

• Python 3.12+
• uv
• Redis (for Celery)

Installation

Clone this repo, change to its directory, install dependencies:

git clone https://forge.fedoraproject.org/apps/oraculum.git && cd oraculum
sudo dnf install redis                # or: sudo apt install redis-server
uv sync

Running Locally

1. Start the Development Server: In your terminal, start the development server (applies database migrations, starts Redis, Celery workers, and Flask):

   uv run oraculum dev
   

2. Populate Initial Cache (First Run Only): On a fresh setup, open a second terminal window and run an immediate initial sync:

   uv run oraculum cache-recreate
   

Note

cache-recreate is only required on your initial setup or after resetting your local database. For routine daily development, running uv run oraculum dev is sufficient as background Celery workers automatically refresh the cache.

Dependency Management

This project uses uv for local dependency management, while generating a standard requirements.txt specifically for the OpenShift S2I production build.

To add, remove, or upgrade a dependency:

1. Update pyproject.toml (or use uv add <package>).
2. Run uv sync to resolve dependencies, update uv.lock, and sync your local .venv.
3. Run make prod-build to export the strictly pinned requirements.txt.

Important: You must commit both uv.lock and requirements.txt when making dependency changes. This guarantees that local development and the OpenShift production environment both receive the exact same reproducible builds.

Code Quality & Testing

• Format code:

  uv run ruff format .
  

• Lint code:

  uv run ruff check .
  

• Fix auto-fixable lint issues:

  uv run ruff check --fix .
  

• Run tests:

  uv run pytest
  

Pre-commit Hooks (Optional)

To automatically format and lint staged files before every git commit:

uv run pre-commit install