pydovetail 0.4.0__tar.gz

pydovetail-0.4.0/LICENSE

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

pydovetail-0.4.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: pydovetail
+Version: 0.4.0
+Summary: A lightweight helper for bridging sync and async code, built on Asyncio & ThreadPoolExecutor
+Author-email: anthrosystems <peaceolawuyi01@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/anthrosystems/dovetail
+Project-URL: Repository, https://github.com/anthrosystems/dovetail
+Project-URL: Changelog, https://github.com/anthrosystems/dovetail/blob/main/CHANGELOG.md
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Dovetail - Sync / Async wrapper for Python.
+
+[![CI](https://github.com/anthrosystems/dovetail/actions/workflows/ci.yml/badge.svg)](https://github.com/anthrosystems/dovetail/actions/workflows/ci.yml) 
+[![PyPI version](https://img.shields.io/pypi/v/dovetail.svg)](https://pypi.org/project/pydovetail/) 
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/anthrosystems/dovetail.svg)](https://github.com/anthrosystems/dovetail/releases/latest)
+
+A lightweight helper for bridging sync and async code, built on Asyncio & ThreadPoolExecutor.
+
+## Table of Contents
+
+- [Why Dovetail](#why-dovetail)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [API Summary](#api-summary)
+- [Detailed Guides](docs/detailed_guide.md#L1)
+- [Development](#development)
+- [License](#license)
+
+## Why Dovetail?
+
+Asyncio is powerful, but it has a cascading problem: the moment you want to
+`await` something, that function has to be `async`, which means everything
+calling it has to be `async`, and so on until your entire codebase has been
+rewritten around it. If you're adding parallelism to an existing project, or
+just want to speed up one specific bottleneck, that cost is hard to justify.
+
+Dovetail's advantage isn't raw performance — `asyncio.gather` will always be
+at least as fast, since Dovetail is built on top of it. The advantage of Dovetail is its
+**surgical approach**: you can parallelise one function in an otherwise
+synchronous codebase without touching anything else.
+
+```python
+# Existing sync code, completely unchanged around this one call
+def process_report():
+    data = dvt.task.map_blocking(fetch_url, urls)  # parallel, but sync caller
+    return summarise(data)
+```
+
+With raw asyncio you can't do this — `fetch_url` being async forces
+`process_report` to be async, which forces everything above it to be async.
+Dovetail breaks that chain. If you're starting a greenfield project and are
+comfortable with async/await throughout, you probably don't need it. Dovetail
+is for the developers who are stuck between "I want parallelism" and "I don't want to rewrite everything."
+
+
+## Install
+
+```bash
+pip install pydovetail
+```
+
+> **Note:** The install name is `pydovetail`, but the import name is `dovetail`.
+> ```python
+> from dovetail import Dovetail
+> ```
+
+
+## Quick Start
+
+Preferred usage: create and manage a `Dovetail` instance with a context manager.
+
+Sync (recommended for most users):
+
+```python
+from dovetail import Dovetail
+
+with Dovetail(max_workers=8) as dvt:
+  # Sync caller -> sync function (blocks)
+  result = dvt.task.run_blocking(fetch_data)
+
+  # Sync caller -> sync function in threadpool (blocks)
+  result = dvt.task.to_thread_blocking(fetch_data, "target.json")
+
+  # Sync caller -> batch map in threadpool (blocks, bounded concurrency)
+  results = dvt.task.map_blocking(fetch_data, ["a.json", "b.json"], max_concurrency=4)
+
+  # run an async coroutine from sync code
+  value = dvt.task.run_blocking(fetch_data_async())
+```
+
+Async (use `async with` in async applications):
+
+```python
+async with Dovetail() as dvt:
+  # schedule coroutines and await
+  tasks = [dvt.task.schedule(fetch_async(i)) for i in items]
+  results = await asyncio.gather(*tasks)
+```
+
+Manual / library patterns (caller-managed ownership):
+
+```py
+# Manual creation: by default Dovetail will attempt to shutdown on
+# interpreter exit and on SIGINT/SIGTERM. You can opt out by passing
+# `shutdown_on_exit=False` when constructing the instance.
+dvt = Dovetail()  # shutdown_on_exit enabled by default
+try:
+  results = dvt.task.map_blocking(fetch, items)
+finally:
+  # explicit shutdown is still allowed and idempotent
+  dvt.shutdown()
+
+# Library-author pattern (prefer caller-managed instance when possible)
+def process(items, dvt: Optional[Dovetail] = None):
+  if dvt is None:
+    with Dovetail() as _dvt:
+      return _dvt.task.map_blocking(worker, items)
+  return dvt.task.map_blocking(worker, items)
+```
+
+> **Note:** `Dovetail` will, by default, register a best-effort shutdown
+> handler that calls `shutdown()` on interpreter exit and when `SIGINT` or
+> `SIGTERM` are received. This is opt-outable via `shutdown_on_exit=False`.
+> Explicitly calling `dvt.shutdown()` is still supported and idempotent.
+>
+> Sync context manager (recommended for synchronous code):
+> ```python
+> with Dovetail(max_workers=8) as dvt:
+>     results = dvt.task.map_blocking(fetch, items)
+> # threadpool shut down on block exit
+> ```
+>
+> Async context manager (recommended for async code):
+> ```python
+> async def main():
+>     async with Dovetail() as dvt:
+>         tasks = [dvt.task.schedule(coro(i)) for i in items]
+>         await asyncio.gather(*tasks)
+> # __aexit__ runs shutdown off the event loop to avoid blocking
+> ```
+>
+> Implementation note: `Dovetail` supports both `__enter__/__exit__` and
+> `__aenter__/__aexit__`. The async exit runs `shutdown()` in a background
+> executor to avoid blocking the running loop. `shutdown()` is idempotent and
+> safe to call multiple times.
+
+
+## API Summary
+
+**Task execution**
+
+- `dvt.task.to_thread(func, *args, **kwargs)` — await a sync callable in Dovetail's threadpool from async code; supports default timeout/retry settings.
+- `dvt.task.to_thread_blocking(func, *args, **kwargs)` — synchronous wrapper for `to_thread` when you are not already in an event loop.
+- `dvt.task.schedule(coro_or_callable, *args, **kwargs)` — create and return an `asyncio.Task` from a coroutine object, async function, or sync callable.
+- `dvt.task.run_blocking(func_or_coro, *args, **kwargs)` — run async or sync work from synchronous code. Do not call from inside a running event loop.
+- `dvt.task.map_blocking(func, items, max_concurrency=None, return_exceptions=False)` — run an ordered parallel map over `items` using the threadpool.
+
+**Events**
+
+- `dvt.events.on_queued(...)` — fires when a task is queued.
+- `dvt.events.on_start(...)` — fires when a task starts executing.
+- `dvt.events.on_end(...)` — fires when a task resolves (including after retries).
+- `dvt.events.on_error(...)` — fires when a task raises an exception.
+- `dvt.events.on_retry(...)` — fires on each retry attempt.
+- `dvt.events.on_cancel(...)` — fires when a task is cancelled.
+- `dvt.events.stats()` — returns cumulative counters: `queued`, `started`, `done`, `error`, `retries`, `throttled`.
+
+**Registry (auto-registration)**
+
+- `dovetail` now exposes a lightweight registry to track active `Dovetail` instances. By default `Dovetail(..., auto_register=True)` will register itself with the package registry so applications can perform coordinated shutdown.
+- Public helpers:
+  - `from dovetail import register, unregister, list_active, shutdown_all, set_app_shutdown_hook`
+  - `register(dvt)` — explicitly register an instance (optional; instances auto-register by default).
+  - `unregister(dvt)` — remove from the registry (useful if you manage shutdown yourself).
+  - `list_active()` — return a list of active (live) instances.
+  - `shutdown_all(wait=True)` — best-effort shutdown of all registered instances (useful for app shutdown hooks).
+  - `set_app_shutdown_hook(fn)` — provide an application-level hook that the registry will call during process exit.
+
+Notes:
+- The registry uses weakrefs and logs a warning if a `Dovetail` is garbage-collected without an explicit `shutdown()` call.
+- To opt-out of auto-registration when creating a `Dovetail`, pass `auto_register=False` to the constructor.
+
+All `dvt.events.on_*` methods accept these optional scope parameters:
+
+- `function_target` — only receive events for a specific callable.
+- `instance_target` — only receive events for a specific execution id (available
+  as `id` in the event payload).
+- `allow_reentry=False` — prevents a listener from triggering itself recursively.
+  Set to `True` to allow reentry, bounded by `max_chain_depth`.
+- `max_chain_depth=5` — maximum active callback depth when reentry is enabled.
+
+
+## Detailed Guides
+
+Full, expanded guides live in the repository under [docs/detailed_guide.md](docs/detailed_guide.md#L1).
+
+
+## Development
+
+Run tests locally:
+
+```bash
+python -m pytest -q
+```
+
+Contributions welcome — open an issue or PR.
+
+
+## License
+
+MIT. See `CHANGELOG.md` for release notes.

pydovetail-0.4.0/README.md

@@ -0,0 +1,202 @@
+# Dovetail - Sync / Async wrapper for Python.
+
+[![CI](https://github.com/anthrosystems/dovetail/actions/workflows/ci.yml/badge.svg)](https://github.com/anthrosystems/dovetail/actions/workflows/ci.yml) 
+[![PyPI version](https://img.shields.io/pypi/v/dovetail.svg)](https://pypi.org/project/pydovetail/) 
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/anthrosystems/dovetail.svg)](https://github.com/anthrosystems/dovetail/releases/latest)
+
+A lightweight helper for bridging sync and async code, built on Asyncio & ThreadPoolExecutor.
+
+## Table of Contents
+
+- [Why Dovetail](#why-dovetail)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [API Summary](#api-summary)
+- [Detailed Guides](docs/detailed_guide.md#L1)
+- [Development](#development)
+- [License](#license)
+
+## Why Dovetail?
+
+Asyncio is powerful, but it has a cascading problem: the moment you want to
+`await` something, that function has to be `async`, which means everything
+calling it has to be `async`, and so on until your entire codebase has been
+rewritten around it. If you're adding parallelism to an existing project, or
+just want to speed up one specific bottleneck, that cost is hard to justify.
+
+Dovetail's advantage isn't raw performance — `asyncio.gather` will always be
+at least as fast, since Dovetail is built on top of it. The advantage of Dovetail is its
+**surgical approach**: you can parallelise one function in an otherwise
+synchronous codebase without touching anything else.
+
+```python
+# Existing sync code, completely unchanged around this one call
+def process_report():
+    data = dvt.task.map_blocking(fetch_url, urls)  # parallel, but sync caller
+    return summarise(data)
+```
+
+With raw asyncio you can't do this — `fetch_url` being async forces
+`process_report` to be async, which forces everything above it to be async.
+Dovetail breaks that chain. If you're starting a greenfield project and are
+comfortable with async/await throughout, you probably don't need it. Dovetail
+is for the developers who are stuck between "I want parallelism" and "I don't want to rewrite everything."
+
+
+## Install
+
+```bash
+pip install pydovetail
+```
+
+> **Note:** The install name is `pydovetail`, but the import name is `dovetail`.
+> ```python
+> from dovetail import Dovetail
+> ```
+
+
+## Quick Start
+
+Preferred usage: create and manage a `Dovetail` instance with a context manager.
+
+Sync (recommended for most users):
+
+```python
+from dovetail import Dovetail
+
+with Dovetail(max_workers=8) as dvt:
+  # Sync caller -> sync function (blocks)
+  result = dvt.task.run_blocking(fetch_data)
+
+  # Sync caller -> sync function in threadpool (blocks)
+  result = dvt.task.to_thread_blocking(fetch_data, "target.json")
+
+  # Sync caller -> batch map in threadpool (blocks, bounded concurrency)
+  results = dvt.task.map_blocking(fetch_data, ["a.json", "b.json"], max_concurrency=4)
+
+  # run an async coroutine from sync code
+  value = dvt.task.run_blocking(fetch_data_async())
+```
+
+Async (use `async with` in async applications):
+
+```python
+async with Dovetail() as dvt:
+  # schedule coroutines and await
+  tasks = [dvt.task.schedule(fetch_async(i)) for i in items]
+  results = await asyncio.gather(*tasks)
+```
+
+Manual / library patterns (caller-managed ownership):
+
+```py
+# Manual creation: by default Dovetail will attempt to shutdown on
+# interpreter exit and on SIGINT/SIGTERM. You can opt out by passing
+# `shutdown_on_exit=False` when constructing the instance.
+dvt = Dovetail()  # shutdown_on_exit enabled by default
+try:
+  results = dvt.task.map_blocking(fetch, items)
+finally:
+  # explicit shutdown is still allowed and idempotent
+  dvt.shutdown()
+
+# Library-author pattern (prefer caller-managed instance when possible)
+def process(items, dvt: Optional[Dovetail] = None):
+  if dvt is None:
+    with Dovetail() as _dvt:
+      return _dvt.task.map_blocking(worker, items)
+  return dvt.task.map_blocking(worker, items)
+```
+
+> **Note:** `Dovetail` will, by default, register a best-effort shutdown
+> handler that calls `shutdown()` on interpreter exit and when `SIGINT` or
+> `SIGTERM` are received. This is opt-outable via `shutdown_on_exit=False`.
+> Explicitly calling `dvt.shutdown()` is still supported and idempotent.
+>
+> Sync context manager (recommended for synchronous code):
+> ```python
+> with Dovetail(max_workers=8) as dvt:
+>     results = dvt.task.map_blocking(fetch, items)
+> # threadpool shut down on block exit
+> ```
+>
+> Async context manager (recommended for async code):
+> ```python
+> async def main():
+>     async with Dovetail() as dvt:
+>         tasks = [dvt.task.schedule(coro(i)) for i in items]
+>         await asyncio.gather(*tasks)
+> # __aexit__ runs shutdown off the event loop to avoid blocking
+> ```
+>
+> Implementation note: `Dovetail` supports both `__enter__/__exit__` and
+> `__aenter__/__aexit__`. The async exit runs `shutdown()` in a background
+> executor to avoid blocking the running loop. `shutdown()` is idempotent and
+> safe to call multiple times.
+
+
+## API Summary
+
+**Task execution**
+
+- `dvt.task.to_thread(func, *args, **kwargs)` — await a sync callable in Dovetail's threadpool from async code; supports default timeout/retry settings.
+- `dvt.task.to_thread_blocking(func, *args, **kwargs)` — synchronous wrapper for `to_thread` when you are not already in an event loop.
+- `dvt.task.schedule(coro_or_callable, *args, **kwargs)` — create and return an `asyncio.Task` from a coroutine object, async function, or sync callable.
+- `dvt.task.run_blocking(func_or_coro, *args, **kwargs)` — run async or sync work from synchronous code. Do not call from inside a running event loop.
+- `dvt.task.map_blocking(func, items, max_concurrency=None, return_exceptions=False)` — run an ordered parallel map over `items` using the threadpool.
+
+**Events**
+
+- `dvt.events.on_queued(...)` — fires when a task is queued.
+- `dvt.events.on_start(...)` — fires when a task starts executing.
+- `dvt.events.on_end(...)` — fires when a task resolves (including after retries).
+- `dvt.events.on_error(...)` — fires when a task raises an exception.
+- `dvt.events.on_retry(...)` — fires on each retry attempt.
+- `dvt.events.on_cancel(...)` — fires when a task is cancelled.
+- `dvt.events.stats()` — returns cumulative counters: `queued`, `started`, `done`, `error`, `retries`, `throttled`.
+
+**Registry (auto-registration)**
+
+- `dovetail` now exposes a lightweight registry to track active `Dovetail` instances. By default `Dovetail(..., auto_register=True)` will register itself with the package registry so applications can perform coordinated shutdown.
+- Public helpers:
+  - `from dovetail import register, unregister, list_active, shutdown_all, set_app_shutdown_hook`
+  - `register(dvt)` — explicitly register an instance (optional; instances auto-register by default).
+  - `unregister(dvt)` — remove from the registry (useful if you manage shutdown yourself).
+  - `list_active()` — return a list of active (live) instances.
+  - `shutdown_all(wait=True)` — best-effort shutdown of all registered instances (useful for app shutdown hooks).
+  - `set_app_shutdown_hook(fn)` — provide an application-level hook that the registry will call during process exit.
+
+Notes:
+- The registry uses weakrefs and logs a warning if a `Dovetail` is garbage-collected without an explicit `shutdown()` call.
+- To opt-out of auto-registration when creating a `Dovetail`, pass `auto_register=False` to the constructor.
+
+All `dvt.events.on_*` methods accept these optional scope parameters:
+
+- `function_target` — only receive events for a specific callable.
+- `instance_target` — only receive events for a specific execution id (available
+  as `id` in the event payload).
+- `allow_reentry=False` — prevents a listener from triggering itself recursively.
+  Set to `True` to allow reentry, bounded by `max_chain_depth`.
+- `max_chain_depth=5` — maximum active callback depth when reentry is enabled.
+
+
+## Detailed Guides
+
+Full, expanded guides live in the repository under [docs/detailed_guide.md](docs/detailed_guide.md#L1).
+
+
+## Development
+
+Run tests locally:
+
+```bash
+python -m pytest -q
+```
+
+Contributions welcome — open an issue or PR.
+
+
+## License
+
+MIT. See `CHANGELOG.md` for release notes.

pydovetail-0.4.0/dovetail/__init__.py

@@ -0,0 +1,25 @@
+"""
+Package exports.
+
+This package intentionally does not provide a module-level `dovetail`
+instance. Consumers should instantiate `Dovetail()` where they need
+an executor helper so they control lifetimes and configuration.
+"""
+
+from .dovetail import Dovetail
+from ._register import (
+	register,
+	unregister,
+	list_active,
+	shutdown_all,
+	set_app_shutdown_hook,
+)
+
+__all__ = [
+	"Dovetail",
+	"register",
+	"unregister",
+	"list_active",
+	"shutdown_all",
+	"set_app_shutdown_hook",
+]