3tears-scheduled-jobs

A generic, payload-agnostic, multipod-safe scheduled-jobs core. Every agent/skill/webhook/conversation-specific concept is stripped out, leaving only the scheduling machinery.

What it gives you:

  • scheduled_tick_job(...) -- one cross-pod-locked tick pump. Acquire the nats_distributed_lock at a caller-supplied key; on LockHeld skip silently; on KvError degrade open (the per-row optimistic-CAS is the real guard); sweep abandoned in-flight fires per kind group; enumerate due rows of the routed kinds; per-row CAS-claim + reschedule; invoke the handler registered for that row's kind; drift / missed-fire accounting; per-row failure isolation. Takes the store(s), a DispatchRoutes table, and the NATS client as parameters, with no domain knowledge.
  • Per-kind routing, and an unrouted kind is inert. The pump's kind -> handler table is matched EXACTLY -- no wildcard, no default handler, no fall-through -- and it also scopes the due-row scan (a SQL predicate, not a Python filter) and the reaper sweep. A row whose kind has no handler is refused with an unrouted_kind failure metric and an ERROR event, and is deliberately not claimed, so the occurrence survives until its handler is registered. Silent misdelivery is the failure this prevents: a row absorbed by another kind's dispatcher does that dispatcher's work and records it as a success.
  • Per-kind reap thresholds. dispatch_reap_after_seconds_by_kind overrides DEFAULT_DISPATCH_REAP_AFTER_SECONDS per kind, so a kind whose work legitimately runs for hours is not reaped on the 15-minute baseline. Kinds sharing a threshold sweep in one query. Note the age is measured from dispatch start, not last activity, so the threshold alone only moves the false-reap cliff -- pair it with progress-conditioned renewal in the executor.
  • A distinct lock key per pump. JobConfig.tick_lock_key defaults to DEFAULT_TICK_LOCK_KEY; consumers running more than one pump in a process MUST vary it, or the pumps serialise against each other for no reason.
  • compute_next_fire_at(...) -- the pure reschedule math for every schedule type (daily_at, every_n_hours, random_within_window, one_shot_at, cron, relative_delay, interval) and both missed-fire policies (coalesce, catch_up). The cron branch imports APScheduler lazily, so non-cron consumers pay nothing.
  • ScheduleStore / FireStore Protocols -- the exact surface the tick engine calls. The engine depends only on these, so a typed consumer collection can implement them.
  • A default store -- ScheduledJobEntity / JobFireEntity + collections + scheduled_jobs / job_fires table factories + a v001 migration, keyed on an opaque kind (TEXT) + payload (JSONB). A simple consumer can use it as-is with no table of its own.
  • Generic config / events / metrics -- a JobConfig protocol, the tick / fire / drift event-name constants, and cardinality-bounded Prometheus instruments.

The engine is pure-async, one tick per call with no internal polling. Drive cadence with whatever scheduler you like (an APScheduler IntervalTrigger, a while True: await asyncio.sleep(...), and so on). The engine does not own the scheduler.

Project links

Data verified by PyPI on Aug 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.41.4)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for pace from gravatar.com pace

Credits

Author: pace

GitHub Statistics

Data verified by PyPI on Aug 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.14

Provides Extra

prometheus

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

3tears_scheduled_jobs-0.24.7.tar.gz (65.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

3tears_scheduled_jobs-0.24.7-py3-none-any.whl (50.9 kB view details)

Uploaded Python 3

File details

Details for the file 3tears_scheduled_jobs-0.24.7.tar.gz.

File metadata

  • Download URL: 3tears_scheduled_jobs-0.24.7.tar.gz
  • Upload date:
  • Size: 65.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for 3tears_scheduled_jobs-0.24.7.tar.gz
Algorithm Hash digest
SHA256 6d2af27df0a25e6c79b88758916eda108610bd975714de5718b4345973bd336b
MD5 e6e0534571c0c70365527de9416a35b6
BLAKE2b-256 c1fa20c9e2104cf1856fb4f9f49a54c3dce06ba20f8ed64c4268867f6416b948

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_scheduled_jobs-0.24.7.tar.gz:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file 3tears_scheduled_jobs-0.24.7-py3-none-any.whl.

File metadata

File hashes

Hashes for 3tears_scheduled_jobs-0.24.7-py3-none-any.whl
Algorithm Hash digest
SHA256 cb4677b066c3c52c9f92e7fff2f0242f405dd43ea645a22f134eec6d5d4bf42a
MD5 5e81550fd8463e903024d684fc4d0c16
BLAKE2b-256 0942bca8a5d368b4bfc05ad2861c613eaaeb3deb64e86d75beb7601012e34a21

See more details on using hashes here.

Provenance

The following attestation bundles were made for 3tears_scheduled_jobs-0.24.7-py3-none-any.whl:

Publisher: release.yml on pacepace/3tears

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.41.4

2 files

0.41.3

2 files

0.41.2

2 files

0.41.1

2 files

0.41.0

2 files

0.40.0

2 files

0.39.0

2 files

0.38.0

2 files

0.37.0

2 files

0.36.0

2 files

0.35.1

2 files

0.35.0

2 files

0.34.0

2 files

0.33.0

2 files

0.32.1

2 files

0.32.0

2 files

0.31.0

2 files

0.30.1

2 files

0.30.0

2 files

0.29.0

2 files

0.28.0

2 files

0.27.0

2 files

0.26.1

2 files

0.26.0

2 files

0.25.0

2 files

This release

0.24.7 This release

2 files

0.24.6

2 files

0.24.5

2 files

0.24.4

2 files

0.24.3

2 files

0.24.2

2 files

0.24.1

2 files

0.24.0

2 files

0.23.11

2 files

0.23.10

2 files

0.23.9

2 files

0.23.8

2 files

0.23.7

2 files

0.23.6

2 files

0.23.5

2 files

0.23.3

2 files

0.23.2

2 files

0.23.1

2 files

0.23.0

2 files

0.22.5

2 files

0.22.4

2 files

0.22.3

2 files

0.22.2

2 files

0.22.1

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.4

2 files

0.19.3

2 files

0.19.2

2 files

0.19.1

2 files

0.19.0

2 files

0.18.0

2 files

0.17.9

2 files

0.17.8

2 files

0.17.7

2 files

0.17.6

2 files

0.17.5

2 files

0.17.4

2 files

0.17.3

2 files

0.17.2

2 files

0.17.1

2 files

0.17.0

2 files

0.16.1

2 files

0.16.0

2 files

0.15.0

2 files

0.14.1

2 files

0.14.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page