Metadata-Version: 2.4
Name: cauli
Version: 0.1.0
Summary: Python client for cauli, a Rust background worker runtime for Python task queues
Author: the cauli contributors
License: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/bilalwork31-cyber/Cauli
Project-URL: Repository, https://github.com/bilalwork31-cyber/Cauli
Project-URL: Issues, https://github.com/bilalwork31-cyber/Cauli/issues
Keywords: task-queue,background-jobs,redis,worker,async
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Requires-Dist: redis>=5
Requires-Dist: msgspec>=0.18
Requires-Dist: tzdata
Requires-Dist: cauli-worker==0.1.0; sys_platform == "linux" and platform_python_implementation == "CPython" and (platform_machine == "x86_64" or platform_machine == "aarch64") and python_version < "3.15"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: django
Requires-Dist: django>=4.2; extra == "django"
Provides-Extra: speed
Dynamic: license-file

# cauli (Python client)

Python client for **cauli**, a Rust background worker runtime for Python task queues.
Define tasks in Python, enqueue from any web framework, execute on the Rust worker.

## Install

    pip install cauli               # Python >= 3.10 (deps: redis>=5, msgspec)

That also installs the `cauli-worker` binary, but only where its wheels exist:
Linux (glibc) on x86_64 or aarch64, CPython 3.10 through 3.14. Anywhere else, a
macOS laptop, Windows, PyPy, a CPython newer than the release matrix, the worker
requirement is dropped rather than failing the install: the client still lands
and enqueueing still works, there is simply no `cauli-worker` to run. Two
targets fail the install instead, because no marker can describe them: musl
(Alpine) and the free threaded build. For those, and for enqueue only web dynos
that never run a worker, see `PROTOCOL.md` section 13.4.

## Define an app and tasks (myproj/tasks.py)

    from cauli import Cauli

    app = Cauli(redis_url="redis://localhost:6379/0", default_queue="default")

    @app.task()
    async def send_email(to: str) -> str:
        ...                      # io task: runs on the worker's asyncio loop
        return "sent"

    @app.task(kind="cpu", timeout=120, soft_timeout=60, max_retries=5)
    def crunch(n: int) -> int:   # cpu task: runs in a child Python process
        return sum(i * i for i in range(n))

## Enqueue from Django, FastAPI, or Flask

    from myproj.tasks import send_email

    r = send_email.delay("a@b.com")
    r = send_email.apply_async(args=("a@b.com",), countdown=30, queue="emails",
                               idempotency_key="welcome:a@b.com")
    r.status()           # "pending" | "success" | "failure" | "duplicate" | "expired"
    r.get(timeout=10)    # value on success; raises TaskFailedError / TimeoutError

Tasks stay directly callable for tests: `crunch(10)` runs inline, no broker needed.

## Run the worker (Rust binary)

    cauli-worker -A myproj.tasks:app -c 50 -Q default,emails

The URL falls back to env `CAULI_REDIS_URL`, then `redis://localhost:6379/0`.
See `PROTOCOL.md` in the repo root for the full wire contract.
