Add GraalPy guides.

Co-authored-by: Tim Felgentreff <tim.felgentreff@oracle.com>
Co-authored-by: stepan <stepan.sindelar@oracle.com>

.github/scripts/check-snippets.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python
+from glob import glob
+from os import PathLike
+from os.path import dirname, join
+from typing import cast
+
+import re
+
+
+STRIP_WHITESPACE_RE = re.compile(r'\s*')
+INDENT_RE = re.compile(r'^', re.MULTILINE)
+
+
+def get_file_snippets(path: str | PathLike[str]):
+    from marko.block import FencedCode
+    from marko.inline import CodeSpan, RawText
+    from marko.ext.gfm import gfm
+    from marko.ext.gfm.elements import Paragraph
+
+    with open(path) as f:
+        doc = gfm.parse(f.read())
+    codeblocks: list[tuple[str, str]] = []
+    for idx, child in enumerate(doc.children):
+        if idx > 0:
+            if child.get_type() == "FencedCode":
+                if (p := doc.children[idx - 1]).get_type() == "Paragraph":
+                    children = cast(Paragraph, p).children
+                    if len(children) == 1 and (filename := children[0]).get_type() == "CodeSpan":
+                        code = cast(RawText, cast(FencedCode, child).children[0]).children
+                        codeblocks.append((cast(str, cast(CodeSpan, filename).children), code))
+    return codeblocks
+
+
+def match_snippets(snippets, rootdir):
+    unmatched_snippets: list[tuple[list[str], str]] = []
+    for filename, snippet in snippets:
+        stripped_snippet = STRIP_WHITESPACE_RE.sub("", snippet)
+        files = glob(join(rootdir, "**", filename), recursive=True)
+        for filepath in files:
+            with open(filepath) as f:
+                contents = f.read()
+            contents = STRIP_WHITESPACE_RE.sub("", contents)
+            if stripped_snippet in contents:
+                break
+        else:
+            unmatched_snippets.append((files, snippet))
+    return unmatched_snippets
+
+
+if __name__ == "__main__":
+    import sys
+    from argparse import ArgumentParser
+
+    parser = ArgumentParser(__file__)
+    parser.add_argument("filename", nargs='+')
+    args = parser.parse_args()
+
+    failed = False
+    for filename in args.filename:
+        snippets = get_file_snippets(filename)
+        unmatched_snippets = match_snippets(snippets, dirname(filename))
+        print(f"Testing {filename}")
+        for files, snippet in unmatched_snippets:
+            failed = True
+            print("Failed to match the following snippet:", INDENT_RE.sub("\t", snippet), f"Tried these files: {files}", sep="\n")
+
+    sys.exit(failed)

.github/scripts/requirements.txt

@@ -0,0 +1 @@
+marko

.github/workflows/graalpy-check-snippets.yml

@@ -0,0 +1,27 @@
+name: Check Snippets in GraalPy Guides
+on:
+  push:
+    paths:
+      - 'graalpy/**'
+      - '.github/workflows/graalpy-check-snippets.yml'
+  pull_request:
+    paths:
+      - 'graalpy/**'
+      - '.github/workflows/graalpy-check-snippets.yml'
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: graalpy-24.1
+    - name: Install dependencies
+      run: |
+        python -m pip install -r .github/scripts/requirements.txt
+    - name: Check README snippets
+      run: find graalpy -name "README.md" -exec python .github/scripts/check-snippets.py "{}" "+"

.github/workflows/graalpy-custom-venv-guide.yml

@@ -0,0 +1,43 @@
+name: Test GraalPy Custom Venv Guide
+on:
+  push:
+    paths:
+      - 'graalpy/graalpy-custom-venv-guide/**'
+      - '.github/workflows/graalpy-custom-venv-guide.yml'
+  pull_request:
+    paths:
+      - 'graalpy/graalpy-custom-venv-guide/**'
+      - '.github/workflows/graalpy-custom-venv-guide.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  run:
+    name: 'graalpy-custom-venv-guide'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: graalvm/setup-graalvm@v1
+        with:
+          java-version: '23.0.0'
+          distribution: 'graalvm'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache: 'maven'
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 'graalpy-24.1'
+      - name: Build, test, and run 'graalpy-custom-venv-guide' using Maven
+        shell: bash
+        run: |
+          cd graalpy/graalpy-custom-venv-guide
+          ./mvnw --no-transfer-progress compile
+          graalpy -m venv venv
+          ./venv/bin/graalpy -m pip install art==6.3
+          ./mvnw --no-transfer-progress exec:java -Dexec.mainClass=org.example.App -Dvenv=venv | tee /tmp/output
+          grep -F "  ____                      _  ____" /tmp/output
+          grep -F " / ___| _ __   __ _   __ _ | ||  _ \  _   _" /tmp/output
+          #        | |  _ | '__| / _` | / _` || || |_) || | | | escaping is too cumbersome for this line
+          grep -F "| |_| || |   | (_| || (_| || ||  __/ | |_| |" /tmp/output
+          grep -F " \____||_|    \__,_| \__,_||_||_|     \__, |" /tmp/output
+          grep -F "                                      |___/" /tmp/output

