goodboy
/
tractor
1
0
Fork 2
Code Issues 5 Pull Requests 6 Packages Projects Releases Wiki Activity
tractor/docs/api/index.rst

70 lines
1.6 KiB
ReStructuredText
Raw Normal View History

Write the big boi docs content tree Replace the ancient `docs/index.rst` (still teaching `tractor.run()`, `@stream` + arbiters..) with a full ~32 page tree teaching ONLY the current api (`.wait_for_result()`, registrar naming, `@context` + `open_context()` as the core model), - landing: hero example, feature cards + canon links, - `start/`: install + a 4-example quickstart on-ramp, - `explain/`: an "SC across processes" essay distilling the essence per #157's orig ask + a runtime architecture tour, - `guide/`: 12 task-focused pages incl the flagship multi-process debugging walkthrough, `Context` + `MsgStream` deep-dives, cancellation semantics (self-vs-cross cancel rules), discovery, infected `asyncio`, typed msging + the #126 testing-tips page, - `api/`: 10 curated autodoc pages (all targets import-verified vs the reorg'd subpkg tree), - `project/`: changelog include, ported dev-tips (drops old `docs/dev_tips.rst`) + roadmap. Every code block is a `literalinclude` from `examples/` - zero duplication, all CI-run - w/ `d2` figs floated into the RHS margin per the 3-col design. Build is green; the 24 remaining warnings all source from lib docstring rst-isms or legacy `NEWS.rst` content. Substantially resolves #157 (refine round pending); chips at #175 + #126. Prompt-IO: ai/prompt-io/claude/20260611T175152Z_8526985c_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
2026-06-11 19:17:14 +00:00
API reference
=============
This is the curated reference for ``tractor``'s public surface: the
names you can import and lean on without reading runtime internals.
Everything below is re-exported at the top level (``import
tractor``) unless a page says otherwise; subsystems like
Showcase `to_actor.run()` across docs The rendered guides and executable examples still taught the legacy `ActorNursery.run_in_actor()` result-portal model even though #481 adds its blocking, linked-context replacement. Deats, - migrate one-shots to direct results through `to_actor.run()` - preserve named target inputs with `functools.partial()` - use daemon actors where reciprocal dialogs need longer lifetimes - link the new API from core, asyncio and clustering references - retain only explicit legacy/removal notes Prompt-IO: ai/prompt-io/opencode/20260820T023005Z_88a23449_prompt_io.md (this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))
2026-08-20 03:29:02 +00:00
``tractor.msg``, ``tractor.trionics``, ``tractor.to_actor``,
``tractor.to_asyncio``, ``tractor.devx`` and ``tractor.log`` are
importable as submodules.
Write the big boi docs content tree Replace the ancient `docs/index.rst` (still teaching `tractor.run()`, `@stream` + arbiters..) with a full ~32 page tree teaching ONLY the current api (`.wait_for_result()`, registrar naming, `@context` + `open_context()` as the core model), - landing: hero example, feature cards + canon links, - `start/`: install + a 4-example quickstart on-ramp, - `explain/`: an "SC across processes" essay distilling the essence per #157's orig ask + a runtime architecture tour, - `guide/`: 12 task-focused pages incl the flagship multi-process debugging walkthrough, `Context` + `MsgStream` deep-dives, cancellation semantics (self-vs-cross cancel rules), discovery, infected `asyncio`, typed msging + the #126 testing-tips page, - `api/`: 10 curated autodoc pages (all targets import-verified vs the reorg'd subpkg tree), - `project/`: changelog include, ported dev-tips (drops old `docs/dev_tips.rst`) + roadmap. Every code block is a `literalinclude` from `examples/` - zero duplication, all CI-run - w/ `d2` figs floated into the RHS margin per the 3-col design. Build is green; the 24 remaining warnings all source from lib docstring rst-isms or legacy `NEWS.rst` content. Substantially resolves #157 (refine round pending); chips at #175 + #126. Prompt-IO: ai/prompt-io/claude/20260611T175152Z_8526985c_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
2026-06-11 19:17:14 +00:00
``tractor`` is "just trio_" extended across processes: every API
here is designed to keep the structured concurrency (SC) rules you
already know from the `trio docs`_ intact across the process
boundary. If a name isn't documented here it's an internal — expect
it to change without notice B).
.. currentmodule:: tractor
Most-used names at a glance:
.. autosummary::
:nosignatures:
open_root_actor
open_nursery
Showcase `to_actor.run()` across docs The rendered guides and executable examples still taught the legacy `ActorNursery.run_in_actor()` result-portal model even though #481 adds its blocking, linked-context replacement. Deats, - migrate one-shots to direct results through `to_actor.run()` - preserve named target inputs with `functools.partial()` - use daemon actors where reciprocal dialogs need longer lifetimes - link the new API from core, asyncio and clustering references - retain only explicit legacy/removal notes Prompt-IO: ai/prompt-io/opencode/20260820T023005Z_88a23449_prompt_io.md (this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))
2026-08-20 03:29:02 +00:00
to_actor.run
Write the big boi docs content tree Replace the ancient `docs/index.rst` (still teaching `tractor.run()`, `@stream` + arbiters..) with a full ~32 page tree teaching ONLY the current api (`.wait_for_result()`, registrar naming, `@context` + `open_context()` as the core model), - landing: hero example, feature cards + canon links, - `start/`: install + a 4-example quickstart on-ramp, - `explain/`: an "SC across processes" essay distilling the essence per #157's orig ask + a runtime architecture tour, - `guide/`: 12 task-focused pages incl the flagship multi-process debugging walkthrough, `Context` + `MsgStream` deep-dives, cancellation semantics (self-vs-cross cancel rules), discovery, infected `asyncio`, typed msging + the #126 testing-tips page, - `api/`: 10 curated autodoc pages (all targets import-verified vs the reorg'd subpkg tree), - `project/`: changelog include, ported dev-tips (drops old `docs/dev_tips.rst`) + roadmap. Every code block is a `literalinclude` from `examples/` - zero duplication, all CI-run - w/ `d2` figs floated into the RHS margin per the 3-col design. Build is green; the 24 remaining warnings all source from lib docstring rst-isms or legacy `NEWS.rst` content. Substantially resolves #157 (refine round pending); chips at #175 + #126. Prompt-IO: ai/prompt-io/claude/20260611T175152Z_8526985c_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
2026-06-11 19:17:14 +00:00
run_daemon
ActorNursery
Portal
context
Context
MsgStream
open_actor_cluster
find_actor
wait_for_actor
get_registry
current_actor
current_ipc_ctx
is_root_process
get_runtime_vars
RemoteActorError
ContextCancelled
MsgTypeError
pause
post_mortem
Channel
.. toctree::
:maxdepth: 1
:caption: Reference pages
core
context
discovery
errors
msg
trionics
to_asyncio
devx
ipc
Where to next? If you're new, start with the runtime and spawning
APIs in :doc:`/api/core`, then graduate to the inter-actor task
linking model in :doc:`/api/context` — it's the heart of the whole
system.
.. _trio: https://github.com/python-trio/trio
.. _trio docs: https://trio.readthedocs.io/en/latest/