tay-client 0.7.0__tar.gz

tay_client-0.7.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Andrii Sydorenko
+
+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.

tay_client-0.7.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: tay-client
+Version: 0.7.0
+Summary: Python SDK for producing and executing Tay jobs
+Author: Andrii Sydorenko
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/AndriiSydorenko1904/tay/tree/v0.7.0/clients/python
+Project-URL: Issues, https://github.com/AndriiSydorenko1904/tay/issues
+Project-URL: Source, https://github.com/AndriiSydorenko1904/tay
+Keywords: background-jobs,job-queue,scheduler,unix-socket
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+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: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Tay Python SDK
+
+`tay` is the stdlib-only Protocol v1 producer and worker client for a local Tay
+Unix-domain socket. `Tay()` needs no socket setting: it uses the same discovery
+contract as the Elixir Engine (explicit path, `TAY_SOCKET_PATH`, XDG runtime,
+`TMPDIR`, then `/tmp/tay-<uid>`). It is intentionally a separately installable
+package:
+
+```sh
+python -m pip install tay-client
+```
+
+From a Tay source checkout, use `python -m pip install ./clients/python`.
+
+Create a `Tay(mode="client")` producer, or a `Tay(mode="worker")` process that
+only executes registered tasks. The SDK sends JSON-object arguments and bounded
+JSON results; it does not serialize arbitrary Python objects.
+
+The producer surface is asynchronous: `enqueue`, `JobHandle.status()`,
+`JobHandle.result()`, and `JobHandle.cancel()` map directly to the currently
+supported Protocol v1 requests. Use a stable `submission_id` when retrying an
+enqueue whose connection outcome is unknown.
+
+Tasks declared before `await tay.start()` are advertised during the handshake.
+For a long-running worker that adds or removes capabilities later, explicitly
+sync the change:
+
+```python
+@tay.task(name="reports.rebuild.v1")
+def rebuild(report_id: str) -> dict:
+    return {"report_id": report_id}
+
+
+await tay.register_tasks(rebuild)
+# ... stop accepting new work for this task
+await tay.unregister_tasks(rebuild)
+```
+
+Both changes are retained as desired capability state and reconciled on the
+next connection. `client` mode cannot register task capabilities.
+
+## Schedules
+
+`schedule()` uses the five-field Unix cron form (minute, hour, day of month,
+month, day of week). Its default timezone is `+00`; pass a fixed UTC offset
+such as `+02`, `-05`, or `+05:30` when the schedule should be evaluated in a
+different local clock. The API accepts `catch_up="latest"` (default) or
+`catch_up="all"`, and defaults to `overlap="skip"`.
+
+```python
+# Every weekday at 08:00 in UTC+02.
+await tay.schedule(
+    "reports.rebuild.v1",
+    cron="0 8 * * 1-5",
+    timezone="+02",
+    catch_up="latest",
+)
+
+# First run in ten minutes, then every fifteen minutes.
+await tay.every("reports.rebuild.v1", minutes=15, delay=600)
+```
+
+Use `start_at=<UTC milliseconds>` instead of `delay` when the first occurrence
+has an absolute timestamp. The two options are mutually exclusive. Schedule
+creation, execution, and cancellation work against the current listener
+generation. Durable recovery/catch-up and enforced overlap policies are still
+pending in the Tay engine.
+
+Run a dedicated worker module with:
+
+```sh
+tay-worker myapp.jobs
+```
+
+The imported module must create exactly one `Tay(mode="worker")` instance and
+register its tasks. Pass `socket_path=` or set `TAY_SOCKET_PATH` only to override
+automatic discovery. See the repository README for the current durable-result/
+scheduling compatibility boundary.
+
+## License
+
+The `tay-client` Python package is licensed under the MIT License. The Tay
+engine is distributed separately under the Elastic License 2.0.

tay_client-0.7.0/README.md

