goodboy
/
tractor
1
0
Fork 2
Code Issues 5 Pull Requests 6 Packages Projects Releases Wiki Activity
tractor/tractor/trionics/__init__.py

44 lines
1.4 KiB
Python
Raw Normal View History

Re-license code base for distribution under AGPL This commit obviously denotes a re-license of all applicable parts of the code base. Acknowledgement of this change was completed in #274 by the majority of the current set of contributors. From here henceforth all changes will be AGPL licensed and distributed. This is purely an effort to maintain the same copy-left policy whilst closing the (perceived) SaaS loophole the GPL allows for. It is merely for this loophole: to avoid code hiding by any potential "network providers" who are attempting to use the project to make a profit without either compensating the authors or re-distributing their changes. I thought quite a bit about this change and can't see a reason not to close the SaaS loophole in our current license. We still are (hard) copy-left and I plan to keep the code base this way for a couple reasons: - The code base produces income/profit through parent projects and is demonstrably of high value. - I believe firms should not get free lunch for the sake of "contributions from their employees" or "usage as a service" which I have found to be a dubious argument at best. - If a firm who intends to profit from the code base wants to use it they can propose a secondary commercial license to purchase with the proceeds going to the project's authors under some form of well defined contract. - Many successful projects like Qt use this model; I see no reason it can't work in this case until such a time as the authors feel it should be loosened. There has been detailed discussion in #103 on licensing alternatives. The main point of this AGPL change is to protect the code base for the time being from exploitation while it grows and as we move into the next phase of development which will include extension into the multi-host distributed software space.
2021-12-13 18:08:32 +00:00
# tractor: structured concurrent "actors".
# Copyright 2018-eternity Tyler Goodlet.
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
Start `trionics` sub-pkg with `async_enter_all()` Since it seems we're building out more and more higher level primitives in order to support certain parallel style actor trees and messaging patterns (eg. task broadcast channels), we might as well start a new sub-package for purely `trio` constructions. We hereby dub this the realm of `trionics` (like electronics but for trios instead of electrons). To kick things off, add an `async_enter_all()` concurrent exit-stack-like context manager API which will concurrently spawn a sequence of provided async context managers and deliver their ordered results but with proper support for `trio` cancellation semantics. The stdlib's `AsyncExitStack` is not compatible with nurseries not `trio` tasks (which are cancelled) since as task will be suspended on the stack after push and does not ever hit a checkpoint until the stack is closed.
2021-10-04 15:02:51 +00:00
'''
Sugary patterns for trio + tractor designs.
'''
Add `maybe_open_context()` an actor wide task-resource cache
2021-10-27 18:01:39 +00:00
from ._mngrs import (
Use `import <blah> as blah` over `__all__` in `.trionics`
2024-01-23 16:09:38 +00:00
gather_contexts as gather_contexts,
maybe_open_context as maybe_open_context,
maybe_open_nursery as maybe_open_nursery,
Add `maybe_open_context()` an actor wide task-resource cache
2021-10-27 18:01:39 +00:00
)
from ._broadcast import (
Use `import <blah> as blah` over `__all__` in `.trionics`
2024-01-23 16:09:38 +00:00
AsyncReceiver as AsyncReceiver,
broadcast_receiver as broadcast_receiver,
BroadcastReceiver as BroadcastReceiver,
Lagged as Lagged,
Add `maybe_open_context()` an actor wide task-resource cache
2021-10-27 18:01:39 +00:00
)
Draft some eg collapsing helpers Inside a new `.trionics._beg` and exposed from the subpkg ns in anticipation of the `strict_exception_groups=False` being removed by `trio` in py 3.15. Notes, - mk an embedded single-exc "extractor" using a `BaseExceptionGroup.exceptions` length check, when 1 return the lone child. - use the above in a new `@acm`, async bc it's most likely to be composed in an `async with` tuple-style sequence block, called `collapse_eg()` which acts a one line "absorber" for when the above mentioned flag is no logner supported by `trio.open_nursery()`. All untested atm fwiw.. but soon to be used in our test suite(s) likely!
2025-03-03 23:01:16 +00:00
from ._beg import (
collapse_eg as collapse_eg,
Rework `collapse_eg()` to NOT use `except*`.. Since it turns out the semantics are basically inverse of normal `except` (particularly for re-raising) which is hard to get right, and bc it's a lot easier to just delegate to what `trio` already has behind the `strict_exception_groups=False` setting, Bp I added a rant here which will get removed shortly likely, but i think going forward recommending against use of `except*` is prudent for anything low level enough in the runtime (like trying to filter begs). Dirty deats, - copy `trio._core._run.collapse_exception_group()` to here with only a slight mod to remove the notes check and tb concatting for the collapse case. - rename `maybe_collapse_eg()` - > `get_collapsed_eg()` and delegate it directly to the former `trio` fn; return `None` when it returns the same beg without collapse. - simplify our own `collapse_eg()` to either raise the collapsed `exc` or original `beg`.
2025-07-25 13:57:20 +00:00
get_collapsed_eg as get_collapsed_eg,
Move `.is_multi_cancelled()` to `.trioniics._beg` Since it's for beg filtering, the current impl should be renamed anyway; it's not just for filtering cancelled excs. Deats, - added a real doc string, links to official eg docs and fixed the return typing. - adjust all internal imports to match.
2025-06-13 03:16:29 +00:00
is_multi_cancelled as is_multi_cancelled,
Draft some eg collapsing helpers Inside a new `.trionics._beg` and exposed from the subpkg ns in anticipation of the `strict_exception_groups=False` being removed by `trio` in py 3.15. Notes, - mk an embedded single-exc "extractor" using a `BaseExceptionGroup.exceptions` length check, when 1 return the lone child. - use the above in a new `@acm`, async bc it's most likely to be composed in an `async with` tuple-style sequence block, called `collapse_eg()` which acts a one line "absorber" for when the above mentioned flag is no logner supported by `trio.open_nursery()`. All untested atm fwiw.. but soon to be used in our test suite(s) likely!
2025-03-03 23:01:16 +00:00
)
Mv `maybe_raise_from_masking_exc()` to `.trionics` Factor the `@acm`-closure it out of the `test_trioisms::test_acm_embedded_nursery_propagates_enter_err` suite for real use internally.
2025-06-15 17:29:34 +00:00
from ._taskc import (
maybe_raise_from_masking_exc as maybe_raise_from_masking_exc,
Add `start_or_cancel()` to `trionics._taskc` Wrapper around `trio.Nursery.start()` that DOESN'T mask out-of-band cancellation as a lossy startup failure. Picks the right re-raise: ambient `Cancelled` when present, the genuine startup-protocol `RuntimeError` otherwise. The problem, - `trio.Nursery.start()` raises a generic `RuntimeError("child exited without calling task_status.started()")` whenever the started task exits BEFORE calling `task_status.started()` — INCLUDING the common case where the child was cancelled out-of-band by an *ancestor* cancel-scope erroring/cancelling. - In that case the original `trio.Cancelled` is swallowed and the caller is left w/ an opaque, root-cause-detached `RuntimeError`. The fix, - Catch the "...started" RTE. - `await trio.lowlevel.checkpoint_if_cancelled()` — re-raises the in-flight `Cancelled` IFF we're under effective cancellation (ancestor-inclusive), carrying trio's auto-generated reason which points at the true root exc. - If we're NOT cancelled the `checkpoint_if_cancelled()` is a cheap no-op and we fall through to re-raise the genuine startup-protocol RTE. Re-export from `tractor.trionics` so callers don't have to reach into `_taskc`. (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code (cherry picked from commit 30e15925bab7f047d4f77d47059c0ab5fd55353e) (cherry picked from commit 2b4589b1ee8106f0969c1c22cbb44bd09da007f9)
2026-05-29 23:20:29 +00:00
start_or_cancel as start_or_cancel,
Mv `maybe_raise_from_masking_exc()` to `.trionics` Factor the `@acm`-closure it out of the `test_trioisms::test_acm_embedded_nursery_propagates_enter_err` suite for real use internally.
2025-06-15 17:29:34 +00:00
)
Add `supervise_run_process` to `trionics._subproc` A `trio.Nursery.start()`-style wrapper around `trio.run_process()` that surfaces rc!=0 errors deterministically, ALWAYS isolates the parent controlling-tty, and optionally live-relays the child's std-streams to `log.<level>` per-line. Suits both short-lived test-runners + long-lived daemons. `supervise_run_process()`, - Deterministic rc!=0: pass `check=False` to `trio` and do our OWN post-drain rc-check from the supervisor coro body AFTER `own_tn.__aexit__` — NOT inside the internal nursery, since that would race-cancel the still-draining relay reader and lose stderr lines. (Re)build + raise a BARE `subprocess.CalledProcessError`: `.stderr=` for programmatic callers + an `add_note()`'d `|_.stderr:` block for human teardown logs. No nursery-eg-wrapped CPE to `collapse_eg` around. - Parent controlling-tty isolation: `stdin=DEVNULL` always, `stdout=DEVNULL` unless relayed/overridden (via `stdout=` kwarg w/ `_UNSET` sentinel so explicit `None` = inherit still works). Prevents a spawned program from clobbering the launching tty's scrollback w/ control-seqs. - Live per-line relay: `relay_stdout=True`/ `relay_stderr=True` → relayed to `log.<relay_level>` (default `'io'`, our custom level 21). Picked to sort just above stdlib `INFO`=20 so it shows at usual `info`/`devx` levels yet stays separately filterable; `runtime`=15 was REJECTED as a default since it'd be silently filtered at usual verbosity — footgun for daemon supervisors whose whole point is visibility. STREAMED, not buffered-until-exit. - Non-blocking `tn.start()` semantics: live `trio.Process` handed up via `task_status.started()` immediately (else `tn.start()` would block till child exit, losing the long-lived-daemon use case). Supervise/relay bg tasks run to completion in this coro. - `**run_process_kwargs` forwarded verbatim (env, shell, cwd, start_new_session, executable, ...); MANAGED keys (`stdin`/`stdout`/`stderr`/`check`) win on conflict. - Crash-handling layer intentionally NOT baked in — compose `maybe_open_crash_handler()` ON TOP at the call-site. `_relay_stream_lines()` helper, - Concurrent pipe-drain reader. MANDATORY whenever piping w/o `capture_*` since nothing else drains the OS pipe — child blocks on `write()` once kernel buf (~64KiB) fills → deadlock. - Modes (combine freely): `emit`-only live relay, `accum`-only silent drain+capture (for the CPE note), or both. Per-line splitting handles cross-chunk residuals + flushes any trailing un-newline-term'd line at EOF. `_add_stderr_note()` helper, - Attaches an indented `|_.stderr:` note to a CPE via `add_note()` for legible rc!=0 reporting at teardown. Tests (`tests/trionics/test_subproc.py`), - Hermetic `trio`-only (no actor-runtime). - `test_stdout_relayed_per_line`: per-line stdout relay. - `test_parent_tty_isolated`: child fd1 is OUR pipe (no `/dev/pts/*`), fd0 pinned to `/dev/null`. - `test_no_deadlock_on_big_unnewlined_output`: 200KiB no-newline output completes under `fail_after(2)` — exercises the concurrent drain (without it, the child blocks at ~64KiB). - `test_stderr_relay_and_cpe_rebuild`: rc!=0 w/ `relay_stderr=True` → bare `CalledProcessError` w/ the `.stderr` note + per-line live relay. - `test_nonrelay_cpe_note`: rc!=0 w/o relay → same deterministic post-drain CPE w/ `.stderr` note (silent drain+capture path). Re-export `supervise_run_process` from `tractor.trionics`. Prompt-IO: ai/prompt-io/claude/20260601T231429Z_0e3e008b_prompt_io.md (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code (cherry picked from commit f595acc76c696317255fca9861d1940603f8d93b) (cherry picked from commit 6df9ee11bc37518f7247806b7c72dfe6e43a315c)
2026-06-01 23:29:46 +00:00
from ._subproc import (
supervise_run_process as supervise_run_process,
)