asynk 0.1.0__tar.gz

asynk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Marques
+
+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.

asynk-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: asynk
+Version: 0.1.0
+Summary: Asyncio task framework with decoupled producers and consumers
+Keywords: asyncio,task-queue,tasks,workers,scheduler
+Author: Carlos Marques
+Author-email: Carlos Marques <chmarques93@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Dist: redis>=5.0.1 ; extra == 'redis'
+Requires-Python: >=3.11
+Project-URL: Issues, https://github.com/marquesch/asynk/issues
+Project-URL: Repository, https://github.com/marquesch/asynk
+Provides-Extra: redis
+Description-Content-Type: text/markdown
+
+# asynk
+
+asynk is a lightweight asyncio task framework for Python 3.11+, built on the
+standard library only. Define tasks with a decorator, publish them with
+`delay`, and run them in workers, behind any broker you plug in.
+
+**Documentation:** <https://marquesch.github.io/asynk/>
+
+## Install
+
+```bash
+pip install asynk
+```
+
+## Example
+
+```python
+"""The smallest asynk app: one task, published and run in the same process."""
+
+import asyncio
+
+from asynk import App, MemoryStore, Worker
+from asynk.transport.memory import memory_transport
+
+producer, consumer = memory_transport()
+app = App("first-app", producer=producer, consumer=consumer, store=MemoryStore())
+
+
+@app.task()
+async def add(a: int, b: int) -> int:
+    return a + b
+
+
+async def main() -> None:
+    worker = Worker(app)
+    run = asyncio.create_task(worker.run())
+
+    handle = await add.delay(2, b=3)
+    print("2 + 3 =", await handle.result(timeout=5))
+
+    worker.request_shutdown()
+    await run
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+With a broker transport, producers and workers run in separate processes; start
+a worker with `asynk worker tasks:app`.
+
+## Why asynk
+
+- **Decoupled producers and consumers**: the core only knows an envelope, a
+  codec and two small protocols, so any broker can sit behind them.
+- **Pluggable transport and store**: bring your own broker and result store; an
+  in-memory transport and store ship for development and tests, and a
+  [Redis store](https://marquesch.github.io/asynk/guides/redis/) and a
+  [Redis transport](https://marquesch.github.io/asynk/guides/redis-transport/)
+  come with `asynk[redis]`.
+- **Type-checked `delay`**: calls are checked against the task's signature.
+- **Cron scheduled tasks** with per-slot dedupe when schedulers share a store.
+- **Task results** through a store, with states and awaitable handles.
+- **Retries with backoff**: a retry policy per app or per task, with exponential
+  backoff and an exception filter.
+- **Lifecycle hooks** shared by workers and the scheduler.
+- **Middleware** around every task: timing, metrics, vetoes, cleanup.
+- **Health probes and graceful shutdown**, ready for Kubernetes.
+
+## Learn more
+
+- [Getting started](https://marquesch.github.io/asynk/getting-started/)
+- [Concepts](https://marquesch.github.io/asynk/concepts/)
+- [Guides](https://marquesch.github.io/asynk/guides/scheduled-tasks/) and
+  [advanced topics](https://marquesch.github.io/asynk/advanced/lifecycle-hooks/)
+- [API reference](https://marquesch.github.io/asynk/reference/)
+- [Release notes](https://marquesch.github.io/asynk/release-notes/) and the
+  [changelog](CHANGELOG.md)
+
+## License
+
+MIT, see [LICENSE](LICENSE).

asynk-0.1.0/README.md

@@ -0,0 +1,82 @@
+# asynk
+
+asynk is a lightweight asyncio task framework for Python 3.11+, built on the
+standard library only. Define tasks with a decorator, publish them with
+`delay`, and run them in workers, behind any broker you plug in.
+
+**Documentation:** <https://marquesch.github.io/asynk/>
+
+## Install
+
+```bash
+pip install asynk
+```
+
+## Example
+
+```python
+"""The smallest asynk app: one task, published and run in the same process."""
+
+import asyncio
+
+from asynk import App, MemoryStore, Worker
+from asynk.transport.memory import memory_transport
+
+producer, consumer = memory_transport()
+app = App("first-app", producer=producer, consumer=consumer, store=MemoryStore())
+
+
+@app.task()
+async def add(a: int, b: int) -> int:
+    return a + b
+
+
+async def main() -> None:
+    worker = Worker(app)
+    run = asyncio.create_task(worker.run())
+
+    handle = await add.delay(2, b=3)
+    print("2 + 3 =", await handle.result(timeout=5))
+
+    worker.request_shutdown()
+    await run
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+With a broker transport, producers and workers run in separate processes; start
+a worker with `asynk worker tasks:app`.
+
+## Why asynk
+
+- **Decoupled producers and consumers**: the core only knows an envelope, a
+  codec and two small protocols, so any broker can sit behind them.
+- **Pluggable transport and store**: bring your own broker and result store; an
+  in-memory transport and store ship for development and tests, and a
+  [Redis store](https://marquesch.github.io/asynk/guides/redis/) and a
+  [Redis transport](https://marquesch.github.io/asynk/guides/redis-transport/)
+  come with `asynk[redis]`.
+- **Type-checked `delay`**: calls are checked against the task's signature.
+- **Cron scheduled tasks** with per-slot dedupe when schedulers share a store.
+- **Task results** through a store, with states and awaitable handles.
+- **Retries with backoff**: a retry policy per app or per task, with exponential
+  backoff and an exception filter.
+- **Lifecycle hooks** shared by workers and the scheduler.
+- **Middleware** around every task: timing, metrics, vetoes, cleanup.
+- **Health probes and graceful shutdown**, ready for Kubernetes.
+
+## Learn more
+
+- [Getting started](https://marquesch.github.io/asynk/getting-started/)
+- [Concepts](https://marquesch.github.io/asynk/concepts/)
+- [Guides](https://marquesch.github.io/asynk/guides/scheduled-tasks/) and
+  [advanced topics](https://marquesch.github.io/asynk/advanced/lifecycle-hooks/)
+- [API reference](https://marquesch.github.io/asynk/reference/)
+- [Release notes](https://marquesch.github.io/asynk/release-notes/) and the
+  [changelog](CHANGELOG.md)
+
+## License
+
+MIT, see [LICENSE](LICENSE).

asynk-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "asynk"
+version = "0.1.0"
+description = "Asyncio task framework with decoupled producers and consumers"
+readme = "README.md"
+authors = [
+    { name = "Carlos Marques", email = "chmarques93@gmail.com" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["asyncio", "task-queue", "tasks", "workers", "scheduler"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+redis = ["redis>=5.0.1"]
+
+[project.urls]
+Repository = "https://github.com/marquesch/asynk"
+Issues = "https://github.com/marquesch/asynk/issues"
+
+[project.scripts]
+asynk = "asynk.cli:main"
+
+[build-system]
+requires = ["uv_build==0.9.9"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "asynk[redis]",
+    "fakeredis>=2.40.0",
+    "mypy>=2.4.1",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.17.3",
+]
+docs = [
+    "mkdocstrings-python>=2.0.10",
+    "zensical==0.1.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "--cov"
+pythonpath = ["."]
+
+[tool.coverage.run]
+source = ["src/asynk"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src", "tests", "examples"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "SIM"]
+# Public APIs take a plain `timeout` argument by design.
+ignore = ["ASYNC109"]

asynk-0.1.0/src/asynk/__init__.py

@@ -0,0 +1,78 @@
+"""asynk: an asyncio task framework."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from asynk.app import App
+from asynk.codec import Codec
+from asynk.codec.json import JsonCodec
+from asynk.envelope import Envelope
+from asynk.errors import (
+    AsynkError,
+    CronError,
+    DecodeError,
+    DeliveryFailedError,
+    EncodeError,
+    InvalidEnvelopeError,
+    NotConfiguredError,
+    TaskError,
+    TaskNotFoundError,
+)
+from asynk.hooks import Next, TaskCall, TaskResult, TaskStatus
+from asynk.options import TaskOptions
+from asynk.results import TaskHandle, TaskState
+from asynk.retry import Backoff, Exponential, RetryPolicy
+from asynk.runner import Runner
+from asynk.scheduled_task import ScheduledTask
+from asynk.scheduler import Scheduler
+from asynk.store import Store
+from asynk.store.memory import MemoryStore
+from asynk.store.null import NullStore
+from asynk.task import Task
+from asynk.transport import Consumer, Delivery, Producer, PublishOptions
+from asynk.worker import Worker
+
+try:
+    __version__ = version("asynk")
+except PackageNotFoundError:
+    # Imported from a source tree without an installed distribution.
+    __version__ = "0+unknown"
+"""The installed asynk version."""
+
+__all__ = [
+    "__version__",
+    "App",
+    "AsynkError",
+    "Backoff",
+    "Codec",
+    "Consumer",
+    "CronError",
+    "DecodeError",
+    "Delivery",
+    "DeliveryFailedError",
+    "Envelope",
+    "InvalidEnvelopeError",
+    "JsonCodec",
+    "EncodeError",
+    "Exponential",
+    "NotConfiguredError",
+    "Next",
+    "Producer",
+    "PublishOptions",
+    "RetryPolicy",
+    "Runner",
+    "Task",
+    "TaskCall",
+    "TaskResult",
+    "TaskStatus",
+    "ScheduledTask",
+    "Scheduler",
+    "Worker",
+    "Store",
+    "MemoryStore",
+    "NullStore",
+    "TaskHandle",
+    "TaskOptions",
+    "TaskState",
+    "TaskError",
+    "TaskNotFoundError",
+]

asynk-0.1.0/src/asynk/_extras.py

@@ -0,0 +1,28 @@
+"""Import-time guard shared by the packages that need an optional extra."""
+
+from __future__ import annotations
+
+import importlib
+
+
+def require_extra(package: str, extra: str) -> None:
+    """Imports `package`, or raises an ImportError that names the extra to install.
+
+    Call it at the top of the package that needs the extra.
+
+    Args:
+        package: Top-level name of the third-party package the extra installs.
+        extra: Name of the extra, as in `pip install 'asynk[<extra>]'`.
+
+    Raises:
+        ImportError: If `package` is not installed. An error raised by one of
+            its own dependencies is passed on unchanged.
+    """
+    try:
+        importlib.import_module(package)
+    except ImportError as exc:
+        if exc.name != package:
+            raise
+        raise ImportError(
+            f"asynk[{extra}] needs the {package} package: pip install 'asynk[{extra}]'"
+        ) from exc

asynk-0.1.0/src/asynk/_redis.py

@@ -0,0 +1,39 @@
+"""The Redis client a Redis store or transport uses, and who closes it."""
+
+from __future__ import annotations
+
+from asynk._extras import require_extra
+
+require_extra("redis", "redis")
+
+from redis.asyncio import Redis  # noqa: E402
+
+
+class RedisConnection:
+    """A Redis client, either given by the caller or created from a URL."""
+
+    def __init__(self, url: str | None, client: Redis | None, *, owner: str) -> None:
+        """Initializes the connection.
+
+        Args:
+            url: Redis URL; the connection creates its own client and closes it.
+            client: Redis client the caller owns and closes.
+            owner: Name of the class using the connection, for error messages.
+
+        Raises:
+            ValueError: If not exactly one of `url` and `client` is given.
+        """
+        if (url is None) == (client is None):
+            raise ValueError(f"{owner} needs exactly one of url and client")
+        if client is None:
+            assert url is not None
+            client = Redis.from_url(url, socket_timeout=5.0, socket_connect_timeout=5.0)
+            self._owns_client = True
+        else:
+            self._owns_client = False
+        self.client = client
+
+    async def close(self) -> None:
+        """Closes the client if the connection created it."""
+        if self._owns_client:
+            await self.client.aclose()