From fb23a9d8d469fd56ae0cf23181bc950233fab84e Mon Sep 17 00:00:00 2001 From: Tyler Goodlet Date: Thu, 25 Feb 2021 23:49:56 -0500 Subject: [PATCH 1/5] Try out sphinx-book-theme --- docs/conf.py | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ede4ad4..224cad7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,7 +54,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_typlog_theme' +html_theme = 'sphinx_book_theme' pygments_style = 'sphinx' @@ -62,20 +62,31 @@ pygments_style = 'sphinx' # further. For a list of options available for each theme, see the # documentation. html_theme_options = { - 'logo': 'tractor_logo_side.svg', - 'description': 'Structured concurrent "actors"', - 'github_user': 'goodboy', - 'github_repo': 'tractor', + # 'logo': 'tractor_logo_side.svg', + # 'description': 'Structured concurrent "actors"', + 'repository_url': "https://github.com/goodboy/tractor", + 'use_repository_button': True, } html_sidebars = { "**": [ - 'logo.html', - 'github.html', - 'relations.html', - 'searchbox.html' - ] + 'globaltoc.html', + 'sbt-sidebar-nav.html', + ], + # 'logo.html', + # 'github.html', + # 'relations.html', + # 'searchbox.html' + # ] } +# doesn't seem to work? +extra_navbar = "

nextttt-gennnnn

" + +html_title = 'tractor' +html_logo = '_static/tractor_logo_side.svg' +html_favicon = '_static/tractor_logo_side.svg' +show_navbar_depth = 1 + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". From 5528a4eb45c877a86d3026cf6f789bad1b415d01 Mon Sep 17 00:00:00 2001 From: Tyler Goodlet Date: Sun, 28 Feb 2021 20:40:44 -0500 Subject: [PATCH 2/5] Attempt configuring sphinx-book-theme --- docs/conf.py | 21 +++++++++++++-------- docs/index.rst | 9 ++++----- requirements-docs.txt | 2 +- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 224cad7..f0452d7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,7 +56,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # html_theme = 'sphinx_book_theme' -pygments_style = 'sphinx' +pygments_style = 'algol_nu' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -64,13 +64,18 @@ pygments_style = 'sphinx' html_theme_options = { # 'logo': 'tractor_logo_side.svg', # 'description': 'Structured concurrent "actors"', - 'repository_url': "https://github.com/goodboy/tractor", - 'use_repository_button': True, + "repository_url": "https://github.com/goodboy/tractor", + "use_repository_button": True, + "home_page_in_toc": False, + "show_toc_level": 1, + "path_to_docs": "docs", + } html_sidebars = { "**": [ - 'globaltoc.html', - 'sbt-sidebar-nav.html', + "sbt-sidebar-nav.html", + "sidebar-search-bs.html", + # 'localtoc.html', ], # 'logo.html', # 'github.html', @@ -80,12 +85,12 @@ html_sidebars = { } # doesn't seem to work? -extra_navbar = "

nextttt-gennnnn

" +# extra_navbar = "

nextttt-gennnnn