.github/workflows/graalpy-freeze-dependencies-guide.yml

@@ -0,0 +1,33 @@
+name: Test GraalPy Freeze Dependencies Guide
+on:
+  push:
+    paths:
+      - 'graalpy/graalpy-freeze-dependencies-guide/**'
+      - '.github/workflows/graalpy-freeze-dependencies-guide.yml'
+  pull_request:
+    paths:
+      - 'graalpy/graalpy-freeze-dependencies-guide/**'
+      - '.github/workflows/graalpy-freeze-dependencies-guide.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  run:
+    name: 'graalpy-freeze-dependencies-guide'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: graalvm/setup-graalvm@v1
+        with:
+          java-version: '23.0.0'
+          distribution: 'graalvm'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache: 'maven'
+      - name: Build, test, and run 'graalpy-freeze-dependencies-guide' using Maven
+        shell: bash
+        run: |
+          cd graalpy/graalpy-freeze-dependencies-guide
+          ./mvnw --no-transfer-progress compile
+          ./mvnw --no-transfer-progress exec:java -Dexec.mainClass=org.example.App | tee /tmp/output
+          grep darent /tmp/output

.github/workflows/graalpy-javase-guide.yml

@@ -0,0 +1,32 @@
+name: Test GraalPy Java SE Guide
+on:
+  push:
+    paths:
+      - 'graalpy/graalpy-javase-guide/**'
+      - '.github/workflows/graalpy-javase-guide.yml'
+  pull_request:
+    paths:
+      - 'graalpy/graalpy-javase-guide/**'
+      - '.github/workflows/graalpy-javase-guide.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  run:
+    name: 'graalpy-javase-guide'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: graalvm/setup-graalvm@v1
+        with:
+          java-version: '23.0.0'
+          distribution: 'graalvm'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache: 'maven'
+      - name: Build, test, and run 'graalpy-javase-guide' using Maven
+        run: |
+          cd graalpy/graalpy-javase-guide
+          ./mvnw --no-transfer-progress compile
+          xvfb-run ./mvnw --no-transfer-progress exec:java -Dexec.mainClass=org.example.App -Dgraalpy.resources=./python-resources &
+          sleep 20

.github/workflows/graalpy-jython-guide.yml

@@ -0,0 +1,32 @@
+name: Test GraalPy Jython Guide
+on:
+  push:
+    paths:
+      - 'graalpy/graalpy-jython-guide/**'
+      - '.github/workflows/graalpy-jython-guide.yml'
+  pull_request:
+    paths:
+      - 'graalpy/graalpy-jython-guide/**'
+      - '.github/workflows/graalpy-jython-guide.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  run:
+    name: 'graalpy-jython-guide'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: graalvm/setup-graalvm@v1
+        with:
+          java-version: '23.0.0'
+          distribution: 'graalvm'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache: 'maven'
+      - name: Build, test, and run 'graalpy-jython-guide' using Maven
+        run: |
+          cd graalpy/graalpy-jython-guide
+          ./mvnw --no-transfer-progress compile
+          xvfb-run ./mvnw --no-transfer-progress exec:java -Dexec.mainClass=org.example.App &
+          sleep 20

.github/workflows/graalpy-micronaut-guide.yml

@@ -0,0 +1,47 @@
+name: Test GraalPy Micronaut Guide
+on:
+  push:
+    paths:
+      - 'graalpy/graalpy-micronaut-guide/**'
+      - '.github/workflows/graalpy-micronaut-guide.yml'
+  pull_request:
+    paths:
+      - 'graalpy/graalpy-micronaut-guide/**'
+      - '.github/workflows/graalpy-micronaut-guide.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+env:
+  NATIVE_IMAGE_OPTIONS: '-J-Xmx16g'
+jobs:
+  run:
+    name: 'graalpy-micronaut-guide'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: graalvm/setup-graalvm@v1
+        with:
+          java-version: '23.0.0'
+          distribution: 'graalvm'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache: 'maven'
+          native-image-job-reports: 'true'
+      - name: Build, test, and run 'graalpy-micronaut-guide' using Maven
+        run: |
+          cd graalpy/graalpy-micronaut-guide
+          ./mvnw --no-transfer-progress clean test -Dmicronaut.http.client.read-timeout=1m
+          ./mvnw --no-transfer-progress mn:run &
+          mnpid="$!"
+          sleep 30
+          curl -s -D - -o /dev/null http://localhost:8080/
+          kill $mnpid
+      - name: Build and run native 'graalpy-micronaut-guide' using Maven
+        run: |
+          cd graalpy/graalpy-micronaut-guide
+          ./mvnw --no-transfer-progress clean package -DskipTests -Dpackaging=native-image
+          ./target/graalpy-micronaut &
+          mnpid="$!"
+          sleep 20
+          curl -s -D - -o /dev/null http://localhost:8080/
+          kill $mnpid

