diff --git a/.bonsai/Bonsai.config b/.bonsai/Bonsai.config new file mode 100644 index 0000000..2bd1888 --- /dev/null +++ b/.bonsai/Bonsai.config @@ -0,0 +1,52 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.bonsai/NuGet.config b/.bonsai/NuGet.config new file mode 100644 index 0000000..97e8b73 --- /dev/null +++ b/.bonsai/NuGet.config @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/.bonsai/Setup.cmd b/.bonsai/Setup.cmd new file mode 100644 index 0000000..92d983d --- /dev/null +++ b/.bonsai/Setup.cmd @@ -0,0 +1,4 @@ +@echo off +pushd %~dp0 +powershell -ExecutionPolicy Bypass -File ./Setup.ps1 +popd \ No newline at end of file diff --git a/.bonsai/Setup.ps1 b/.bonsai/Setup.ps1 new file mode 100644 index 0000000..01cfba6 --- /dev/null +++ b/.bonsai/Setup.ps1 @@ -0,0 +1,21 @@ +Push-Location $PSScriptRoot +if (!(Test-Path "./Bonsai.exe")) { + $release = "https://github.com/bonsai-rx/bonsai/releases/latest/download/Bonsai.zip" + $configPath = "./Bonsai.config" + if (Test-Path $configPath) { + [xml]$config = Get-Content $configPath + $bootstrapper = $config.PackageConfiguration.Packages.Package.where{$_.id -eq 'Bonsai'} + if ($bootstrapper) { + $version = $bootstrapper.version + $release = "https://github.com/bonsai-rx/bonsai/releases/download/$version/Bonsai.zip" + } + } + Invoke-WebRequest $release -OutFile "temp.zip" + Move-Item -Path "NuGet.config" "temp.config" -ErrorAction SilentlyContinue + Expand-Archive "temp.zip" -DestinationPath "." -Force + Move-Item -Path "temp.config" "NuGet.config" -Force -ErrorAction SilentlyContinue + Remove-Item -Path "temp.zip" + Remove-Item -Path "Bonsai32.exe" +} +& .\Bonsai.exe --no-editor +Pop-Location \ No newline at end of file diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json new file mode 100644 index 0000000..278b6c7 --- /dev/null +++ b/.config/dotnet-tools.json @@ -0,0 +1,12 @@ +{ + "version": 1, + "isRoot": true, + "tools": { + "docfx": { + "version": "2.75.3", + "commands": [ + "docfx" + ] + } + } +} \ No newline at end of file diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6232b7d..9e0c786 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -8,29 +8,43 @@ jobs: build: runs-on: windows-latest steps: - - uses: actions/checkout@v2 - + - name: Checkout + uses: actions/checkout@v4.1.1 + with: + submodules: true + - name: Setup MSBuild - uses: microsoft/setup-msbuild@v1 - + uses: microsoft/setup-msbuild@v2 + - name: Restore NuGet Packages - run: msbuild -t:restore src\Bonsai.Scripting.Python.sln + run: msbuild -t:restore src/Bonsai.Scripting.Python.sln - - name: Setup DocFX - uses: crazy-max/ghaction-chocolatey@v1 + - name: Build Solution + run: msbuild src/Bonsai.Scripting.Python.sln /p:Configuration=Release + + - name: Setup .NET Core SDK + uses: actions/setup-dotnet@v4.0.0 with: - args: install docfx + dotnet-version: 7.x + + - name: Setup DocFX + run: dotnet tool restore + - name: Setup Bonsai + working-directory: .bonsai + run: .\Setup.ps1 + - name: Build Documentation - run: docfx docs/docfx.json + working-directory: docs + run: .\build.ps1 - name: Checkout gh-pages - uses: actions/checkout@v2 + uses: actions/checkout@v4.1.1 with: ref: gh-pages path: gh-pages - name: Publish to github pages - uses: peaceiris/actions-gh-pages@v3 + uses: peaceiris/actions-gh-pages@v3.9.3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: docs/_site diff --git a/.gitignore b/.gitignore index 93edfd3..6b16b78 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,9 @@ .vs +.venv bin obj +Packages +*.exe +*.exe.* *.user *.suo diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..c8ffa76 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs/bonsai"] + path = docs/bonsai + url = https://github.com/bonsai-rx/docfx-tools diff --git a/docs/articles/intro.md b/docs/articles/intro.md deleted file mode 100644 index 3a0c047..0000000 --- a/docs/articles/intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# Introduction - -[!include[Overview](~/articles/overview.md)] \ No newline at end of file diff --git a/docs/articles/overview.md b/docs/articles/overview.md deleted file mode 100644 index e2b3d9b..0000000 --- a/docs/articles/overview.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -uid: overview ---- - -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. - -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. - -## How to install - -1. Download [Bonsai](https://bonsai-rx.org/). -2. From the package manager, search and install the **Bonsai - Python Scripting** package. - -## Create a Python environment - -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. - -To create a virtual environment you can run the following command from inside the folder where you want to install the environment: - -```ps -python -m venv example-env -``` - -## Create a Python runtime - -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: - -:::workflow -![CreateRuntime](~/workflows/create-runtime.bonsai) -::: - -Alternatively, you can activate the virtual environment *before* starting Bonsai. In this case you do not need to specify the Python home directory. - -> [!Tip] -> 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. - -## Run Python code - -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: - -:::workflow -![HelloPython](~/workflows/hello-python.bonsai) -::: - -You can also use the [Exec](xref:Bonsai.Scripting.Python.Exec) operator to run Python statements dynamically, for example to import new modules: - -:::workflow -![HelloPython](~/workflows/exec-eval.bonsai) -::: - -## Read and write state variables - -To interface with Python state variables, you can use the [Get](xref:Bonsai.Scripting.Python.Get) and [Set](xref:Bonsai.Scripting.Python.Set) operators: - -:::workflow -![GetSet](~/workflows/get-set.bonsai) -::: - -> [!Warning] -> 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. - -## Scripting Extensions - -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). - -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. \ No newline at end of file diff --git a/docs/articles/toc.yml b/docs/articles/toc.yml index cc73e8f..fb44c08 100644 --- a/docs/articles/toc.yml +++ b/docs/articles/toc.yml @@ -1,7 +1,3 @@ - name: Getting Started - href: intro.md - items: - - name: Quickstart - href: intro.md - - name: Dynamic Modules - href: modules.md \ No newline at end of file +- href: ../index.md +- href: modules.md \ No newline at end of file diff --git a/docs/bonsai b/docs/bonsai new file mode 160000 index 0000000..81ef52f --- /dev/null +++ b/docs/bonsai @@ -0,0 +1 @@ +Subproject commit 81ef52fb1741ed607a583aa3b640428d70d896a9 diff --git a/docs/build.ps1 b/docs/build.ps1 new file mode 100644 index 0000000..43edf81 --- /dev/null +++ b/docs/build.ps1 @@ -0,0 +1,2 @@ +.\bonsai\modules\Export-Image.ps1 "..\src\Bonsai.Scripting.Python\bin\Release\net472" +dotnet docfx @args \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json index e112237..6a359cf 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -9,9 +9,7 @@ "src": "../src" } ], - "dest": "api", - "disableGitFeatures": false, - "disableDefaultFilter": false + "dest": "api" } ], "build": { @@ -41,6 +39,7 @@ ] } ], + "output": "_site", "overwrite": [ { "files": [ @@ -52,21 +51,25 @@ ] } ], + "template": [ + "default", + "modern", + "bonsai/template", + "template" + ], "globalMetadata": { + "_appName": "Bonsai - Python Scripting", + "_appTitle": "Bonsai.Scripting.Python", "_enableNewTab": true, + "_enableSearch": true, + "pdf": false, + "_appFooter": "© 2024 Bonsai Foundation CIC and Contributors. Made with docfx", "_gitContribute": { + "repo": "https://github.com/bonsai-rx/python-scripting", "branch": "main", "apiSpecFolder": "docs/apidoc" } }, - "dest": "_site", - "globalMetadataFiles": [], - "fileMetadataFiles": [], - "template": [ - "default", - "templates/html" - ], - "postProcessors": [ "ExtractSearchIndex" ], "markdownEngineName": "markdig", "markdownEngineProperties": { "markdigExtensions": [ @@ -74,11 +77,6 @@ "customcontainers" ] }, - "noLangKeyword": false, - "keepFileLink": false, - "cleanupCacheHistory": false, - "disableGitFeatures": false, - "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ], "xref": [ "https://bonsai-rx.org/docs/xrefmap.yml", "https://horizongir.github.io/reactive/xrefmap.yml" diff --git a/docs/index.md b/docs/index.md index dca2d80..c90101b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,67 @@ -**Bonsai - Python Scripting** Documentation -=========================================== +# Introduction -[!include[Overview](~/articles/overview.md)] +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. + +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. + +## How to install + +1. Download [Bonsai](https://bonsai-rx.org/). +2. From the package manager, search and install the **Bonsai - Python Scripting** package. + +## Create a Python environment + +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. + +To create a virtual environment you can run the following command from inside the folder where you want to install the environment: + +```ps +python -m venv .venv +``` + +## Create a Python runtime + +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: + +:::workflow +![CreateRuntime](~/workflows/create-runtime.bonsai) +::: + +Alternatively, you can activate the virtual environment *before* starting Bonsai. In this case you do not need to specify the Python home directory. + +> [!Tip] +> 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. + +## Run Python code + +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: + +:::workflow +![HelloPython](~/workflows/hello-python.bonsai) +::: + +You can also use the [Exec](xref:Bonsai.Scripting.Python.Exec) operator to run Python statements dynamically, for example to import new modules: + +:::workflow +![HelloPython](~/workflows/exec-eval.bonsai) +::: + +## Read and write state variables + +To interface with Python state variables, you can use the [Get](xref:Bonsai.Scripting.Python.Get) and [Set](xref:Bonsai.Scripting.Python.Set) operators: + +:::workflow +![GetSet](~/workflows/get-set.bonsai) +::: + +> [!Warning] +> All the operators in the Python Scripting package must 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. + +## Scripting Extensions + +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). + +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. > [!Warning] -> These docs are under active development, feel free to contribute by either [raising an issue](https://github.com/bonsai-rx/python-scripting/issues) or following the links to **Improve this Doc**. \ No newline at end of file +> These docs are under active development, feel free to contribute by either [raising an issue](https://github.com/bonsai-rx/python-scripting/issues) or following the links to **Edit this page**. \ No newline at end of file diff --git a/docs/template/public/main.css b/docs/template/public/main.css new file mode 100644 index 0000000..ee56505 --- /dev/null +++ b/docs/template/public/main.css @@ -0,0 +1 @@ +@import "workflow.css"; \ No newline at end of file diff --git a/docs/template/public/main.js b/docs/template/public/main.js new file mode 100644 index 0000000..62c7fa4 --- /dev/null +++ b/docs/template/public/main.js @@ -0,0 +1,13 @@ +import WorkflowContainer from "./workflow.js" + +export default { + defaultTheme: 'light', + iconLinks: [{ + icon: 'github', + href: 'https://github.com/bonsai-rx/python-scripting', + title: 'GitHub' + }], + start: () => { + WorkflowContainer.init(); + } +} \ No newline at end of file diff --git a/docs/templates/html/styles/main.css b/docs/templates/html/styles/main.css deleted file mode 100644 index b53f655..0000000 --- a/docs/templates/html/styles/main.css +++ /dev/null @@ -1,102 +0,0 @@ -.affix { - height: auto; -} - -.sideaffix { - overflow-x: hidden; - overflow-y: auto; -} - -.affix > ul.level1 { - overflow: inherit; -} - -.affix ul > li.active > ul, -.affix ul > li.active > a:before, -.affix ul > li > a:hover:before { - display: block; - white-space: inherit; -} - -.workflow { - border: 1px solid #e3e3e3; - padding: 2px; - margin-bottom: 10px; -} - -.workflow > p > img { - padding-top: 12px; - padding-left: 12px; - padding-right: 12px; -} - -.codeHeader { - box-sizing: content-box; - background-color: #f2f2f2; - color: #171717; - display: flex; - flex-direction: row; - border: 1px solid #e3e3e3; - border-bottom: 0; - margin-top: 16px; - min-height: 30px; -} - -.codeHeader > .language { - padding: 2px 16px; - flex-grow: 1; - line-height: 26px; -} - -.codeHeader > .action { - position: relative; - padding: 2px 10px; - background-color: transparent; - border: 0 solid #e3e3e3; - border-left-width: 1px; - color: #171717; - cursor: pointer; - display: flex; - align-items: center; - line-height: normal; -} - -.codeHeader .glyphicon { - margin-right: 0.25em; -} - -.codeHeader > .action:hover { - background-color: #fafafa; -} - -.codeHeader + pre { - margin-top: 0; - border: 1px solid #e3e3e3; -} - -.codeHeader > .action .successful-copy-alert { - justify-content: center; - align-items: center; - right: 0; - left: 0; - bottom: 0; - top: 0; - position: absolute; - display: flex; - background-color: #128712; - outline-color: #fff; - color: #fff; -} - -.codeHeader > .action .successful-copy-alert.is-transparent { - opacity: 0; - transition: 500ms opacity ease-in-out; -} - -.diagram { - text-align: center; -} - -summary { - display: list-item; -} \ No newline at end of file diff --git a/docs/templates/html/styles/main.js b/docs/templates/html/styles/main.js deleted file mode 100644 index ecefbfc..0000000 --- a/docs/templates/html/styles/main.js +++ /dev/null @@ -1,61 +0,0 @@ -$(function() { - var createCodeHeader = function(text) { - return $( - '
'+ - ' '+ text +''+ - ' '+ - '
' - ); - } - - var setCopyAlert = function($element) { - var copyAlert = $element.find(".successful-copy-alert"); - copyAlert.removeClass("is-transparent"); - setTimeout(function() { - copyAlert.addClass("is-transparent"); - }, 2000); - } - - $("div.workflow").each(function() { - var workflowPath = undefined; - $(this).find("img").attr("src", (_, val) => { - workflowPath = val; - return workflowPath.replace(/\.[^.]+$/, ".svg"); - }); - var $codeHeader = createCodeHeader("Workflow"); - $(this).first().before($codeHeader); - $codeHeader.find("button").click(function() { - var $button = $(this); - fetch(workflowPath).then(req => req.text()).then(contents => { - navigator.clipboard.writeText(contents); - setCopyAlert($button); - }); - }); - }); - - $("code.hljs").each(function() { - var $this = $(this); - var language = /lang-(.+?)(\s|$)/.exec($this.attr("class"))[1].toUpperCase(); - if (language === 'CS' || language === 'CSHARP') { - language = "C#"; - } - if (language === 'JS') { - language = "JavaScript"; - } - var $codeHeader = createCodeHeader(language); - var $codeElement = $this.closest("pre"); - $codeElement.before($codeHeader); - $codeHeader.find("button").click(function() { - navigator.clipboard.writeText($codeElement.text()); - setCopyAlert($(this)); - }); - }); -}); \ No newline at end of file diff --git a/docs/workflows/.gitignore b/docs/workflows/.gitignore new file mode 100644 index 0000000..af455cb --- /dev/null +++ b/docs/workflows/.gitignore @@ -0,0 +1,2 @@ +*.layout +*.svg \ No newline at end of file diff --git a/docs/workflows/create-module.svg b/docs/workflows/create-module.svg deleted file mode 100644 index 043e0f6..0000000 --- a/docs/workflows/create-module.svg +++ /dev/null @@ -1,3 +0,0 @@ - -]>NewModuleCreateModule \ No newline at end of file diff --git a/docs/workflows/create-runtime.bonsai b/docs/workflows/create-runtime.bonsai index 81e77cf..c610b9f 100644 --- a/docs/workflows/create-runtime.bonsai +++ b/docs/workflows/create-runtime.bonsai @@ -1,5 +1,5 @@  - @@ -7,7 +7,7 @@ - example-env + .venv diff --git a/docs/workflows/create-runtime.svg b/docs/workflows/create-runtime.svg deleted file mode 100644 index 8603573..0000000 --- a/docs/workflows/create-runtime.svg +++ /dev/null @@ -1,3 +0,0 @@ - -]>CreateRuntime \ No newline at end of file diff --git a/docs/workflows/exec-eval.svg b/docs/workflows/exec-eval.svg deleted file mode 100644 index 5293e8f..0000000 --- a/docs/workflows/exec-eval.svg +++ /dev/null @@ -1,3 +0,0 @@ - -]>EvalExecCreateRuntime \ No newline at end of file diff --git a/docs/workflows/get-set.bonsai b/docs/workflows/get-set.bonsai index d2be94e..b9fc362 100644 --- a/docs/workflows/get-set.bonsai +++ b/docs/workflows/get-set.bonsai @@ -1,5 +1,5 @@  -PT1S + + + time @@ -24,6 +27,9 @@ false + + + time @@ -32,7 +38,9 @@ - + + + \ No newline at end of file diff --git a/docs/workflows/get-set.svg b/docs/workflows/get-set.svg deleted file mode 100644 index 42cea7f..0000000 --- a/docs/workflows/get-set.svg +++ /dev/null @@ -1,3 +0,0 @@ - -]>SetGetTimerKeyDown \ No newline at end of file diff --git a/docs/workflows/hello-python.svg b/docs/workflows/hello-python.svg deleted file mode 100644 index c6e564f..0000000 --- a/docs/workflows/hello-python.svg +++ /dev/null @@ -1,3 +0,0 @@ - -]>EvalCreateRuntime \ No newline at end of file diff --git a/docs/workflows/share-module.bonsai b/docs/workflows/share-module.bonsai index f234c0c..a667f77 100644 --- a/docs/workflows/share-module.bonsai +++ b/docs/workflows/share-module.bonsai @@ -1,5 +1,5 @@  -PT0.01S + + + NewModule @@ -41,11 +44,12 @@ - - - - - + + + + + + \ No newline at end of file diff --git a/docs/workflows/share-module.svg b/docs/workflows/share-module.svg deleted file mode 100644 index 2c6b3fc..0000000 --- a/docs/workflows/share-module.svg +++ /dev/null @@ -1,3 +0,0 @@ - -]>NewModuleEvalCreateModuleSetTimerModuleNewModule \ No newline at end of file diff --git a/src/Bonsai.Scripting.Python/Properties/launchSettings.json b/src/Bonsai.Scripting.Python/Properties/launchSettings.json index ee1d35e..93c2d6b 100644 --- a/src/Bonsai.Scripting.Python/Properties/launchSettings.json +++ b/src/Bonsai.Scripting.Python/Properties/launchSettings.json @@ -2,8 +2,9 @@ "profiles": { "Bonsai": { "commandName": "Executable", - "executablePath": "$(registry:HKEY_CURRENT_USER\\Software\\Goncalo Lopes\\Bonsai@InstallDir)Bonsai.exe", - "commandLineArgs": "--lib:$(TargetDir)." + "executablePath": "$(SolutionDir)..\\.bonsai\\Bonsai.exe", + "commandLineArgs": "--lib:\"$(TargetDir).\"", + "nativeDebugging": true } } } \ No newline at end of file