Metadata-Version: 2.5
Name: z4j-hueyperiodic
Version: 1.13.0
Summary: z4j scheduler adapter for Huey @periodic_task (Apache 2.0)
Project-URL: Changelog, https://github.com/z4jdev/z4j-hueyperiodic/blob/main/CHANGELOG.md
Project-URL: Documentation, https://docs.z4j.com
Project-URL: Homepage, https://z4j.com
Project-URL: Issues, https://github.com/z4jdev/z4j-hueyperiodic/issues
Project-URL: Source, https://github.com/z4jdev/z4j-hueyperiodic
Author: z4j contributors
License: Apache-2.0
License-File: LICENSE
Keywords: huey,periodic,scheduler,z4j
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: huey>=2.4
Requires-Dist: z4j-core<2,>=1.13.0
Description-Content-Type: text/markdown

# z4j-hueyperiodic

The native Huey periodic adapter for [z4j](https://z4j.com), with dashboard management
of periodic schedules. Dashboard management needs the z4j server, `z4j-core`, `z4j-bare`
and this adapter from the same release, plus the producer setup below.

## Compatibility

Huey 2.4+ (Huey 2 and 3); Python 3.11+.

## Installation and producer setup

Install `z4j-hueyperiodic` and `z4j-bare` from the same release wave, plus the native
scheduler and broker/store dependencies used by your application. The example
assumes your task code, writable application-state directory and agent credentials
already exist. Use the project UUID from agent registration.

```python
import os
from myapp.tasks import huey  # Import all decorated tasks first; use utc=True.
from z4j_bare import NativeScheduleControl, install_agent
from z4j_hueyperiodic import HueyPeriodicAdapter

adapter = HueyPeriodicAdapter(
    huey=huey,
    control=NativeScheduleControl("/var/lib/myapp/huey-schedules.sqlite3"),
)
agent = install_agent(
    engines=[], schedulers=[adapter],
    brain_url=os.environ["Z4J_BRAIN_URL"], token=os.environ["Z4J_TOKEN"],
    hmac_secret=os.environ["Z4J_HMAC_SECRET"], project_id=os.environ["Z4J_PROJECT_ID"],
)
try:
    huey.create_consumer(periodic=True).run()
finally:
    agent.stop()
```

Construct the adapter in the actual periodic consumer process, before starting
that consumer. An agent in a separate web process cannot change the consumer's
in-memory registry. Without `control`, discovery and manual runs remain available
but dashboard definition changes are disabled.

## Dashboard controls

The connected producer supports inventory, create, edit, pause, resume, delete
and **Run now**. A write is complete only after z4j accepts a snapshot confirming
the native source. The dashboard uses the current connection's advertised
capabilities; an unavailable producer cannot accept new edits. Repeating an
operation ID does not submit it twice. A timeout or uncertain outcome requires
inspection before submitting a new request.

A pause prevents future scheduling. Work already queued or running can finish.
Run now submits an additional execution without resuming a paused schedule.
Native scheduling keeps the upstream scheduler's timing and delivery semantics;
it does not acquire z4j-scheduler's catch-up, overlap or exactly-once guarantees.
Queue task history requires the corresponding engine adapter in the workers.

## Code definitions and durable overrides

`NativeScheduleControl` stores dashboard changes in a private SQLite file in
the producer's application state directory. Keep that file on a durable local
volume, back it up with the application, and reuse the same path after restart.
Use a separate file for each application and scheduler owner. Do not put it on
an ephemeral container filesystem or a network filesystem.

Code supplies the initial definitions. Each saved change overrides the fields
it submits: pause and resume submit only the enabled flag, while the dashboard
edit form submits every editable field (task, schedule type, expression,
timezone, queue, arguments and enabled flag), so later code changes to those
fields stay hidden. Removing a code definition removes its projection;
reintroducing the same source identity restores any saved override. Deletion is
a durable tombstone, so restarting the application does not recreate it.
Dashboard-created schedules survive with the same file. No Python files are
rewritten. New schedules can invoke only tasks already registered in the host
application; deploying new task code remains an application operation.

The producer reads committed controls locally and keeps scheduling during a
z4j server outage. If that local state cannot be read or validated, periodic
dispatch is withheld and the error is logged. Normal task processing continues.
Install control before starting periodic dispatch. Keep one periodic producer
per application, as required by its native scheduler. There is currently no
separate dashboard action to remove an override and restore the code default.

## Supported definitions and limits

- Supported definitions use Huey's `crontab(...)` validator, with five numeric cron fields, UTC and the application's configured Huey queue.
- Custom Python datetime predicates are not serializable cron definitions; managed startup rejects them before replacing the producer hook.
- Registered ordinary Huey tasks can also receive dashboard-created periodic schedules.
- Cron uses Huey's weekday convention, Sunday=0 or 7. Periodic dispatch is minute-granular.

## Links

- [Documentation](https://docs.z4j.com/schedulers/huey-periodic/)
- [Changelog](https://github.com/z4jdev/z4j-hueyperiodic/blob/main/CHANGELOG.md)
- [Security policy](https://github.com/z4jdev/z4j-hueyperiodic/blob/main/SECURITY.md); report vulnerabilities to security@z4j.com
- [Apache-2.0 license](https://github.com/z4jdev/z4j-hueyperiodic/blob/main/LICENSE)
