asyncz 0.14.2__tar.gz → 0.15.0__tar.gz

{asyncz-0.14.2 → asyncz-0.15.0}/.gitignore

@@ -3,8 +3,8 @@
 *.sqlite3
 .hypothesis/
 .idea/
-.mypy_cache/
 .pytest_cache/
+.ruff_cache/
 .scannerwork/
 .tox/
 .venv/
@@ -26,3 +26,4 @@ target/
 .coverage
 .python-version
 coverage.*
+docs/generated

asyncz-0.15.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: asyncz
+Version: 0.15.0
+Summary: The scheduler that nobody wants but every application needs.
+Project-URL: Homepage, https://github.com/dymmond/asyncz
+Project-URL: Documentation, https://asyncz.dymmond.com/
+Project-URL: Changelog, https://asyncz.dymmond.com/release-notes/
+Project-URL: Funding, https://github.com/sponsors/tarsil
+Project-URL: Source, https://github.com/dymmond/asyncz
+Author-email: Tiago Silva <tiago.arasilva@gmail.com>
+License-File: LICENSE
+Keywords: apscheduler,asgi,asyncz,cron,fastapi,framework,pydantic,scheduler,starlette
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AnyIO
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Internet
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography
+Requires-Dist: monkay>=0.5.0
+Requires-Dist: pydantic<3.0.0,>=2.5.3
+Requires-Dist: sayer>=0.7.4
+Provides-Extra: dashboard
+Requires-Dist: lilya[standard]>=0.22.15; extra == 'dashboard'
+Provides-Extra: docs
+Requires-Dist: griffe-typingdoc<1.0,>=0.2.2; extra == 'docs'
+Requires-Dist: mkdocs-meta-descriptions-plugin>=2.3.0; extra == 'docs'
+Requires-Dist: mkdocstrings-python>=2.0.3; extra == 'docs'
+Requires-Dist: mkdocstrings>=0.28.3; extra == 'docs'
+Requires-Dist: pyyaml<7.0.0,>=6.0; extra == 'docs'
+Requires-Dist: sayer>=0.7.4; extra == 'docs'
+Requires-Dist: typing-extensions>=3.10.0; extra == 'docs'
+Requires-Dist: zensical<0.1.0,>=0.0.23; extra == 'docs'
+Provides-Extra: localtime
+Requires-Dist: tzlocal; extra == 'localtime'
+Provides-Extra: testing
+Requires-Dist: freezegun; extra == 'testing'
+Requires-Dist: httpx; extra == 'testing'
+Requires-Dist: ipdb; extra == 'testing'
+Requires-Dist: lilya[standard]>=0.22.15; extra == 'testing'
+Requires-Dist: pymongo<5.0.0,>=4.3.3; extra == 'testing'
+Requires-Dist: pytest-asyncio<2.0.0,>=1.0; extra == 'testing'
+Requires-Dist: pytest-cov<8.0.0,>=2.12.0; extra == 'testing'
+Requires-Dist: pytest<10.0.0,>=7.1.3; extra == 'testing'
+Requires-Dist: pytz>=2022.6; extra == 'testing'
+Requires-Dist: ravyn>=0.3.7; extra == 'testing'
+Requires-Dist: redis<8.0.0,>=4.4.0; extra == 'testing'
+Requires-Dist: sqlalchemy; extra == 'testing'
+Requires-Dist: starlette; extra == 'testing'
+Requires-Dist: ty; extra == 'testing'
+Requires-Dist: tzlocal; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# Asyncz
+
+<p align="center">
+  <a href="https://asyncz.tarsil.io"><img src="https://res.cloudinary.com/tarsild/image/upload/v1687363326/packages/asyncz/asyncz-new_wiyih8.png" alt='Asyncz'></a>
+</p>
+
+<p align="center">
+    <em>🚀 The scheduler that simply works. 🚀</em>
+</p>
+
+<p align="center">
+<a href="https://github.com/dymmond/asyncz/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" target="_blank">
+    <img src="https://github.com/dymmond/asyncz/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" alt="Test Suite">
+</a>
+
+<a href="https://pypi.org/project/asyncz" target="_blank">
+    <img src="https://img.shields.io/pypi/v/asyncz?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+
+<a href="https://pypi.org/project/asyncz" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/asyncz.svg?color=%2334D058" alt="Supported Python versions">
+</a>
+</p>
+
+---
+
+**Documentation**: [https://asyncz.dymmond.com](https://asyncz.dymmond.com) 📚
+
+**Source Code**: [https://github.com/dymmond/asyncz](https://github.com/dymmond/asyncz)
+
+---
+
+Asyncz is an async-first scheduler for Python applications and ASGI services. It wraps the core APScheduler model in a codebase that is focused on `asyncio`, explicit task objects, pluggable stores and executors, and framework-friendly lifecycle integration.
+
+Documentation: [https://asyncz.dymmond.com](https://asyncz.dymmond.com)
+
+## Highlights
+
+- `AsyncIOScheduler` and `NativeAsyncIOScheduler` for async runtimes.
+- Built-in triggers for `date`, `interval`, `cron`, `and`, `or`, and `shutdown`.
+- Built-in stores for `memory`, `file`, `mongodb`, `redis`, and `sqlalchemy`.
+- Executors for in-event-loop work, thread pools, process pools, and direct debug execution.
+- CLI commands for starting schedulers and managing persisted tasks.
+- Task inspection snapshots and filtered task queries for dashboards, CLIs, and admin tooling.
+- Optional dashboard UI for browsing tasks, filtering by schedule metadata, and viewing captured logs.
+- Standard-library logging throughout the project.
+
+## Installation
+
+```bash
+pip install asyncz
+```
+
+Useful extras:
+
+```bash
+pip install "asyncz[dashboard]"
+pip install "asyncz[localtime]"
+```
+
+## Quick start
+
+```python
+import logging
+
+from asyncz.schedulers import AsyncIOScheduler
+
+logging.basicConfig(level=logging.INFO)
+
+scheduler = AsyncIOScheduler()
+
+
+def cleanup() -> None:
+    logging.getLogger(__name__).info("cleanup finished")
+
+
+scheduler.add_task(cleanup, "interval", minutes=5, id="cleanup-task")
+scheduler.start()
+```
+
+## Core concepts
+
+Asyncz is built around four main component types:
+
+- [Schedulers](https://asyncz.dymmond.com/schedulers/)
+- [Triggers](https://asyncz.dymmond.com/triggers/)
+- [Stores](https://asyncz.dymmond.com/stores/)
+- [Executors](https://asyncz.dymmond.com/executors/)
+
+Tasks are the public unit of scheduling. A task combines a callable, a trigger, an executor alias, and the metadata needed to persist and reschedule it correctly.
+
+## Logging
+
+Asyncz uses Python's built-in `logging` module. The default logger namespaces are:
+
+- `asyncz.schedulers`
+- `asyncz.executors.<alias>`
+- `asyncz.stores.<alias>`
+
+If you need custom logger creation, pass your own `loggers_class` to the scheduler. That class only needs to implement the same dictionary-like contract used by `ClassicLogging`.
+
+## ASGI integration
+
+Asyncz can wrap an ASGI app directly:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+scheduler = AsyncIOScheduler()
+application = scheduler.asgi(application)
+```
+
+Or you can wire startup and shutdown hooks manually:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+scheduler = AsyncIOScheduler()
+
+app = Lilya(
+    routes=[...],
+    on_startup=[scheduler.start],
+    on_shutdown=[scheduler.shutdown],
+)
+```
+
+The scheduler also supports synchronous and asynchronous context managers, which makes it easy to use inside lifespan handlers.
+
+## Persistent stores and encryption
+
+The default store is in-memory. For durable scheduling, configure a file, MongoDB, Redis, or SQLAlchemy store.
+
+Persistent stores support the `ASYNCZ_STORE_ENCRYPTION_KEY` environment variable. When it is set, task payloads are encrypted before they are written to the backing store.
+
+## CLI and dashboard
+
+Asyncz ships with:
+
+- a CLI for `start`, `add`, `list`, `run`, `pause`, `resume`, and `remove`
+- a Lilya-based dashboard with task controls, task filters, and a log viewer
+
+See the documentation for usage details:
+
+- [CLI guide](https://asyncz.dymmond.com/cli/)
+- [Dashboard guide](https://asyncz.dymmond.com/dashboard/dashboard/)

asyncz-0.15.0/README.md

@@ -0,0 +1,145 @@
+# Asyncz
+
+<p align="center">
+  <a href="https://asyncz.tarsil.io"><img src="https://res.cloudinary.com/tarsild/image/upload/v1687363326/packages/asyncz/asyncz-new_wiyih8.png" alt='Asyncz'></a>
+</p>
+
+<p align="center">
+    <em>🚀 The scheduler that simply works. 🚀</em>
+</p>
+
+<p align="center">
+<a href="https://github.com/dymmond/asyncz/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" target="_blank">
+    <img src="https://github.com/dymmond/asyncz/actions/workflows/test-suite.yml/badge.svg?event=push&branch=main" alt="Test Suite">
+</a>
+
+<a href="https://pypi.org/project/asyncz" target="_blank">
+    <img src="https://img.shields.io/pypi/v/asyncz?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+
+<a href="https://pypi.org/project/asyncz" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/asyncz.svg?color=%2334D058" alt="Supported Python versions">
+</a>
+</p>
+
+---
+
+**Documentation**: [https://asyncz.dymmond.com](https://asyncz.dymmond.com) 📚
+
+**Source Code**: [https://github.com/dymmond/asyncz](https://github.com/dymmond/asyncz)
+
+---
+
+Asyncz is an async-first scheduler for Python applications and ASGI services. It wraps the core APScheduler model in a codebase that is focused on `asyncio`, explicit task objects, pluggable stores and executors, and framework-friendly lifecycle integration.
+
+Documentation: [https://asyncz.dymmond.com](https://asyncz.dymmond.com)
+
+## Highlights
+
+- `AsyncIOScheduler` and `NativeAsyncIOScheduler` for async runtimes.
+- Built-in triggers for `date`, `interval`, `cron`, `and`, `or`, and `shutdown`.
+- Built-in stores for `memory`, `file`, `mongodb`, `redis`, and `sqlalchemy`.
+- Executors for in-event-loop work, thread pools, process pools, and direct debug execution.
+- CLI commands for starting schedulers and managing persisted tasks.
+- Task inspection snapshots and filtered task queries for dashboards, CLIs, and admin tooling.
+- Optional dashboard UI for browsing tasks, filtering by schedule metadata, and viewing captured logs.
+- Standard-library logging throughout the project.
+
+## Installation
+
+```bash
+pip install asyncz
+```
+
+Useful extras:
+
+```bash
+pip install "asyncz[dashboard]"
+pip install "asyncz[localtime]"
+```
+
+## Quick start
+
+```python
+import logging
+
+from asyncz.schedulers import AsyncIOScheduler
+
+logging.basicConfig(level=logging.INFO)
+
+scheduler = AsyncIOScheduler()
+
+
+def cleanup() -> None:
+    logging.getLogger(__name__).info("cleanup finished")
+
+
+scheduler.add_task(cleanup, "interval", minutes=5, id="cleanup-task")
+scheduler.start()
+```
+
+## Core concepts
+
+Asyncz is built around four main component types:
+
+- [Schedulers](https://asyncz.dymmond.com/schedulers/)
+- [Triggers](https://asyncz.dymmond.com/triggers/)
+- [Stores](https://asyncz.dymmond.com/stores/)
+- [Executors](https://asyncz.dymmond.com/executors/)
+
+Tasks are the public unit of scheduling. A task combines a callable, a trigger, an executor alias, and the metadata needed to persist and reschedule it correctly.
+
+## Logging
+
+Asyncz uses Python's built-in `logging` module. The default logger namespaces are:
+
+- `asyncz.schedulers`
+- `asyncz.executors.<alias>`
+- `asyncz.stores.<alias>`
+
+If you need custom logger creation, pass your own `loggers_class` to the scheduler. That class only needs to implement the same dictionary-like contract used by `ClassicLogging`.
+
+## ASGI integration
+
+Asyncz can wrap an ASGI app directly:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+scheduler = AsyncIOScheduler()
+application = scheduler.asgi(application)
+```
+
+Or you can wire startup and shutdown hooks manually:
+
+```python
+from asyncz.schedulers import AsyncIOScheduler
+
+scheduler = AsyncIOScheduler()
+
+app = Lilya(
+    routes=[...],
+    on_startup=[scheduler.start],
+    on_shutdown=[scheduler.shutdown],
+)
+```
+
+The scheduler also supports synchronous and asynchronous context managers, which makes it easy to use inside lifespan handlers.
+
+## Persistent stores and encryption
+
+The default store is in-memory. For durable scheduling, configure a file, MongoDB, Redis, or SQLAlchemy store.
+
+Persistent stores support the `ASYNCZ_STORE_ENCRYPTION_KEY` environment variable. When it is set, task payloads are encrypted before they are written to the backing store.
+
+## CLI and dashboard
+
+Asyncz ships with:
+
+- a CLI for `start`, `add`, `list`, `run`, `pause`, `resume`, and `remove`
+- a Lilya-based dashboard with task controls, task filters, and a log viewer
+
+See the documentation for usage details:
+
+- [CLI guide](https://asyncz.dymmond.com/cli/)
+- [Dashboard guide](https://asyncz.dymmond.com/dashboard/dashboard/)

{asyncz-0.14.2 → asyncz-0.15.0}/asyncz/__init__.py

@@ -2,7 +2,7 @@ from typing import TYPE_CHECKING
 
 from .monkay import create_monkay
 
-__version__ = "0.14.2"
+__version__ = "0.15.0"
 
 if TYPE_CHECKING:
     from .conf import settings

{asyncz-0.14.2 → asyncz-0.15.0}/asyncz/cli/commands/list.py

@@ -8,12 +8,41 @@ from sayer import Option, command, info
 
 from asyncz.cli.bootstrap_loader import load_bootstrap_scheduler
 from asyncz.cli.utils import build_stores_map, ensure_loop, maybe_await
+from asyncz.enums import TaskScheduleState
 from asyncz.schedulers import AsyncIOScheduler
 
 
 @command(name="list")
 def list_jobs(
     as_json: Annotated[bool, Option(False, "--json", help="Output as JSON")],
+    state: Annotated[
+        str | None,
+        Option(None, "--state", help="Filter by task state: pending, paused, or scheduled."),
+    ],
+    executor: Annotated[
+        str | None,
+        Option(None, "--executor", help="Filter by executor alias."),
+    ],
+    trigger: Annotated[
+        str | None,
+        Option(None, "--trigger", help="Filter by trigger alias or trigger class name."),
+    ],
+    q: Annotated[
+        str | None,
+        Option(None, "--query", help="Case-insensitive free-text task search."),
+    ],
+    sort_by: Annotated[
+        str,
+        Option(
+            "next_run_time",
+            "--sort-by",
+            help="Sort by id, name, next_run_time, schedule_state, executor, store, or trigger.",
+        ),
+    ],
+    descending: Annotated[
+        bool,
+        Option(False, "--desc", help="Reverse the selected sort order."),
+    ],
     bootstrap: Annotated[
         str | None,
         Option(
@@ -35,6 +64,7 @@ def list_jobs(
         asyncz list
         asyncz list --store durable=sqlite:///scheduler.db
         asyncz list --json --store default=memory
+        asyncz list --state paused --sort-by name
         asyncz list --bootstrap ravyn.contrib.asyncz:AsynczSpec
     """
     loop = ensure_loop()
@@ -60,29 +90,50 @@ def list_jobs(
             await maybe_await(scheduler.start())
 
         try:
-            # 2) Fetch jobs
-            jobs = await maybe_await(scheduler.get_tasks())
+            # 2) Fetch task snapshots
+            schedule_state = (
+                TaskScheduleState(state.strip().lower()) if state is not None else None
+            )
+            infos = await maybe_await(
+                scheduler.get_task_infos(
+                    schedule_state=schedule_state,
+                    executor=executor,
+                    trigger=trigger,
+                    q=q,
+                    sort_by=sort_by,
+                    descending=descending,
+                )
+            )
 
             # 3) Format payload
             payload: list[dict[str, Any]] = [
                 {
-                    "id": j.id,
-                    "name": j.name,
-                    "trigger": type(j.trigger).__name__,
-                    "next_run_time": getattr(j, "next_run_time", None),
+                    "id": item.id,
+                    "name": item.name,
+                    "trigger": item.trigger_name,
+                    "trigger_alias": item.trigger_alias,
+                    "trigger_description": item.trigger_description,
+                    "next_run_time": item.next_run_time,
+                    "state": item.schedule_state.value,
+                    "store": item.store_alias,
+                    "executor": item.executor,
+                    "callable_name": item.callable_name,
+                    "callable_reference": item.callable_reference,
                 }
-                for j in jobs
+                for item in infos
             ]
 
             # 4) Output
             if as_json:
-                info(json.dumps(payload, default=str))
+                print(json.dumps(payload, default=str))
                 return payload
             else:
                 for r in payload:
                     info(
                         f"{r['id']:<32} {r['name'] or '-':<24} "
-                        f"{r['trigger']:<16} {r['next_run_time']}"
+                        f"{r['state']:<10} {r['trigger'] or '-':<16} "
+                        f"{(r['store'] or '-'): <12} {(r['executor'] or '-'): <12} "
+                        f"{r['next_run_time']}"
                     )
                 return None
         finally:

{asyncz-0.14.2 → asyncz-0.15.0}/asyncz/cli/commands/pause.py

@@ -9,8 +9,6 @@ from sayer import Argument, Option, command, info, success
 from asyncz.cli.bootstrap_loader import load_bootstrap_scheduler
 from asyncz.cli.utils import build_stores_map, ensure_loop, maybe_await
 from asyncz.schedulers import AsyncIOScheduler
-from asyncz.stores.base import BaseStore
-from asyncz.tasks import Task as AsynczTask
 
 
 @command
@@ -28,11 +26,8 @@ def pause(
     """
     Pause a job by ID.
 
-    This command initializes a temporary scheduler, connects to the specified job store,
-    and instructs the store to temporarily suspend the execution of the specified job ID.
-
-    This implementation achieves the pause by **directly setting the task's next run time to None**
-    in the persistent store, avoiding scheduler events that might interfere with CLI execution.
+    The CLI delegates to ``scheduler.pause_task(...)`` so command-line behavior
+    stays aligned with the scheduler's own pause semantics.
 
     Examples:
         asyncz pause <job_id>
@@ -59,19 +54,12 @@ def pause(
             scheduler = AsyncIOScheduler(**cfg)
             await maybe_await(scheduler.start())
 
-        # 2) Locate the task and the store alias that holds it
-        task: AsynczTask
-        store_alias: str
-        task, store_alias = scheduler.lookup_task(job_id, None)  # type: ignore
-
-        # 3) Mark paused: clear next_run_time and persist in the originating store
-        task.update_task(next_run_time=None)
-        store_obj: BaseStore = scheduler.lookup_store(store_alias)  # type: ignore
-        store_obj.update_task(task)
+        # 2) Delegate to the scheduler API.
+        await maybe_await(scheduler.pause_task(job_id))
 
         success(f"Paused job {job_id}")
 
-        # 4) Shutdown only if we created a temporary scheduler
+        # 3) Shutdown only if we created a temporary scheduler
         if not bootstrap_mode:
             await maybe_await(scheduler.shutdown())
 

{asyncz-0.14.2 → asyncz-0.15.0}/asyncz/cli/commands/resume.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
-from datetime import datetime
 from typing import Annotated, Any
 
 from sayer import Argument, Option, command, info, success
@@ -10,8 +9,6 @@ from sayer import Argument, Option, command, info, success
 from asyncz.cli.bootstrap_loader import load_bootstrap_scheduler
 from asyncz.cli.utils import build_stores_map, ensure_loop, maybe_await
 from asyncz.schedulers import AsyncIOScheduler
-from asyncz.stores.base import BaseStore
-from asyncz.tasks import Task as AsynczTask
 
 
 @command
@@ -29,8 +26,8 @@ def resume(
     """
     Resume a paused job by ID.
 
-    This command initializes a temporary scheduler instance, connects to the specified job store,
-    and instructs the store to reactivate the execution schedule for the specified job ID.
+    The CLI delegates to ``scheduler.resume_task(...)`` so paused-job recovery
+    follows the same logic as programmatic callers and the dashboard.
 
     Examples:
         asyncz resume <job_id>
@@ -56,30 +53,14 @@ def resume(
             scheduler = AsyncIOScheduler(**cfg)
             await maybe_await(scheduler.start())
 
-        # 2) Lookup the task and its backing store alias
-        # Use None to let the scheduler find the correct store alias for the task.
-        task: AsynczTask
-        store_alias: str
-        task, store_alias = scheduler.lookup_task(job_id, None)  # type: ignore
-
-        # 3) Compute the next run time from "now" (resume semantics)
-        now: datetime = datetime.now(scheduler.timezone)
-        next_run: datetime | None = task.trigger.get_next_trigger_time(  # type: ignore[union-attr]
-            scheduler.timezone, None, now
-        )
-
-        # 4) Update or delete in the appropriate store
-        if next_run:
-            task.update_task(next_run_time=next_run)
-            store_obj: BaseStore = scheduler.lookup_store(store_alias)  # type: ignore
-            store_obj.update_task(task)
-            success(f"Resumed job {job_id}")
-        else:
-            # No further runs: remove the task entirely
-            scheduler.delete_task(job_id, store_alias)
+        # 2) Delegate to the scheduler API and mirror the resulting state in the message.
+        resumed_task = await maybe_await(scheduler.resume_task(job_id))
+        if resumed_task is None:
             success(f"Removed job {job_id} (schedule finished)")
+        else:
+            success(f"Resumed job {job_id}")
 
-        # 5) Shutdown only if we created a temporary scheduler
+        # 3) Shutdown only if we created a temporary scheduler
         if not bootstrap_mode:
             await maybe_await(scheduler.shutdown())
 

asyncz-0.15.0/asyncz/cli/commands/run.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import Annotated, Any
+
+from sayer import Argument, Option, command, info
+
+from asyncz.cli.bootstrap_loader import load_bootstrap_scheduler
+from asyncz.cli.utils import build_stores_map, ensure_loop, maybe_await
+from asyncz.schedulers import AsyncIOScheduler
+
+
+@command
+def run(
+    job_id: Annotated[str, Argument(help="Job ID to run now")],
+    bootstrap: Annotated[
+        str | None,
+        Option(
+            None,
+            help="Dotted path to a class with get_scheduler(), e.g. 'ravyn.contrib.asyncz:AsynczSpec'",
+        ),
+    ],
+    store: Annotated[list[str], Option([], "--store", help="Store spec alias=value. Repeatable.")],
+) -> None:
+    """
+    Trigger a job to run immediately.
+
+    This command delegates to ``scheduler.run_task(...)`` so the CLI, dashboard,
+    and programmatic APIs all share the same "run now" semantics.
+
+    Examples:
+
+        asyncz run <job_id>
+        asyncz run <job_id> --store durable=sqlite:///scheduler.db
+    """
+    loop: asyncio.AbstractEventLoop = ensure_loop()
+
+    async def main() -> None:
+        """The core asynchronous logic for running the job immediately."""
+        bootstrap_mode = bool(bootstrap)
+        if bootstrap_mode:
+            if store:
+                info("Using --bootstrap; ignoring --store flag.")
+
+            scheduler: AsyncIOScheduler = load_bootstrap_scheduler(bootstrap)  # type: ignore[arg-type]
+            # Try starting the scheduler if not already running
+            with contextlib.suppress(Exception):
+                await maybe_await(scheduler.start())
+        else:
+            # 1. Build configuration and initialize a temporary scheduler
+            cfg: dict[str, dict[str, Any]] = {"stores": build_stores_map(store)} if store else {}
+            scheduler = AsyncIOScheduler(**cfg)
+            await maybe_await(scheduler.start())
+
+        # 2. Delegate the "run now" flow to the scheduler itself.
+        await maybe_await(scheduler.run_task(job_id))
+        info(f"Triggered job {job_id}")
+
+        # 3. Shutdown the temporary scheduler
+        if not bootstrap_mode:
+            await maybe_await(scheduler.shutdown())
+
+    loop.run_until_complete(main())

{asyncz-0.14.2 → asyncz-0.15.0}/asyncz/cli/types.py

@@ -75,4 +75,4 @@ def parse_trigger(*, cron: str | None, interval: str | None, at: str | None) ->
     when: dt.datetime = dt.datetime.fromisoformat(at)  # type: ignore[arg-type]
     from asyncz.triggers.date import DateTrigger
 
-    return DateTrigger(run_date=when)
+    return DateTrigger(run_at=when)