@@ -0,0 +1,83 @@
+# Tay Python SDK
+
+`tay` is the stdlib-only Protocol v1 producer and worker client for a local Tay
+Unix-domain socket. `Tay()` needs no socket setting: it uses the same discovery
+contract as the Elixir Engine (explicit path, `TAY_SOCKET_PATH`, XDG runtime,
+`TMPDIR`, then `/tmp/tay-<uid>`). It is intentionally a separately installable
+package:
+
+```sh
+python -m pip install tay-client
+```
+
+From a Tay source checkout, use `python -m pip install ./clients/python`.
+
+Create a `Tay(mode="client")` producer, or a `Tay(mode="worker")` process that
+only executes registered tasks. The SDK sends JSON-object arguments and bounded
+JSON results; it does not serialize arbitrary Python objects.
+
+The producer surface is asynchronous: `enqueue`, `JobHandle.status()`,
+`JobHandle.result()`, and `JobHandle.cancel()` map directly to the currently
+supported Protocol v1 requests. Use a stable `submission_id` when retrying an
+enqueue whose connection outcome is unknown.
+
+Tasks declared before `await tay.start()` are advertised during the handshake.
+For a long-running worker that adds or removes capabilities later, explicitly
+sync the change:
+
+```python
+@tay.task(name="reports.rebuild.v1")
+def rebuild(report_id: str) -> dict:
+    return {"report_id": report_id}
+
+
+await tay.register_tasks(rebuild)
+# ... stop accepting new work for this task
+await tay.unregister_tasks(rebuild)
+```
+
+Both changes are retained as desired capability state and reconciled on the
+next connection. `client` mode cannot register task capabilities.
+
+## Schedules
+
+`schedule()` uses the five-field Unix cron form (minute, hour, day of month,
+month, day of week). Its default timezone is `+00`; pass a fixed UTC offset
+such as `+02`, `-05`, or `+05:30` when the schedule should be evaluated in a
+different local clock. The API accepts `catch_up="latest"` (default) or
+`catch_up="all"`, and defaults to `overlap="skip"`.
+
+```python
+# Every weekday at 08:00 in UTC+02.
+await tay.schedule(
+    "reports.rebuild.v1",
+    cron="0 8 * * 1-5",
+    timezone="+02",
+    catch_up="latest",
+)
+
+# First run in ten minutes, then every fifteen minutes.
+await tay.every("reports.rebuild.v1", minutes=15, delay=600)
+```
+
+Use `start_at=<UTC milliseconds>` instead of `delay` when the first occurrence
+has an absolute timestamp. The two options are mutually exclusive. Schedule
+creation, execution, and cancellation work against the current listener
+generation. Durable recovery/catch-up and enforced overlap policies are still
+pending in the Tay engine.
+
+Run a dedicated worker module with:
+
+```sh
+tay-worker myapp.jobs
+```
+
+The imported module must create exactly one `Tay(mode="worker")` instance and
+register its tasks. Pass `socket_path=` or set `TAY_SOCKET_PATH` only to override
+automatic discovery. See the repository README for the current durable-result/
+scheduling compatibility boundary.
+
+## License
+
+The `tay-client` Python package is licensed under the MIT License. The Tay
+engine is distributed separately under the Elastic License 2.0.

tay_client-0.7.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tay-client"
+version = "0.7.0"
+description = "Python SDK for producing and executing Tay jobs"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Andrii Sydorenko"}]
+keywords = ["background-jobs", "job-queue", "scheduler", "unix-socket"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://github.com/AndriiSydorenko1904/tay/tree/v0.7.0/clients/python"
+Issues = "https://github.com/AndriiSydorenko1904/tay/issues"
+Source = "https://github.com/AndriiSydorenko1904/tay"
+
+[project.scripts]
+tay-worker = "tay.__main__:main"
+
+[tool.setuptools]
+packages = ["tay"]
+
+[tool.setuptools.package-data]
+tay = ["py.typed"]

tay_client-0.7.0/setup.cfg

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

tay_client-0.7.0/tay/__init__.py

@@ -0,0 +1,35 @@
+"""Public Python SDK for the Tay Protocol v1 local executor endpoint."""
+
+from .client import JobHandle, ScheduleHandle, Tay
+from .errors import (
+    ConnectionLost,
+    ModeError,
+    ProtocolError,
+    RemoteTaskError,
+    ResultTooLarge,
+    ServerError,
+    TaskNotRegistered,
+    TaskRegistrationError,
+    TayError,
+    ValidationError,
+)
+from .socket_path import resolve_socket_path
+from .task import Task
+
+__all__ = [
+    "ConnectionLost",
+    "JobHandle",
+    "ModeError",
+    "ProtocolError",
+    "RemoteTaskError",
+    "ResultTooLarge",
+    "ScheduleHandle",
+    "ServerError",
+    "Task",
+    "TaskNotRegistered",
+    "TaskRegistrationError",
+    "Tay",
+    "TayError",
+    "ValidationError",
+    "resolve_socket_path",
+]

tay_client-0.7.0/tay/__main__.py

@@ -0,0 +1,67 @@
+"""The small, dependency-free dedicated-worker entry point."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import signal
+import sys
+from typing import Any
+
+from .client import Tay
+
+
+def _instance(specification: str) -> Tay:
+    module_name, separator, attribute = specification.partition(":")
+    module = importlib.import_module(module_name)
+    if separator:
+        candidate: Any = getattr(module, attribute)
+        if not isinstance(candidate, Tay):
+            raise TypeError(f"{specification!r} is not a Tay instance")
+        return candidate
+
+    candidates = tuple(
+        instance for instance in Tay.instances() if instance.__module__ == "tay.client"
+    )
+    if len(candidates) != 1:
+        raise RuntimeError(
+            f"{module_name!r} must create exactly one Tay instance, or use module:attribute"
+        )
+    return candidates[0]
+
+
+async def _serve(instance: Tay) -> None:
+    if instance.mode != "worker":
+        raise RuntimeError("tay-worker requires Tay(mode='worker')")
+
+    stopped = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for current in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(current, stopped.set)
+        except (
+            NotImplementedError
+        ):  # pragma: no cover - Windows has no UDS support here
+            pass
+
+    await instance.start()
+    try:
+        await stopped.wait()
+    finally:
+        await instance.close()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="run a dedicated Tay Python worker")
+    parser.add_argument("application", help="module or module:Tay_instance to import")
+    arguments = parser.parse_args(argv)
+    try:
+        asyncio.run(_serve(_instance(arguments.application)))
+    except (ImportError, AttributeError, RuntimeError, TypeError) as exc:
+        parser.error(str(exc))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())