From 03d07cb12a73fa999414deeda2f4452778294abb Mon Sep 17 00:00:00 2001 From: Tyler Goodlet Date: Mon, 10 Feb 2020 11:49:54 -0500 Subject: [PATCH] Mirror readme off docs intro --- README.rst | 65 +++++++++++++++++++------------------------------- docs/index.rst | 18 +++++++------- 2 files changed, 34 insertions(+), 49 deletions(-) diff --git a/README.rst b/README.rst index 761de3d..23b65e2 100644 --- a/README.rst +++ b/README.rst @@ -1,17 +1,24 @@ tractor ======= -An async-native "`actor model`_" built on trio_ and multiprocessing_. +A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_. +|travis| |docs| -|travis| - -.. |travis| image:: https://img.shields.io/travis/goodboy/tractor/master.svg - :target: https://travis-ci.org/goodboy/tractor +.. toctree:: + :maxdepth: 2 + :caption: Contents: +.. _actor model: https://en.wikipedia.org/wiki/Actor_model +.. _trio: https://github.com/python-trio/trio +.. _multiprocessing: https://en.wikipedia.org/wiki/Multiprocessing +.. _trionic: https://trio.readthedocs.io/en/latest/design.html#high-level-design-principles +.. _async sandwich: https://trio.readthedocs.io/en/latest/tutorial.html#async-sandwich +.. _structured concurrent: https://trio.discourse.group/t/concise-definition-of-structured-concurrency/228 ``tractor`` is an attempt to bring trionic_ `structured concurrency`_ to -distributed multi-core Python. +distributed multi-core Python; it aims to be the Python multi-processing +framework *you always wanted*. ``tractor`` lets you spawn ``trio`` *"actors"*: processes which each run a ``trio`` scheduled task tree (also known as an `async sandwich`_). @@ -23,44 +30,13 @@ many hosts. The first step to grok ``tractor`` is to get the basics of ``trio`` down. A great place to start is the `trio docs`_ and this `blog post`_. -.. _actor model: https://en.wikipedia.org/wiki/Actor_model -.. _trio: https://github.com/python-trio/trio -.. _multiprocessing: https://en.wikipedia.org/wiki/Multiprocessing -.. _trionic: https://trio.readthedocs.io/en/latest/design.html#high-level-design-principles -.. _async sandwich: https://trio.readthedocs.io/en/latest/tutorial.html#async-sandwich -.. _always propagate: https://trio.readthedocs.io/en/latest/design.html#exceptions-always-propagate -.. _causality: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#c-c-c-c-causality-breaker -.. _shared nothing architecture: https://en.wikipedia.org/wiki/Shared-nothing_architecture -.. _cancellation: https://trio.readthedocs.io/en/latest/reference-core.html#cancellation-and-timeouts -.. _channels: https://en.wikipedia.org/wiki/Channel_(programming) -.. _chaos engineering: http://principlesofchaos.org/ .. _messages: https://en.wikipedia.org/wiki/Message_passing .. _trio docs: https://trio.readthedocs.io/en/latest/ .. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ .. _structured concurrency: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ - - -Philosophy ----------- -``tractor`` aims to be the Python multi-processing framework *you always wanted*. - -Its tenets non-comprehensively include: - -- strict adherence to the `concept-in-progress`_ of *structured concurrency* -- no spawning of processes *willy-nilly*; causality_ is paramount! -- (remote) errors `always propagate`_ back to the parent supervisor -- verbatim support for ``trio``'s cancellation_ system -- `shared nothing architecture`_ -- no use of *proxy* objects or shared references between processes -- an immersive debugging experience -- anti-fragility through `chaos engineering`_ - - -.. warning:: ``tractor`` is in alpha-alpha and is expected to change rapidly! - Expect nothing to be set in stone. Your ideas about where it should go - are greatly appreciated! - -.. _concept-in-progress: https://trio.discourse.group/t/structured-concurrency-kickoff/55 +.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts +.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony +.. _async generators: https://www.python.org/dev/peps/pep-0525/ Install @@ -80,3 +56,12 @@ community). If you want to help, have suggestions or just want to say hi, please feel free to ping me on the `trio gitter channel`_! .. _trio gitter channel: https://gitter.im/python-trio/general +A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_. + + +.. |travis| image:: https://img.shields.io/travis/goodboy/tractor/master.svg + :target: https://travis-ci.org/goodboy/tractor + +.. |docs| image:: https://readthedocs.org/projects/tractor/badge/?version=latest + :target: https://tractor.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status diff --git a/docs/index.rst b/docs/index.rst index dbfb56d..45d7698 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,12 +16,6 @@ A `structured concurrent`_, async-native "`actor model`_" built on trio_ and mul .. _multiprocessing: https://en.wikipedia.org/wiki/Multiprocessing .. _trionic: https://trio.readthedocs.io/en/latest/design.html#high-level-design-principles .. _async sandwich: https://trio.readthedocs.io/en/latest/tutorial.html#async-sandwich -.. _always propagate: https://trio.readthedocs.io/en/latest/design.html#exceptions-always-propagate -.. _causality: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#c-c-c-c-causality-breaker -.. _shared nothing architecture: https://en.wikipedia.org/wiki/Shared-nothing_architecture -.. _cancellation: https://trio.readthedocs.io/en/latest/reference-core.html#cancellation-and-timeouts -.. _channels: https://en.wikipedia.org/wiki/Channel_(programming) -.. _chaos engineering: http://principlesofchaos.org/ .. _structured concurrent: https://trio.discourse.group/t/concise-definition-of-structured-concurrency/228 @@ -43,9 +37,6 @@ A great place to start is the `trio docs`_ and this `blog post`_. .. _trio docs: https://trio.readthedocs.io/en/latest/ .. _blog post: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ .. _structured concurrency: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/ -.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts -.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony -.. _async generators: https://www.python.org/dev/peps/pep-0525/ Install @@ -104,6 +95,15 @@ reactive style for IPC. are greatly appreciated! .. _concept-in-progress: https://trio.discourse.group/t/structured-concurrency-kickoff/55 +.. _3 axioms: https://en.wikipedia.org/wiki/Actor_model#Fundamental_concepts +.. _unrequirements: https://en.wikipedia.org/wiki/Actor_model#Direct_communication_and_asynchrony +.. _async generators: https://www.python.org/dev/peps/pep-0525/ +.. _always propagate: https://trio.readthedocs.io/en/latest/design.html#exceptions-always-propagate +.. _causality: https://vorpus.org/blog/some-thoughts-on-asynchronous-api-design-in-a-post-asyncawait-world/#c-c-c-c-causality-breaker +.. _shared nothing architecture: https://en.wikipedia.org/wiki/Shared-nothing_architecture +.. _cancellation: https://trio.readthedocs.io/en/latest/reference-core.html#cancellation-and-timeouts +.. _channels: https://en.wikipedia.org/wiki/Channel_(programming) +.. _chaos engineering: http://principlesofchaos.org/ Examples