Merge pull request #1 from SubstrateLabs/hwwu/toolchain-update

update the python toolchain to support both Rye and Poetry

_internal/_template/README.md

@@ -1,7 +1,8 @@
 # Title
 
 <details>
-    <summary>How to run this example</summary>
+<summary>How to run this example</summary>
+<br/>
 
 ```bash
 # Set your API key as an environment variable.
@@ -12,10 +13,16 @@ cd typescript                   # Navigate to the typescript example
 npm install                     # Install dependencies
 ts-node example.ts              # Run the example
 
-# Run the Python example
-# Note: First install dependencies in the root examples directory.
+# If using Poetry:
 cd python                       # Navigate to the python example
-poetry run python example.py    # Run the example
+poetry install                  # Install dependencies and build the example
+poetry run main                 # Run the example
+
+# If using Rye:
+# Update pyproject.toml to switch to Rye.
+cd python                       # Navigate to the python example
+rye sync                        # Install dependencies and build the example
+rye run main                    # Run the example
 ```
 
 </details>
@@ -24,13 +31,13 @@ We follow this procedure to create consistent, high volume content.
 
 1. Come up with a short readable slug, e.g. `generate-json` and a title.
 2. Create a folder in the [examples repo](https://github.com/SubstrateLabs/examples), copying this folder
-3. Write the code in TS or Python, and keep it simple. Ideally it’s just a script with no additional dependencies. 
-    1. Consider creating illustrative variations of the script (e.g. `ComputeText` and `MultiComputeText` - [example](https://github.com/SubstrateLabs/examples/tree/main/basics/generate-text))
-    2. Translate your script to the other language. (TODO: automated translation with Substrate)
-    3. Make sure both examples run and produce simple polished output.
-    4. Simplify the code
-        1. Wrap lines (multi-line node declarations are easier to read)
-        2. Consider inlining variables
+3. Write the code in TS or Python, and keep it simple. Ideally it’s just a script with no additional dependencies.
+   1. Consider creating illustrative variations of the script (e.g. `ComputeText` and `MultiComputeText` - [example](https://github.com/SubstrateLabs/examples/tree/main/basics/generate-text))
+   2. Translate your script to the other language. (TODO: automated translation with Substrate)
+   3. Make sure both examples run and produce simple polished output.
+   4. Simplify the code
+      1. Wrap lines (multi-line node declarations are easier to read)
+      2. Consider inlining variables
 4. Fill out this README with walkthrough text and generate new image assets.
 
 ![hero](hero.png)
@@ -82,7 +89,6 @@ If your example is a graph, create a diagram.
 
 ![diagram](diagram.svg)
 
-
 To edit the diagram, run:
 
 ```bash

_internal/_template/python/.gitignore

@@ -0,0 +1,10 @@
+# python generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# venv
+.venv

_internal/_template/python/README.md

@@ -0,0 +1,26 @@
+# Substrate Example Templates in Python
+
+This is a Substrate example template written in Python. To run this example,
+
+```bash
+# Set your API key as an environment variable.
+# Get one here https://www.substrate.run/dashboard/keys if this is your first time.
+export SUBSTRATE_API_KEY=<your Substrate API key>
+
+# Navigate to the python example directory.
+cd python
+```
+
+To run the example with Poetry (default), run the following.
+
+```bash
+poetry install
+poetry run main
+```
+
+To run the example with Rye, comment out the Poetry sections and uncomment the Rye sections in `pyproject.toml` and run the following.
+
+```bash
+rye sync
+rye run main
+```

_internal/_template/python/poetry.toml

@@ -0,0 +1,2 @@
+[virtualenvs]
+in-project = true

_internal/_template/python/pyproject.toml

@@ -0,0 +1,68 @@
+[project]
+name = "template"
+version = "0.1.0"
+description = ""
+authors = [{ name = "Hanwen Wu", email = "[email protected]" }]
+readme = "README.md"
+
+requires-python = ">= 3.9"
+dependencies = ["substrate"]
+
+[project.scripts]
+main = "python.example:main"
+
+[tool.ruff]
+line-length = 120
+output-format = "grouped"
+target-version = "py310"
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+##############################
+# Uncomment for Poetry support
+##############################
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "template"
+version = "0.1.0"
+description = ""
+authors = ["Hanwen Wu <[email protected]>"]
+readme = "README.md"
+
+packages = [{ include = "python", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+substrate = "220240617.*"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.6.1"
+marimo = "^0.8.0"
+
+[tool.poetry.scripts]
+main = "python.example:main"
+
+
+###########################
+# Uncomment for Rye support
+###########################
+
+# [build-system]
+# requires = ["hatchling"]
+# build-backend = "hatchling.build"
+
+# [tool.rye]
+# managed = true
+# dev-dependencies = ["ruff>=0.6.1", "marimo>=0.8.0"]
+
+# [tool.hatch.metadata]
+# allow-direct-references = true
+
+# [tool.hatch.build.targets.wheel]
+# packages = ["src/python"]

basics/generate-text/README.md

@@ -15,9 +15,10 @@ ts-node example-multi.ts        # Run the MultiComputeText example
 
 # Run the Python example
 # Note: First install dependencies in the root examples directory.
-cd python                             # Navigate to the python example
-poetry run python example.py          # Run the ComputeText example
-poetry run python example-multi.py    # Run the MultiComputeText example
+cd python                       # Navigate to the python example
+poetry install                  # Install dependencies and build the example
+poetry run example              # Run the ComputeText example
+poetry run example-multi        # Run the MultiComputeText example
 ```
 
 </details>

basics/generate-text/python/README.md

@@ -0,0 +1,28 @@
+# Substrate GenerateText Examples
+
+To run this example,
+
+```bash
+# Set your API key as an environment variable.
+# Get one here https://www.substrate.run/dashboard/keys if this is your first time.
+export SUBSTRATE_API_KEY=<your Substrate API key>
+
+# Navigate to the python example directory.
+cd python
+```
+
+To run the example with Poetry (default),
+
+```bash
+poetry install
+poetry run example
+poetry run example-multi
+```
+
+To run the example with Rye, comment out the Poetry sections and uncomment the Rye sections in `pyproject.toml` and run the following.
+
+```bash
+rye sync
+rye run example
+rye run example-multi
+```

basics/generate-text/python/poetry.toml

@@ -0,0 +1,2 @@
+[virtualenvs]
+in-project = true

basics/generate-text/python/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "example-generate-text"
+version = "0.1.0"
+description = ""
+authors = [{ name = "Ben Guo", email = "[email protected]" }]
+readme = "README.md"
+
+requires-python = ">= 3.9"
+dependencies = ["substrate"]
+
+[project.scripts]
+example = "generatetext.example:main"
+example-multi = "generatetext.example_multi:main"
+
+[tool.ruff]
+line-length = 120
+output-format = "grouped"
+target-version = "py310"
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+##############################
+# Uncomment for Poetry support
+##############################
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "example-generate-text"
+version = "0.1.0"
+description = ""
+authors = ["Ben Guo <[email protected]>"]
+readme = "README.md"
+
+packages = [{ include = "generatetext", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+substrate = "220240617.*"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.6.1"
+marimo = "^0.8.0"
+
+[tool.poetry.scripts]
+example = "generatetext.example:main"
+example-multi = "generatetext.example_multi:main"
+
+###########################
+# Uncomment for Rye support
+###########################
+
+# [build-system]
+# requires = ["hatchling"]
+# build-backend = "hatchling.build"
+
+# [tool.rye]
+# managed = true
+# dev-dependencies = ["ruff>=0.6.1", "marimo>=0.8.0"]
+
+# [tool.hatch.metadata]
+# allow-direct-references = true
+
+# [tool.hatch.build.targets.wheel]
+# packages = ["src/generatetext"]