Merge pull request #83 from leon-thomm/dev

Ryven 3.1

.github/workflows/publish-package.yml

@@ -0,0 +1,27 @@
+name: Publish package distribution to TestPyPi and PyPi
+on:
+  push:
+    branches:
+      - main
+jobs:
+  Build-and-Publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+          architecture: x64
+      - name: Install pypa/build
+        run: python -m pip install build --user
+      - name: Build binary wheel and source tarball
+        run: python -m build --sdist --wheel --outdir dist/
+      - name: Publish distribution to TestPyPI
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@master
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -1,13 +1,16 @@
 .idea/
 .vscode/
+.qt_for_python/
 __pycache__/
 venv/
 temp/
 tests/
 code_gen/
 __own__/
+build/
+dist/
+*.egg-info
 
-MANIFEST.in
 ryvencore-drawio.xml
-setup.cfg
-setup.py
+
+

CONTRIBUTING.md

@@ -1,23 +1,24 @@
 # Philosophy :cyclone:
 
 Ryven is meant to be a **simple** and **transparent** tool for visual scripting in Python.
-It does not intend to replace textual source code by the diagram representation, rather to enhance it.
-Any form of optimization shall only be considered if it does not seriously restrict or significantly complicate
-the functionality of the software.
+It does not intend to replace textual source code in general by the diagram representation, rather to enhance it.
+The idea is to provide a simple but powerful system for nodes and node packages with virtually no restrictions, so even fairly advanced mechanisms can be built on top of it.
 
 # Contributions In General :rocket:
 
-There are many different ways you can contribute to the Ryven project.
-If you want to help out, there are a few very effective options including
+There are many ways you can contribute to the Ryven project. Particularly effective options include improvement of
 
-- consequent and precise docstrings
-- better online documentation
-- content: nodes and examples
+- docstrings
+- online documentation
+- example content: nodes and projects
+- tutorials
+
+Also check out the other repositories.
 
 # Creating Good Issues :mega:
 
