Skip to content

Commit cfdd395

Browse files
glopesdevglopesdev
committed
Add main conceptual overview and example workflows
1 parent ab2d991 commit cfdd395

16 files changed

+285
-6
lines changed

‎docs/articles/modules.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Dynamic Modules
2+
3+
The Python Scripting package allows you to define dynamic modules at runtime. This is useful if you need to isolate specific scripts, or keep track of state variables evolving independently in different parts of the workflow.
4+
5+
To create a new module, you can use the [CreateModule](xref:Bonsai.Scripting.Python.CreateModule) operator together with a [ResourceSubject](xref:Bonsai.Reactive.ResourceSubject):
6+
7+
:::workflow
8+
![CreateModule](~/workflows/create-module.bonsai)
9+
:::
10+
11+
> [!Warning]
12+
> Make sure to always pair the [CreateModule](xref:Bonsai.Scripting.Python.CreateModule) operator together with a [ResourceSubject](xref:Bonsai.Reactive.ResourceSubject) to ensure that your module is correctly destroyed when your workflow terminates.
13+
14+
Once the module is declared, you can now pass it to any of your Python operators to make sure they run their code in the correct scope:
15+
16+
:::workflow
17+
![ShareModule](~/workflows/share-module.bonsai)
18+
:::
19+
20+
> [!Tip]
21+
> You can think of modules as "objects", as they encapsulate all their state variables inside a unique Python scope.
22+
23+
> [!Warning]
24+
> If you do not provide a specific module for a Python scripting operator to run in, it will always run in the global Python main module.

‎docs/articles/overview.md

Lines changed: 59 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,65 @@
22
uid: overview
33
---
44