" -html_title = 'tractor' +html_title = '' html_logo = '_static/tractor_logo_side.svg' html_favicon = '_static/tractor_logo_side.svg' -show_navbar_depth = 1 +# show_navbar_depth = 1 # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/index.rst b/docs/index.rst index 4ed5a47..2bdf993 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,12 +3,13 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -tractor -======= +``tractor`` +=========== + A `structured concurrent`_, async-native "`actor model`_" built on trio_ and multiprocessing_. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: .. _actor model: https://en.wikipedia.org/wiki/Actor_model @@ -58,8 +59,6 @@ say hi, please feel free to ping me on the `trio gitter channel`_! .. _trio gitter channel: https://gitter.im/python-trio/general -.. contents:: - Philosophy ---------- diff --git a/requirements-docs.txt b/requirements-docs.txt index 5c53ba7..2c88be7 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,2 +1,2 @@ sphinx -sphinx_typlog_theme \ No newline at end of file +sphinx_book_theme From 558d546c8f1dfdf6b559105aacabfcf489b379d0 Mon Sep 17 00:00:00 2001 From: Tyler Goodlet Date: Mon, 31 May 2021 08:37:44 -0400 Subject: [PATCH 3/5] Bump readme for #210 --- docs/README.rst | 78 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 53 insertions(+), 25 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index 27b4d40..f632ffb 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -3,18 +3,15 @@ |gh_actions| |docs| -.. _actor model: https://en.wikipedia.org/wiki/Actor_model -.. _trio: https://github.com/python-trio/trio -.. _multi-processing: 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 a `structured concurrent`_, multi-processing_ runtime built on trio_. +Fundamentally ``tractor`` gives you parallelism via ``trio``-"*actors*": +our nurseries_ let you spawn new Python processes which each run a ``trio`` +scheduled runtime - a call to ``trio.run()``. -``tractor`` is a `structured concurrent`_ "`actor model`_" built on trio_ and multi-processing_. - -We pair structured concurrency and true multi-core parallelism with -the aim of being the multi-processing framework *you always wanted*. +We believe the system adhere's to the `3 axioms`_ of an "`actor model`_" +but likely *does not* look like what *you* probably think an "actor +model" looks like, and that's *intentional*. 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`_. @@ -23,12 +20,13 @@ A great place to start is the `trio docs`_ and this `blog post`_. Features -------- - **It's just** a ``trio`` API -- Infinitely nesteable process trees -- Built-in APIs for inter-process streaming -- A (first ever?) "native" multi-core debugger for Python using `pdb++`_ -- Support for multiple process spawning backends -- A modular transport layer, allowing for custom serialization, +- *Infinitely nesteable* process trees +- Built-in inter-process streaming APIs +- A (first ever?) "native" multi-core debugger UX for Python using `pdb++`_ +- Support for a swappable, OS specific, process spawning layer +- A modular transport stack, allowing for custom serialization, communications protocols, and environment specific IPC primitives +- `structured concurrency`_ from the ground up Run a func in a process @@ -244,19 +242,41 @@ distributed Python. You can think of it as a ``trio`` stdlib's ``multiprocessing`` but built on async programming primitives from the ground up. -``tractor``'s nurseries let you spawn ``trio`` *"actors"*: new Python -processes which each run a ``trio`` scheduled runtime - a call to ``trio.run()``. - Don't be scared off by this description. ``tractor`` **is just** ``trio`` but with nurseries for process management and cancel-able streaming IPC. If you understand how to work with ``trio``, ``tractor`` will give you -the parallelism you've been missing. +the parallelism you may have been needing. -"Actors" communicate by exchanging asynchronous messages_ and avoid -sharing state. The intention of this model is to allow for highly -distributed software that, through the adherence to *structured -concurrency*, results in systems which fail in predictable and -recoverable ways. + +Wait, huh?! I thought "actors" have messages, and mailboxes and stuff?! +----------------------------------------------------------------------- +Let's stop and ask how many canon actor model papers have you actually read? + +From the author's mouth, **the only thing required** is `adherance to`_ +the `3 axioms`_, *and that's it*. + +To get more fired up on the matter, please read issue 1 and issue 2. + +*News flash*: many "actor systems" people create aren't really "actor +models" since they don't adhere to the `3 axioms`_. Despite not looking +like an one from the outside ``tractor`` **does seem to adhere** to the +base requirements to be considered an "actor model". + +If you want do debate this further please feel free to chime in on our +chat or discuss on one of the above issues **after you've read +everything in them**. + +Let's keep our parlance simple +****************************** +The main goal of ``tractor`` besides the above feature set is is to +allow for highly distributed software that, through the adherence to +*structured concurrency*, results in systems which fail in predictable, +recoverable and maybe even understandable ways. + +Whether or not ``tractor`` has "actors" underneath should be mostly +irrelvant to users other then for referring to the interactions of +our primary runtime primitives: a Python process + `trio.run()` + +surrounding IPC machinery as *single-units-of-abstraction*. What's on the TODO: @@ -278,6 +298,15 @@ say hi, please feel free to reach us in our `matrix channel`_. If matrix seems too hip, we're also mostly all in the the `trio gitter channel`_! +.. _nurseries: https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/#nurseries-a-structured-replacement-for-go-statements +.. _actor model: https://en.wikipedia.org/wiki/Actor_model +.. _trio: https://github.com/python-trio/trio +.. _multi-processing: 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 +.. _3 axioms: https://www.youtube.com/watch?v=7erJ1DV_Tlo&t=162s +.. _adherance to: https://www.youtube.com/watch?v=7erJ1DV_Tlo&t=1821s .. _trio gitter channel: https://gitter.im/python-trio/general .. _matrix channel: https://matrix.to/#/!tractor:matrix.org .. _pdb++: https://github.com/pdbpp/pdbpp @@ -286,7 +315,6 @@ channel`_! .. _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/ .. _trio-parallel: https://github.com/richardsheridan/trio-parallel From 4ee7db338d2de7c0b97d35cada563b8530d5fe59 Mon Sep 17 00:00:00 2001 From: Tyler Goodlet Date: Mon, 31 May 2021 08:56:36 -0400 Subject: [PATCH 4/5] Fill out the rant a bit more --- docs/README.rst | 53 ++++++++++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 18 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index f632ffb..e432b99 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -249,34 +249,51 @@ the parallelism you may have been needing. Wait, huh?! I thought "actors" have messages, and mailboxes and stuff?! ------------------------------------------------------------------------ +*********************************************************************** Let's stop and ask how many canon actor model papers have you actually read? From the author's mouth, **the only thing required** is `adherance to`_ the `3 axioms`_, *and that's it*. -To get more fired up on the matter, please read issue 1 and issue 2. +To get more fired up on the matter, please read these issues: -*News flash*: many "actor systems" people create aren't really "actor -models" since they don't adhere to the `3 axioms`_. Despite not looking -like an one from the outside ``tractor`` **does seem to adhere** to the -base requirements to be considered an "actor model". +- https://github.com/goodboy/tractor/issues/210 +- https://github.com/goodboy/tractor/issues/18 + +*News flash*: many "actor systems" aren't really "actor models" since +they **don't adhere** to the `3 axioms`_ and pay even less attention to +the problem of *unbounded non-determinism* (which was the whole point +for creation of the model in the first place). + +Again, ``tractor`` does seem to adhere to the base requirements of +an "actor model":: + + In response to a message, an actor may: + + - send a finite number of new messages + - create a finite number of new actors + - designate a new behavior to process subsequent messages + +``tractor`` requires *no further api changes* to accomplish this. If you want do debate this further please feel free to chime in on our -chat or discuss on one of the above issues **after you've read -everything in them**. - -Let's keep our parlance simple -****************************** -The main goal of ``tractor`` besides the above feature set is is to -allow for highly distributed software that, through the adherence to -*structured concurrency*, results in systems which fail in predictable, -recoverable and maybe even understandable ways. +chat or discuss on one of the above issues *after you've read +everything in them*. +Let's clarify our parlance +************************** Whether or not ``tractor`` has "actors" underneath should be mostly -irrelvant to users other then for referring to the interactions of -our primary runtime primitives: a Python process + `trio.run()` + -surrounding IPC machinery as *single-units-of-abstraction*. +irrelevant to users other then for referring to the interactions of our +primary runtime primitives: each Python process + ``trio.run()`` ++ surrounding IPC machinery. These are our high level, base +*runtime-units-of-abstraction* which both *are* (as much as they can +be in Python) and will be referred to as our *"actors"*. + +The main goal of ``tractor`` is is to allow for highly distributed +software that, through the adherence to *structured concurrency*, +results in systems which fail in predictable, recoverable and maybe even +understandable ways; being an "actor model" is just one way to describe +properties of the system. What's on the TODO: From 0301d105ddd66d37f99a56e28b873d6118ffcdbd Mon Sep 17 00:00:00 2001 From: Tyler Goodlet Date: Mon, 14 Jun 2021 06:41:10 -0400 Subject: [PATCH 5/5] Better rant flow as per suggestions --- docs/README.rst | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index e432b99..ff09ab2 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -250,23 +250,17 @@ the parallelism you may have been needing. Wait, huh?! I thought "actors" have messages, and mailboxes and stuff?! *********************************************************************** -Let's stop and ask how many canon actor model papers have you actually read? +Let's stop and ask how many canon actor model papers have you actually read ;) + +From our experience many "actor systems" aren't really "actor models" +since they **don't adhere** to the `3 axioms`_ and pay even less +attention to the problem of *unbounded non-determinism* (which was the +whole point for creation of the model in the first place). From the author's mouth, **the only thing required** is `adherance to`_ the `3 axioms`_, *and that's it*. -To get more fired up on the matter, please read these issues: - -- https://github.com/goodboy/tractor/issues/210 -- https://github.com/goodboy/tractor/issues/18 - -*News flash*: many "actor systems" aren't really "actor models" since -they **don't adhere** to the `3 axioms`_ and pay even less attention to -the problem of *unbounded non-determinism* (which was the whole point -for creation of the model in the first place). - -Again, ``tractor`` does seem to adhere to the base requirements of -an "actor model":: +``tractor`` adheres to said base requirements of an "actor model":: In response to a message, an actor may: @@ -274,11 +268,16 @@ an "actor model":: - create a finite number of new actors - designate a new behavior to process subsequent messages -``tractor`` requires *no further api changes* to accomplish this. + +**and** requires *no further api changes* to accomplish this. If you want do debate this further please feel free to chime in on our -chat or discuss on one of the above issues *after you've read -everything in them*. +chat or discuss on one of the following issues *after you've read +everything in them*:: + +- https://github.com/goodboy/tractor/issues/210 +- https://github.com/goodboy/tractor/issues/18 + Let's clarify our parlance **************************