-- you might check the [information on the website](https://ryven.org/guides) before you open a new issue
-- if it's an issue about the software, make sure to always include a precise desctiption of the problem and reproduction steps
-- you can also use the discussions area for suggestions around possible improvements and FAQ
+- you might want to check the [information on the website](https://ryven.org/guide)
+- be precise and include a minimal procedure to reproduce the problem
+- notice there's a *discussions* section which can be used for all kinds of questions or suggestions
 
-Have a great day!
+Thanks for hanging around and have a nice day!

MANIFEST.in

@@ -0,0 +1,15 @@
+recursive-include **/resources *
+recursive-include ryven/example_nodes *
+recursive-include ryven/example_projects *
+recursive-include docs *
+recursive-include ryven/unused *
+recursive-include ryven *.json *.ui
+include CONTRIBUTING.md
+include LICENSE
+include MANIFEST.in
+include pyproject.toml
+include README.md
+include requirements.txt
+include setup.cfg
+global-exclude *.py[co]
+global-exclude __pycache__

README.md

@@ -1,54 +1,142 @@
 <p align="center">
-  <img src="./Ryven/resources/pics/logo.png" alt="drawing" height="200"/>
+  <img src="./docs/img/logo.png" alt="drawing" width="70%"/>
 </p>
 
-# A simple flow-based visual scripting env for Python
+# A simple visual node editor for Python
 
-## Introduction
+**Ryven combines flow-based visual scripting with Python. It gives you absolute freedom for your nodes and a simple system for programming them. While there are some example node packages, you will most likely rely mostly on your own nodes.**
 
-Hello there! Ryven is an editor combining flow-based visual scripting with Python. It provides an easy to use system for programming nodes executing any Python code.
+<!-- Ryven is based on [ryvencore](https://github.com/leon-thomm/ryvencore) and [ryvencore-qt](https://github.com/leon-thomm/ryvencore-qt). A detailed guide for Ryven can be found [here](https://ryven.org/guides.html#/). -->
 
-Ryven is now based on [ryvencore-qt](https://github.com/leon-thomm/ryvencore-qt), a guide for Ryven can be found [here](https://ryven.org/guide#/).
+While Ryven has a large Qt-based frontend which affects performance of flow execution, you can disable particularly expensive features, and a project made in the editor can be deployed directly on the backend (ryvencore) via RyvenConsole, which does not have a single dependency!
 
-*Ryven 3 and the new underlying framework haven't been tested extensively yet, so there might be some further changes incoming.*
+| Ryven repos on GitHub | -------------------------------------------------------------------------------- |
+|---|---|
+| [ryvencore](https://github.com/leon-thomm/ryvencore) | backend / core framework |
+| [ryvencore-qt](https://github.com/leon-thomm/ryvencore-qt) | Qt frontend |
+| [ryven-blender](https://github.com/leon-thomm/ryven-blender) | Ryven plugin for Blender |
+| [ryven-unreal](https://github.com/leon-thomm/ryven-unreal) | Ryven plugin for Unreal Engine |
+| [ryven-website](https://github.com/leon-thomm/ryven-website) | Ryven website sources |
+| [PythonOCC nodes for Ryven](https://github.com/Tanneguydv/Pythonocc-nodes-for-Ryven) | Ryven nodes for PythonOCC |
 
-## Installation
+To get started with Ryven, these are the resources that guide you through the process (in an order that makes the most sense):
+1. the quick start guide below
+2. the tutorials in the `docs/node_tutorials` directory
+3. a longer [guide on the website](https://ryven.org/guide#/) for details
+
+Ryven comes with some example nodes, but these are, indeed, just examples, and there's no guarantee that all of them will stay. I would like to open a repository for maintaining particularly useful (frameworks of) nodes, but I will need contributors for that.
+
+### Installation
 
 ```
-git clone https://github.com/leon-thomm/ryven
-cd Ryven
-pip install -r requirements.txt
-cd Ryven/src
-python Ryven.py
+pip install ryven
+```
+
+and now you can launch it by running `ryven` on your terminal, and `ryven_console` for RyvenConsole. If you want to start Ryven from a Python script, just import it and run it like this
+
+```python
+import ryven
+
+ryven.run_ryven(
+    # args...
+)
+
 ```
 
-## Features
+### quick start
 
-#### simple nodes system
-All information about a node is part of its class. A minimal node definition can be as simple as this
+A super quick intro to Ryven.
+
+**editor usage**
+
+Open Ryven by typing `ryven` in your terminal (or running `Ryven.py` with python), and create a new project. Import some example nodes via `File -> Import Example Nodes` and select `std/nodes.py`. You should now see a long list of nodes on the left. Drag and drop them into the scene and get a feeling for how they work, everything is being executed at realtime. For instance, drag two `val` nodes into the scene, wire them together with a `+` node and display the result in a `result` node. Now replace one of them with a slider node generating real numbers. You can also get an interactive nodes list preview inside the scene by right-clicking. You can pan around also with the right mouse button, and zoom via `ctrl + scroll`.  You can also create new scripts, rename and delete them.
+
+Now let's check out the small example projects: open a new Ryven window and load one of them. Take a closer look and understand what they do.
+
+At this point you are ready to start building your own nodes.
+
+**defining nodes**
+
+Navigate to the `~/.ryven/packages/` directory and create a new folder `<your_package_name>`. Inside this folder create a python file `nodes.py` and fill it with the following content:
 
 ```python
-class PrintNode(Node):
-    """Prints your data."""
+from ryven.NENV import *
+
+# your node definitions go here
+
+export_nodes(
+    # list your node classes here, as tuple
+)
+```
+
+and now you can define your own node classes. Reference the ones you want to expose to Ryven in the `export_nodes` function (for example `export_nodes(MyNode, )` or `export_nodes(Node1, Node2, )`). Let's define two basic nodes:
+
+one which generates random numbers
+
+```python
+from random import random
+
+class RandNode(Node):
+    """Generates scaled random float values"""
+    # the docstring will be shown as tooltip in the editor
+
+    title = 'Rand'  # the display_title is title by default
+    tags = ['random', 'numbers']  # for better search
+
+    init_inputs = [  # one input
+        NodeInputBP(dtype=dtypes.Data(default=1))
+        # the dtype will automatically provide a suitable widget
+    ]
+    init_outputs = [  # and one output
+        NodeOutputBP()
+    ]
+    color = '#fcba03'
+
+    def update_event(self, inp=-1):
+        # update first output
+        self.set_output_val(0, 
+            random() * self.input(0)  # random float between 0 and value at input
+        )
+```
 
+and another one which prints them
+
+```python
+class PrintNode(Node):
     title = 'Print'
     init_inputs = [
-        NodeInputBP()
+        NodeInputBP(),
     ]
     color = '#A9D5EF'
 
     def update_event(self, inp=-1):
         print(self.input(0))
 ```
 
-#### macros / subgraphs
-You can define *macros* which get registered as nodes themselves
+and that's it! Go ahead and import your nodes package in Ryven. Place both in the scene and connect the `Rand` node to your `Print` node.
+
+***
+
+You can do a lot more than shown above. A summary of the main features:
+
+- **many modifiable themes**
+- **simple and unrestricted nodes system**
+- **actions / right-click operations system for nodes**
+- **variables system** with update mechanism for nodes that automatically adapt to change of data
+- **logging support**
+- **rendering flow images**
+- **stylus support** for adding handwritten notes / drawings on touch devices
+- **exec flow support** like [UnrealEngine BluePrints](https://docs.unrealengine.com/4.26/en-US/ProgrammingAndScripting/Blueprints/)
+- **Qt widgets support**
+
+and some examples for those:
+
+#### many modifiable themes
+![](./docs/img/themes_with_logo.png)
 
-![](./docs/img/macro.png)
-Macros are like all other scripts, so they have their own flow, plus input and output node
-![](./docs/img/macro2.png)
+Also light themes!
 
-#### right click operations system for nodes
+#### actions / right-click operations system for nodes
 which can be edited through the API at any time.
 ```python
 class MyNode(Node):
@@ -65,67 +153,81 @@ class MyNode(Node):
 ```
 
 #### Qt widgets
-You can add custom QWidgets for your nodes, so you can also easily integrate your existing Python-Qt widgets.
+You can add custom Qt widgets for your nodes. Define a `widgets.py` file next to your `nodes.py` with similar structure to `nodes.py`, see the guide for detailed instructions.
+
+`widgets.py`
+```python
+from ryven.NWENV import *
+from qtpy.QtWidgets import QWidget
+
+class SomeMainWidget(MWB, QWidget):
+    def __init__(self, params):
+        MWB.__init__(self, params)
+        QWidget.__init__(self)
+    ...
+
+class SomeInputWidget(IWB, QWidget):
+    def __init__(self, params):
+        IWB.__init__(self, params)
+        QWidget.__init__(self)
+    ...
+
+export_widgets(
+    SomeMainWidget,
+    SomeInputWidget,
+)
+```
+`nodes.py`
 ```python
 class MyNode(Node):
     main_widget_class = MyNode_MainWidget
     main_widget_pos = 'below ports'  # alternatively 'between ports'
-    # ...
 ```
-<!-- - **convenience GUI classes** -->
-
-#### many different modifiable themes
-![](./docs/img/themes_1_merged.png)
 
-#### exec flow support
-While data flows are the most common use case, exec flows (like [UnrealEngine BluePrints](https://docs.unrealengine.com/4.26/en-US/ProgrammingAndScripting/Blueprints/)) are also supported. 
-<!-- While while it can lead to issues when using exec connections in data flows, conceptually this also works and has proven to be also really powerful if applied correctly. -->
-
-#### stylus support for adding handwritten notes
-![](./docs/img/stylus_light.png)
-
-#### rendering flow images
+#### stylus support
+<p align="center">
+  <img src="./docs/img/stylus_dark.png" alt="drawing" width="70%"/>
+</p>
 
 #### logging support
 ```python
 import logging
 
 class MyNode(Node):
-    def __init__(self, params):
-        super().__init__(params)
-
+    def somewhere(self):
         self.logger = self.new_logger('nice log')
 
     def update_event(self, inp=-1):
-        self.logger.log(logging.INFO, 'updated!')
+        self.logger.info('updated!')
 ```
 
 #### variables system
-with an update mechanism to build nodes that automatically adapt to change of variables.
+with an update mechanism to build nodes that automatically adapt to change of data.
 
 ```python
 class MyNode(Node):
-    ...
-
     def a_method(self):
         self.register_var_receiver('x', method=self.process)
 
     # with some method...
     def process(self, val_of_x):
-        # processing new value of x
+        # processing new value of var 'x'
         ...
 ```
 
-Also visit the [website](https://ryven.org) if you haven't been there already.
+## Contributions
 
-Ryven is now built on top of [ryvencore-qt](https://github.com/leon-thomm/ryvencore-qt), a framework for building Ryven-like editors. Nodes from Ryven are easily migratable to other ryvencore-qt editors.
+Contributing guidelines: [here](https://github.com/leon-thomm/Ryven/blob/dev/CONTRIBUTING.md).
 
-## Contributions
+Particularly effective ways to contribute outside direct development of the software include
 
-To support the development of this project, which will decide its future, check out the [ryvencore-qt](https://github.com/leon-thomm/ryvencore-qt) repo where the main development is happening.
+- creating examples
+- creating tutorials
+- creating node packages
+- improving documentation
 
-Feel free to open discussions here (there's a discussions area in this repo).
+Also notice that there's a *discussions* area in this repo.
 
-The docs page on the website is made with [Docsify](https://github.com/docsifyjs/docsify/), so you can improve it by simply editing the markdown.
+The docs page on the website is made with [Docsify](https://github.com/docsifyjs/docsify/), so you can improve it by simply editing the markdown. The whole [website sources](https://github.com/leon-thomm/ryven-website) are also on GitHub.
 
 Cheers.