.github/workflows/graalpy-native-extensions-guide.yml

@@ -0,0 +1,42 @@
+name: Test GraalPy Native Extensions Guide
+on:
+  push:
+    paths:
+      - 'graalpy/graalpy-native-extensions-guide/**'
+      - '.github/workflows/graalpy-native-extensions-guide.yml'
+  pull_request:
+    paths:
+      - 'graalpy/graalpy-native-extensions-guide/**'
+      - '.github/workflows/graalpy-native-extensions-guide.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  run:
+    name: 'graalpy-native-extensions-guide'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: graalvm/setup-graalvm@v1
+        with:
+          java-version: '23.0.0'
+          distribution: 'graalvm'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache: 'maven'
+      - name: Build, test, and run 'graalpy-native-extensions-guide' using Maven
+        shell: bash
+        run: |
+          cd graalpy/graalpy-native-extensions-guide
+          ./mvnw --no-transfer-progress compile
+          ./mvnw --no-transfer-progress exec:java -Dexec.mainClass=org.example.App -Dexec.args="appkle pear anana tomato" | tee /tmp/output
+          grep "did you mean 'apple'" /tmp/output
+          ./mvnw --no-transfer-progress exec:java -Dexec.mainClass=org.example.AppLogging -Dexec.args="appkle pear anana tomato" 2>&1 | tee /tmp/output2
+          grep "Loading C extension module polyleven" /tmp/output2
+          grep "did you mean 'apple'" /tmp/output2
+          if mvn package exec:java -Dexec.mainClass=org.example.MultiContextApp -Dexec.args="appkle pear anana strawberry tomato" 2>&1 | tee /tmp/output3; then
+            echo "the command was supposed to fail"
+            exit 1
+          fi
+          grep "did you mean 'apple'" /tmp/output3
+          grep "SystemError" /tmp/output3

.github/workflows/graalpy-openai-starter.yml

@@ -24,7 +24,6 @@ jobs:
           distribution: 'graalvm'
           github-token: ${{ secrets.GITHUB_TOKEN }}
           cache: 'maven'
-          native-image-job-reports: 'true'
       - name: Build, test, and run 'graalpy-openai-starter' using Maven
         run: |
           cd graalpy/graalpy-openai-starter

.github/workflows/graalpy-spring-boot-guide.yml

@@ -0,0 +1,47 @@
+name: Test GraalPy Spring Boot Guide
+on:
+  push:
+    paths:
+      - 'graalpy/graalpy-spring-boot-guide/**'
+      - '.github/workflows/graalpy-spring-boot-guide.yml'
+  pull_request:
+    paths:
+      - 'graalpy/graalpy-spring-boot-guide/**'
+      - '.github/workflows/graalpy-spring-boot-guide.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+env:
+  NATIVE_IMAGE_OPTIONS: '-J-Xmx16g'
+jobs:
+  run:
+    name: 'graalpy-spring-boot-guide'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: graalvm/setup-graalvm@v1
+        with:
+          java-version: '23.0.0'
+          distribution: 'graalvm'
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          cache: 'maven'
+          native-image-job-reports: 'true'
+      - name: Build, test, and run 'graalpy-spring-boot-guide' using Maven
+        run: |
+          cd graalpy/graalpy-spring-boot-guide
+          ./mvnw --no-transfer-progress clean test -Dspring.mvc.async.request-timeout=60000
+          ./mvnw --no-transfer-progress spring-boot:run &
+          sbpid="$!"
+          sleep 30
+          curl -s -D - -o /dev/null http://localhost:8080/
+          kill $sbpid
+      - name: Build and run native 'graalpy-spring-boot-guide' using Maven
+        run: |
+          cd graalpy/graalpy-spring-boot-guide
+          ./mvnw --no-transfer-progress clean -DskipTests -Pnative native:compile
+          ./target/graalpy-springboot &
+          sbpid="$!"
+          sleep 20
+          curl -s -D - -o /dev/null http://localhost:8080/
+          kill $sbpid

.github/workflows/graalpy-starter.yml

@@ -24,7 +24,6 @@ jobs:
           distribution: 'graalvm'
           github-token: ${{ secrets.GITHUB_TOKEN }}
           cache: 'maven'
-          native-image-job-reports: 'true'
       - name: Build, test, and run 'graalpy-starter' using Maven
         run: |
           cd graalpy/graalpy-starter