5-
Bonsai.Scripting.Python is a [Bonsai](https://bonsai-rx.org/) interface for the [Python](https://www.python.org/) programming language. It uses [Python.NET](https://pythonnet.github.io/pythonnet/) under the hood to provide a seamless integration between the CPython runtime and data streaming in a Bonsai workflow.
5+
The Python Scripting package is a [Bonsai](https://bonsai-rx.org/) interface for the [Python](https://www.python.org/) programming language. It uses [Python.NET](https://pythonnet.github.io/pythonnet/) under the hood to provide a seamless integration between the CPython runtime and data streaming in a Bonsai workflow.
66

7-
You can use Bonsai.Scripting.Python to run native Python scripts, import any module available to Python, and read or write to any variable in a named scope. The package is designed to work with any Python version from 3.7 onwards, and you can also use it in combination with [Python virtual environments](https://docs.python.org/3/tutorial/venv.html) to fully isolate your project dependencies.
7+
You can use the Python Scripting package to run native Python scripts, import any module available to Python, and read or write to any variable in a named scope. The package is designed to work with any Python version from 3.7 onwards, and you can also use it in combination with [Python virtual environments](https://docs.python.org/3/tutorial/venv.html) to fully isolate your project dependencies.
88

9-
## Installing the package
9+
## How to install
1010

11-
To install Bonsai.Scripting.Python use the Bonsai package manager and search for the **Bonsai - Python Scripting** package.
11+
1. Download [Bonsai](https://bonsai-rx.org/).
12+
2. From the package manager, search and install the **Bonsai - Python Scripting** package.
13+
14+
## Create a Python environment
15+
16+
In addition to the Python Scripting package you need to have a version of [Python](https://www.python.org/) installed in your system. We recommend installing the official distributions and using `venv` to create virtual environments to run your specific projects.
17+
18+
To create a virtual environment you can run the following command from inside the folder where you want to install the environment:
19+
20+
```ps
21+
python -m venv example-env
22+
```
23+
24+
## Create a Python runtime
25+
26+
The [CreateRuntime](xref:Bonsai.Scripting.Python.CreateRuntime) node launches the Python kernel and creates the main global scope for running Python scripts. You must set the [PythonHome](xref:Bonsai.Scripting.Python.CreateRuntime.PythonHome) property to the environment folder (or your Python home directory) before starting the workflow:
27+
28+
:::workflow
29+
![CreateRuntime](~/workflows/create-runtime.bonsai)
30+
:::
31+
32+
Alternatively, you can activate the virtual environment *before* starting Bonsai. In this case you do not need to specify the Python home directory.
33+
34+
> [!Tip]
35+
> You can set the value of the [**ScriptPath**](xref:Bonsai.Scripting.Python.CreateRuntime.ScriptPath) property to specify a main script that will be run when the Python runtime is initialized. This script can be used to import all the main modules to be used in your workflow, or initialize any state variables to be manipulated during execution.
36+
37+
## Run Python code
38+
39+
The [Eval](xref:Bonsai.Scripting.Python.Eval) operator can be used anywhere in your workflow to interact with the Python runtime, just as if you were writing code in the Python REPL:
40+
41+
:::workflow
42+
![HelloPython](~/workflows/hello-python.bonsai)
43+
:::
44+
45+
You can also use the [Exec](xref:Bonsai.Scripting.Python.Exec) operator to run Python statements dynamically, for example to import new modules:
46+
47+
:::workflow
48+
![HelloPython](~/workflows/exec-eval.bonsai)
49+
:::
50+
51+
## Read and write state variables
52+
53+
To interface with Python state variables, you can use the [Get](xref:Bonsai.Scripting.Python.Get) and [Set](xref:Bonsai.Scripting.Python.Set) operators:
54+
55+
:::workflow
56+
![GetSet](~/workflows/get-set.bonsai)
57+
:::
58+
59+
> [!Warning]
60+
> All the operators in the Python Scripting package run under the Python [Global Interpreter Lock](https://docs.python.org/3/glossary.html#term-global-interpreter-lock). This means that although execution of Python code can be triggered asynchronously anywhere in the workflow, there will be a bottleneck when accessing the interpreter. Because of this, we currently do not recommend running large number of parallel calls to Python.
61+
62+
## Scripting Extensions
63+
64+
Custom script files can be executed when creating the Python runtime with [CreateRuntime](xref:Bonsai.Scripting.Python.CreateRuntime) or when creating a new module with [CreateModule](xref:Bonsai.Scripting.Python.CreateModule).
65+
66+
To edit script files we recommend [Visual Studio Code](https://code.visualstudio.com/) and the [Python extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-python.python). If both your virtual environment and your custom Python scripts are placed relative to your main workflow, VS Code can be launched from the Bonsai IDE and will be able to correctly pick up the right environment when editing the scripts.

‎docs/articles/toc.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,6 @@
22
href: intro.md
33
items:
44
- name: Quickstart
5-
href: intro.md
5+
href: intro.md
6+
- name: Dynamic Modules
7+
href: modules.md

‎docs/templates/html/styles/main.css

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@
2020

2121
.workflow {
2222
border: 1px solid #e3e3e3;
23-
padding: 1px;
23+
padding: 2px;
24+
margin-bottom: 10px;
2425
}
2526

2627
.workflow > p > img {

‎docs/workflows/create-module.bonsai

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<WorkflowBuilder Version="2.7.1"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
5+
xmlns:rx="clr-namespace:Bonsai.Reactive;assembly=Bonsai.Core"
6+
xmlns="https://bonsai-rx.org/2018/workflow">
7+
<Workflow>
8+
<Nodes>
9+
<Expression xsi:type="Combinator">
10+
<Combinator xsi:type="py:CreateModule">
11+
<py:Name>NewModule</py:Name>
12+
</Combinator>
13+
</Expression>
14+
<Expression xsi:type="rx:ResourceSubject">
15+
<Name>NewModule</Name>
16+
</Expression>
17+
</Nodes>
18+
<Edges>
19+
<Edge From="0" To="1" Label="Source1" />
20+
</Edges>
21+
</Workflow>
22+
</WorkflowBuilder>

‎docs/workflows/create-module.svg

Lines changed: 3 additions & 0 deletions
Loading

‎docs/workflows/create-runtime.bonsai

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<WorkflowBuilder Version="2.7.1"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
5+
xmlns="https://bonsai-rx.org/2018/workflow">
6+
<Workflow>
7+
<Nodes>
8+
<Expression xsi:type="Combinator">
9+
<Combinator xsi:type="py:CreateRuntime">
10+
<py:PythonHome>example-env</py:PythonHome>
11+
</Combinator>
12+
</Expression>
13+
</Nodes>
14+
<Edges />
15+
</Workflow>
16+
</WorkflowBuilder>

‎docs/workflows/create-runtime.svg

Lines changed: 3 additions & 0 deletions
Loading

‎docs/workflows/exec-eval.bonsai

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<WorkflowBuilder Version="2.7.1"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
5+
xmlns="https://bonsai-rx.org/2018/workflow">
6+
<Workflow>
7+
<Nodes>
8+
<Expression xsi:type="Combinator">
9+
<Combinator xsi:type="py:CreateRuntime">
10+
<py:PythonHome>example-env</py:PythonHome>
11+
</Combinator>
12+
</Expression>
13+
<Expression xsi:type="Combinator">
14+
<Combinator xsi:type="py:Exec">
15+
<py:Script>from datetime import datetime</py:Script>
16+
</Combinator>
17+
</Expression>
18+
<Expression xsi:type="Combinator">
19+
<Combinator xsi:type="py:Eval">
20+
<py:Expression>print(datetime.now())</py:Expression>
21+
</Combinator>
22+
</Expression>
23+
</Nodes>
24+
<Edges>
25+
<Edge From="0" To="1" Label="Source1" />
26+
<Edge From="1" To="2" Label="Source1" />
27+
</Edges>
28+
</Workflow>
29+
</WorkflowBuilder>

0 commit comments

Comments
 (0)