tickforge 0.1.0__tar.gz

tickforge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tickforge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tickforge-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: tickforge
+Version: 0.1.0
+Summary: An advanced task scheduler with persistence, retries, cron/interval/date triggers and native async support.
+Author: tickforge contributors
+License: MIT License
+        
+        Copyright (c) 2026 tickforge contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/scheduleforge/tickforge
+Project-URL: Repository, https://github.com/scheduleforge/tickforge
+Project-URL: Issues, https://github.com/scheduleforge/tickforge/issues
+Keywords: scheduler,cron,async,asyncio,jobs,tasks,persistence
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: python-dateutil>=2.8.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+# tickforge
+
+An advanced task scheduler for Python with **persistence**, **native async support**,
+retries, timeouts, misfire handling and a batteries-included CLI.
+
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Features
+
+- **Three trigger types** — `IntervalTrigger`, `CronTrigger` (with timezone support), `DateTrigger`
+- **Durable jobs** — SQLite, JSON file, or in-memory stores behind one interface
+- **Async first** — `async def` jobs are awaited; sync jobs run in a thread pool
+- **Reliability** — per-job retries, retry backoff delay, execution timeouts, misfire grace windows
+- **Concurrency control** — global semaphore plus per-job overlap protection
+- **Run history** — every execution recorded with duration, attempts, result and traceback
+- **Event hooks** — subscribe to job and scheduler lifecycle events
+- **Structured logging** — human-readable or JSON, with job context on every record
+- **CLI** — register, inspect, preview, run and serve jobs without writing a driver script
+
+## Installation
+
+```bash
+pip install tickforge
+```
+
+From source:
+
+```bash
+git clone https://github.com/example/tickforge
+cd tickforge
+pip install -e ".[dev]"
+```
+
+Requires Python 3.8 or newer. Dependencies: `click`, `python-dateutil`.
+
+## Quick start
+
+### Async
+
+```python
+import asyncio
+from tickforge import AsyncScheduler, CronTrigger, IntervalTrigger, SQLiteJobStore
+
+async def heartbeat():
+    print("alive")
+
+def collect_metrics(source: str):
+    print("collecting from", source)
+
+async def main():
+    scheduler = AsyncScheduler(store=SQLiteJobStore("jobs.db"))
+    await scheduler.add_job(heartbeat, IntervalTrigger(seconds=30), name="heartbeat")
+    await scheduler.add_job(
+        collect_metrics,
+        CronTrigger.from_string("*/5 * * * *", timezone="Europe/Paris"),
+        args=["edge-01"],
+        max_retries=3,
+        retry_delay=10,
+        timeout=60,
+        name="metrics",
+    )
+    await scheduler.run_forever()
+
+asyncio.run(main())
+```
+
+### Synchronous
+
+```python
+from tickforge import Scheduler, IntervalTrigger, MemoryJobStore
+
+def report():
+    print("report generated")
+
+with Scheduler(store=MemoryJobStore()) as scheduler:
+    scheduler.add_job(report, IntervalTrigger(minutes=15), name="report")
+    input("press enter to stop\n")
+```
+
+## Triggers
+
+| Trigger | Purpose | Example |
+| --- | --- | --- |
+| `IntervalTrigger` | Fixed period, optional jitter and window | `IntervalTrigger(hours=2, jitter=30)` |
+| `CronTrigger` | Calendar schedules, timezone aware | `CronTrigger(minute="0", hour="9", day_of_week="mon-fri")` |
+| `DateTrigger` | One-shot execution | `DateTrigger(run_at="2026-01-01T00:00:00Z")` |
+
+Cron fields are `minute hour day month day_of_week`, supporting `*`, `a-b`, `a,b`,
+`*/n`, `a-b/n`, month and weekday names, and the macros `@hourly`, `@daily`,
+`@weekly`, `@monthly`, `@yearly`.
+
+**`day_of_week` uses Python semantics: `0` is Monday through `6` is Sunday.**
+Names (`mon`, `fri`) and the legacy `7` for Sunday are also accepted. When both
+`day` and `day_of_week` are restricted, classic cron OR semantics apply.
+
+## Stores
+
+```python
+from tickforge import MemoryJobStore, JSONFileJobStore, SQLiteJobStore, create_store
+
+MemoryJobStore()                  # volatile, ideal for tests
+JSONFileJobStore("jobs.json")     # human-readable, atomic writes
+SQLiteJobStore("jobs.db")         # durable, WAL, safe across threads and processes
+
+create_store("sqlite:///var/lib/tickforge/jobs.db")
+create_store("json:///tmp/jobs.json")
+create_store("memory://")
+```
+
+Because jobs are persisted as `module:callable` references, the target must be
+importable from the process running the scheduler. Lambdas and locally defined
+functions are rejected at registration time.
+
+## Reliability options
+
+```python
+await scheduler.add_job(
+    flaky_task,
+    IntervalTrigger(minutes=5),
+    max_retries=3,            # four attempts total
+    retry_delay=10,           # seconds between attempts
+    timeout=120,              # abort a single attempt after two minutes
+    misfire_grace_time=300,   # drop slots older than five minutes
+    coalesce=True,            # collapse a missed backlog into one run
+    allow_concurrent=False,   # skip a slot if the previous run is still going
+)
+```
+
+## Events
+
+```python
+from tickforge import EventType
+
+def on_error(event):
+    print("job failed:", event.job.name, event.run.error)
+
+scheduler.add_listener(on_error, EventType.JOB_ERROR)
+scheduler.add_listener(lambda e: print(e.to_dict()))   # all events
+```
+
+Available types: `SCHEDULER_STARTED`, `SCHEDULER_STOPPED`, `SCHEDULER_PAUSED`,
+`SCHEDULER_RESUMED`, `JOB_ADDED`, `JOB_REMOVED`, `JOB_MODIFIED`, `JOB_SUBMITTED`,
+`JOB_EXECUTED`, `JOB_ERROR`, `JOB_RETRY`, `JOB_MISSED`, `JOB_SKIPPED`, `JOB_FINISHED`.
+
+## Logging
+
+```python
+from tickforge import configure_logging
+
+configure_logging(level="DEBUG", fmt="json", log_file="/var/log/tickforge.log")
+```
+
+Records emitted during a run carry `job_id`, `run_id` and `job_name` automatically.
+
+## CLI
+
+```bash
+# register jobs
+tickforge add myapp.tasks:cleanup --interval 1h --name nightly-cleanup
+tickforge add myapp.tasks:report --cron "0 9 * * mon-fri" --timezone Europe/Paris
+tickforge add myapp.tasks:ping --at "2026-06-01 12:00" --retries 2 --timeout 30
+
+# inspect
+tickforge list
+tickforge show nightly-cleanup
+tickforge next nightly-cleanup --count 10
+tickforge history --limit 20
+
+# control
+tickforge pause nightly-cleanup
+tickforge resume nightly-cleanup
+tickforge run-now nightly-cleanup
+tickforge remove nightly-cleanup --yes
+
+# serve
+tickforge start --poll 1 --concurrency 20
+```
+
+Global options: `--db` (path or store URI, also read from `TICKFORGE_DB`),
+`-v/-vv`, `-q`, `--log-format text|json`, `--log-file`.
+
+The default store is `~/.tickforge/jobs.db`.
+
+## Running as a service
+
+```ini
+[Unit]
+Description=tickforge scheduler
+After=network.target
+
+[Service]
+Environment=TICKFORGE_DB=/var/lib/tickforge/jobs.db
+ExecStart=/usr/local/bin/tickforge --log-format json start
+Restart=always
+User=tickforge
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src
+black src
+mypy src
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tickforge-0.1.0/README.md

@@ -0,0 +1,214 @@
+# tickforge
+
+An advanced task scheduler for Python with **persistence**, **native async support**,
+retries, timeouts, misfire handling and a batteries-included CLI.
+
+[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Features
+
+- **Three trigger types** — `IntervalTrigger`, `CronTrigger` (with timezone support), `DateTrigger`
+- **Durable jobs** — SQLite, JSON file, or in-memory stores behind one interface
+- **Async first** — `async def` jobs are awaited; sync jobs run in a thread pool
+- **Reliability** — per-job retries, retry backoff delay, execution timeouts, misfire grace windows
+- **Concurrency control** — global semaphore plus per-job overlap protection
+- **Run history** — every execution recorded with duration, attempts, result and traceback
+- **Event hooks** — subscribe to job and scheduler lifecycle events
+- **Structured logging** — human-readable or JSON, with job context on every record
+- **CLI** — register, inspect, preview, run and serve jobs without writing a driver script
+
+## Installation
+
+```bash
+pip install tickforge
+```
+
+From source:
+
+```bash
+git clone https://github.com/example/tickforge
+cd tickforge
+pip install -e ".[dev]"
+```
+
+Requires Python 3.8 or newer. Dependencies: `click`, `python-dateutil`.
+
+## Quick start
+
+### Async
+
+```python
+import asyncio
+from tickforge import AsyncScheduler, CronTrigger, IntervalTrigger, SQLiteJobStore
+
+async def heartbeat():
+    print("alive")
+
+def collect_metrics(source: str):
+    print("collecting from", source)
+
+async def main():
+    scheduler = AsyncScheduler(store=SQLiteJobStore("jobs.db"))
+    await scheduler.add_job(heartbeat, IntervalTrigger(seconds=30), name="heartbeat")
+    await scheduler.add_job(
+        collect_metrics,
+        CronTrigger.from_string("*/5 * * * *", timezone="Europe/Paris"),
+        args=["edge-01"],
+        max_retries=3,
+        retry_delay=10,
+        timeout=60,
+        name="metrics",
+    )
+    await scheduler.run_forever()
+
+asyncio.run(main())
+```
+
+### Synchronous
+
+```python
+from tickforge import Scheduler, IntervalTrigger, MemoryJobStore
+
+def report():
+    print("report generated")
+
+with Scheduler(store=MemoryJobStore()) as scheduler:
+    scheduler.add_job(report, IntervalTrigger(minutes=15), name="report")
+    input("press enter to stop\n")
+```
+
+## Triggers
+
+| Trigger | Purpose | Example |
+| --- | --- | --- |
+| `IntervalTrigger` | Fixed period, optional jitter and window | `IntervalTrigger(hours=2, jitter=30)` |
+| `CronTrigger` | Calendar schedules, timezone aware | `CronTrigger(minute="0", hour="9", day_of_week="mon-fri")` |
+| `DateTrigger` | One-shot execution | `DateTrigger(run_at="2026-01-01T00:00:00Z")` |
+
+Cron fields are `minute hour day month day_of_week`, supporting `*`, `a-b`, `a,b`,
+`*/n`, `a-b/n`, month and weekday names, and the macros `@hourly`, `@daily`,
+`@weekly`, `@monthly`, `@yearly`.
+
+**`day_of_week` uses Python semantics: `0` is Monday through `6` is Sunday.**
+Names (`mon`, `fri`) and the legacy `7` for Sunday are also accepted. When both
+`day` and `day_of_week` are restricted, classic cron OR semantics apply.
+
+## Stores
+
+```python
+from tickforge import MemoryJobStore, JSONFileJobStore, SQLiteJobStore, create_store
+
+MemoryJobStore()                  # volatile, ideal for tests
+JSONFileJobStore("jobs.json")     # human-readable, atomic writes
+SQLiteJobStore("jobs.db")         # durable, WAL, safe across threads and processes
+
+create_store("sqlite:///var/lib/tickforge/jobs.db")
+create_store("json:///tmp/jobs.json")
+create_store("memory://")
+```
+
+Because jobs are persisted as `module:callable` references, the target must be
+importable from the process running the scheduler. Lambdas and locally defined
+functions are rejected at registration time.
+
+## Reliability options
+
+```python
+await scheduler.add_job(
+    flaky_task,
+    IntervalTrigger(minutes=5),
+    max_retries=3,            # four attempts total
+    retry_delay=10,           # seconds between attempts
+    timeout=120,              # abort a single attempt after two minutes
+    misfire_grace_time=300,   # drop slots older than five minutes
+    coalesce=True,            # collapse a missed backlog into one run
+    allow_concurrent=False,   # skip a slot if the previous run is still going
+)
+```
+
+## Events
+
+```python
+from tickforge import EventType
+
+def on_error(event):
+    print("job failed:", event.job.name, event.run.error)
+
+scheduler.add_listener(on_error, EventType.JOB_ERROR)
+scheduler.add_listener(lambda e: print(e.to_dict()))   # all events
+```
+
+Available types: `SCHEDULER_STARTED`, `SCHEDULER_STOPPED`, `SCHEDULER_PAUSED`,
+`SCHEDULER_RESUMED`, `JOB_ADDED`, `JOB_REMOVED`, `JOB_MODIFIED`, `JOB_SUBMITTED`,
+`JOB_EXECUTED`, `JOB_ERROR`, `JOB_RETRY`, `JOB_MISSED`, `JOB_SKIPPED`, `JOB_FINISHED`.
+
+## Logging
+
+```python
+from tickforge import configure_logging
+
+configure_logging(level="DEBUG", fmt="json", log_file="/var/log/tickforge.log")
+```
+
+Records emitted during a run carry `job_id`, `run_id` and `job_name` automatically.
+
+## CLI
+
+```bash
+# register jobs
+tickforge add myapp.tasks:cleanup --interval 1h --name nightly-cleanup
+tickforge add myapp.tasks:report --cron "0 9 * * mon-fri" --timezone Europe/Paris
+tickforge add myapp.tasks:ping --at "2026-06-01 12:00" --retries 2 --timeout 30
+
+# inspect
+tickforge list
+tickforge show nightly-cleanup
+tickforge next nightly-cleanup --count 10
+tickforge history --limit 20
+
+# control
+tickforge pause nightly-cleanup
+tickforge resume nightly-cleanup
+tickforge run-now nightly-cleanup
+tickforge remove nightly-cleanup --yes
+
+# serve
+tickforge start --poll 1 --concurrency 20
+```
+
+Global options: `--db` (path or store URI, also read from `TICKFORGE_DB`),
+`-v/-vv`, `-q`, `--log-format text|json`, `--log-file`.
+
+The default store is `~/.tickforge/jobs.db`.
+
+## Running as a service
+
+```ini
+[Unit]
+Description=tickforge scheduler
+After=network.target
+
+[Service]
+Environment=TICKFORGE_DB=/var/lib/tickforge/jobs.db
+ExecStart=/usr/local/bin/tickforge --log-format json start
+Restart=always
+User=tickforge
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src
+black src
+mypy src
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tickforge-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tickforge"
+version = "0.1.0"
+description = "An advanced task scheduler with persistence, retries, cron/interval/date triggers and native async support."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+authors = [{ name = "tickforge contributors" }]
+keywords = ["scheduler", "cron", "async", "asyncio", "jobs", "tasks", "persistence"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "click>=8.0",
+    "python-dateutil>=2.8.2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "black>=23.0",
+    "ruff>=0.1",
+    "mypy>=1.0",
+    "build>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/scheduleforge/tickforge"
+Repository = "https://github.com/scheduleforge/tickforge"
+Issues = "https://github.com/scheduleforge/tickforge/issues"
+
+[project.scripts]
+tickforge = "tickforge.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tickforge = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ["py38"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.mypy]
+python_version = "3.8"
+warn_unused_ignores = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

tickforge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tickforge-0.1.0/src/tickforge/__init__.py

@@ -0,0 +1,107 @@
+"""tickforge: an advanced task scheduler with persistence and async support.
+
+Quick start
+-----------
+    import asyncio
+    from tickforge import AsyncScheduler, IntervalTrigger, SQLiteJobStore
+
+    async def ping():
+        print("pong")
+
+    async def main():
+        scheduler = AsyncScheduler(store=SQLiteJobStore("jobs.db"))
+        await scheduler.add_job(ping, IntervalTrigger(seconds=5), name="ping")
+        await scheduler.start()
+        await scheduler.wait_closed()
+
+    asyncio.run(main())
+"""
+
+from .core import (
+    ConfigurationError,
+    CronTrigger,
+    DateTrigger,
+    IntervalTrigger,
+    Job,
+    JobExecutionError,
+    JobLookupError,
+    JobResult,
+    JobRun,
+    JobStatus,
+    SchedulePlusError,
+    SerializationError,
+    Trigger,
+    TriggerError,
+    build_trigger,
+    callable_ref,
+    coerce_datetime,
+    coerce_timezone,
+    resolve_callable,
+    trigger_from_dict,
+    utcnow,
+)
+from .logging import (
+    JSONFormatter,
+    TextFormatter,
+    configure_logging,
+    get_logger,
+    job_context,
+)
+from .persistence import (
+    JobStore,
+    JSONFileJobStore,
+    MemoryJobStore,
+    SQLiteJobStore,
+    create_store,
+)
+from .scheduler import (
+    AsyncScheduler,
+    EventType,
+    Scheduler,
+    SchedulerConfig,
+    SchedulerEvent,
+    SchedulerState,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "SchedulePlusError",
+    "TriggerError",
+    "JobLookupError",
+    "JobExecutionError",
+    "SerializationError",
+    "ConfigurationError",
+    "Trigger",
+    "DateTrigger",
+    "IntervalTrigger",
+    "CronTrigger",
+    "Job",
+    "JobRun",
+    "JobResult",
+    "JobStatus",
+    "build_trigger",
+    "trigger_from_dict",
+    "resolve_callable",
+    "callable_ref",
+    "coerce_datetime",
+    "coerce_timezone",
+    "utcnow",
+    "JobStore",
+    "MemoryJobStore",
+    "SQLiteJobStore",
+    "JSONFileJobStore",
+    "create_store",
+    "AsyncScheduler",
+    "Scheduler",
+    "SchedulerConfig",
+    "SchedulerState",
+    "SchedulerEvent",
+    "EventType",
+    "configure_logging",
+    "get_logger",
+    "job_context",
+    "JSONFormatter",
+    "TextFormatter",
+]