Add Python support to Micronaut guides

.agents/skills/micronaut-guides-authoring/SKILL.md

@@ -67,7 +67,7 @@ Each app entry usually includes:
 
 Feature names must be valid Micronaut Starter features. If a guide needs a feature not provided by Starter, add a feature class under `buildSrc/src/main/java/io/micronaut/guides/feature` and keep dependency coordinates in `buildSrc/src/main/resources/pom.xml`.
 
-Use optional metadata only when needed: `languages`, `buildTools`, `testFramework`, `minimumJavaVersion`, `maximumJavaVersion`, `cloud`, `publish`, `base`, `zipIncludes`, `skipGradleTests`, `skipMavenTests`, `env`, app-specific `javaFeatures`, `kotlinFeatures`, `groovyFeatures`, `invisibleFeatures`, `excludeTest`, and `excludeSource`.
+Use optional metadata only when needed: `languages`, `buildTools`, `testFramework`, `minimumJavaVersion`, `maximumJavaVersion`, `cloud`, `publish`, `base`, `zipIncludes`, `skipGradleTests`, `skipMavenTests`, `env`, app-specific `javaFeatures`, `kotlinFeatures`, `groovyFeatures`, `jvmFeatures` (shared by Java, Kotlin, and Groovy but not Python), `invisibleFeatures`, `excludeTest`, and `excludeSource`.
 
 Omit `languages` when a guide supports all default languages: Java, Groovy, and Kotlin. Add `languages` only when the guide intentionally narrows support to a subset.
 

.github/workflows/python-guides.yml

@@ -0,0 +1,49 @@
+name: Validate Python Guides
+on:
+  push:
+    branches:
+      - python
+    paths:
+      - '.github/workflows/python-guides.yml'
+      - 'buildSrc/**'
+      - 'guides/**'
+      - 'settings.gradle'
+      - 'src/docs/common/**'
+  pull_request:
+    branches:
+      - python
+    paths:
+      - '.github/workflows/python-guides.yml'
+      - 'buildSrc/**'
+      - 'guides/**'
+      - 'settings.gradle'
+      - 'src/docs/common/**'
+
+jobs:
+  validate:
+    name: Generate Python Guides
+    runs-on: ubuntu-latest
+    env:
+      LOCAL_GIT_MICRONAUT_STARTER: ${{ github.workspace }}/micronaut-starter
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - uses: actions/checkout@v6.0.2
+        with:
+          repository: n0tl3ss/micronaut-starter
+          # Pin micronaut-starter#3136 until its fix is merged upstream.
+          ref: 763920aaa46c06aeebbaba995a66fc3bef643801
+          path: micronaut-starter
+      - uses: actions/setup-java@v5.2.0
+        with:
+          distribution: adopt
+          java-version: '25'
+      - uses: actions/cache@v5.0.5
+        with:
+          path: ~/.gradle/caches
+          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}
+          restore-keys: |
+            ${{ runner.os }}-gradle-
+      - name: Validate build infrastructure
+        run: ./gradlew buildSrc:test --stacktrace
+      - name: Generate Python guides
+        run: ./gradlew generateAllPythonGuideTestScripts --stacktrace

README.md

@@ -18,6 +18,22 @@ To build a single guide, run the dynamic task created by `GuidesPlugin`; convert
 ./gradlew micronautHttpClientBuild
 ```
 
+### Use local composite builds
+
+Local Micronaut Core, Pyronaut, and Starter checkouts can be included with
+either the matching Gradle property or environment variable:
+
+| Checkout | Gradle property | Environment variable |
+| --- | --- | --- |
+| Micronaut Core | `local.git.micronaut-core` | `LOCAL_GIT_MICRONAUT_CORE` |
+| Pyronaut | `local.git.pyronaut` | `LOCAL_GIT_PYRONAUT` |
+| Micronaut Starter | `local.git.micronaut-starter` | `LOCAL_GIT_MICRONAUT_STARTER` |
+
+For example: `./gradlew -Plocal.git.pyronaut=/path/to/pyronaut help`.
+Gradle properties take precedence when both forms are set. Pyronaut's GraalPy
+bundle repository is discovered from a local Core or Pyronaut checkout when
+available; set `micronaut.graalpy.bundle.repo` to override it.
+
 ## Create a new guide
 
 For a high-level overview of the guides infrastructure, take a look at this [blog post](https://micronaut.io/2021/04/12/improving-the-micronaut-guides-infrastructure/).

buildSrc/build.gradle

@@ -36,7 +36,7 @@ repositories {
 }
 
 ext {
-    micronautStarterVersion = "5.2.0"
+    micronautStarterVersion = "5.2.0-SNAPSHOT"
 }
 
 dependencies {
@@ -83,5 +83,5 @@ tasks.named('test', Test) {
 }
 
 tasks.withType(JavaCompile).configureEach {
-    options.compilerArgs.add("-Amicronaut.jsonschema.baseUri=https://micronaut-projects.github.io/micronaut-guides/schemas") // (1)
+    options.compilerArgs.add("-Amicronaut.jsonschema.baseUri=https://guides.micronaut.io/schemas") // (1)
 }

buildSrc/settings.gradle

@@ -0,0 +1,10 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "micronaut-guides-buildsrc"
+
+apply from: file('../gradle/local-composite-builds.gradle')

buildSrc/src/main/groovy/io/micronaut/guides/GuideProjectGenerator.groovy

@@ -20,13 +20,15 @@ import org.gradle.api.GradleException
 import org.slf4j.Logger
 import org.slf4j.LoggerFactory
 
+import java.io.IOException
 import java.nio.file.Files
 import java.nio.file.FileVisitResult
 import java.nio.file.Path
 import java.nio.file.Paths
 import java.nio.file.SimpleFileVisitor
-import java.time.LocalDate
 import java.nio.file.attribute.BasicFileAttributes
+import java.time.LocalDate
+import java.util.Locale
 import java.util.regex.Pattern
 
 import static groovy.io.FileType.FILES
@@ -153,7 +155,7 @@ class GuideProjectGenerator implements AutoCloseable {
                 String packageAndName = BASE_PACKAGE + '.' + app.name()
 
                 guidesGenerator.generateAppIntoDirectory(destination, app.applicationType(), packageAndName, app.framework(),
-                        appFeatures, buildTool, app.testFramework() ?: testFramework, lang, javaVersion)
+                        appFeatures, buildTool, lang == PYTHON ? PYTEST : (app.testFramework() ?: testFramework), lang, javaVersion)
 
                 if (lang == PYTHON) {
                     movePythonResources(destinationPath)
@@ -166,13 +168,17 @@ class GuideProjectGenerator implements AutoCloseable {
 
                 copyGuideSourceFiles(inputDir, destinationPath, appName, guidesOption.language.toString())
 
+                if (buildTool == BuildTool.PYRONAUT && lang == PYTHON) {
+                    ensurePyronautBlockingExecutorConfig(destinationPath.resolve('config/application.toml'))
+                }
+
                 if (app.excludeSource()) {
                     for (String mainSource : app.excludeSource()) {
-                        File f = fileToDelete(destination, GuideAsciidocGenerator.mainPath(appName, mainSource), guidesOption)
+                        File f = fileToDelete(destination, GuideAsciidocGenerator.mainPath(appName, mainSource, guidesOption), guidesOption)
                         if (f.exists()) {
                             f.delete()
                         }
-                        f = fileToDelete(destination, GuideAsciidocGenerator.mainPath(EMPTY_STRING, mainSource), guidesOption)
+                        f = fileToDelete(destination, GuideAsciidocGenerator.mainPath(EMPTY_STRING, mainSource, guidesOption), guidesOption)
                         if (f.exists()) {
                             f.delete()
                         }
@@ -181,14 +187,20 @@ class GuideProjectGenerator implements AutoCloseable {
 
                 if (app.excludeTest()) {
                     for (String testSource : app.excludeTest()) {
-                        File f = fileToDelete(destination, GuideAsciidocGenerator.testPath(appName, testSource, testFramework), guidesOption)
+                        File f = fileToDelete(destination, GuideAsciidocGenerator.testPath(appName, testSource, guidesOption), guidesOption)
                         if (f.exists()) {
                             f.delete()
                         }
-                        f = fileToDelete(destination, GuideAsciidocGenerator.testPath(EMPTY_STRING, testSource, testFramework), guidesOption)
+                        f = fileToDelete(destination, GuideAsciidocGenerator.testPath(EMPTY_STRING, testSource, guidesOption), guidesOption)
                         if (f.exists()) {
                             f.delete()
                         }
+                        if (buildTool == BuildTool.PYRONAUT && lang == PYTHON) {
+                            f = new File(destination, "tests/${pythonTestModuleName(testSource)}.${lang.extension}")
+                            if (f.exists()) {
+                                f.delete()
+                            }
+                        }
                     }
                 }
 
@@ -198,11 +210,41 @@ class GuideProjectGenerator implements AutoCloseable {
                         copyFile(inputDir, destinationRoot, zipInclude)
                     }
                 }
+                if (buildTool == BuildTool.PYRONAUT && lang == PYTHON) {
+                    removePythonPackageMarkerFiles(destination)
+                }
                 addLicenses(new File(outputDir.absolutePath, folder))
             }
         }
     }
 
+    private static void removePythonPackageMarkerFiles(File destination) {
+        Files.walkFileTree(destination.toPath(), new SimpleFileVisitor<Path>() {
+            @Override
+            FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
+                if (attrs.isRegularFile() && file.fileName.toString() == '__init__.py') {
+                    Files.delete(file)
+                }
+                FileVisitResult.CONTINUE
+            }
+        })
+    }
+
+    private static String pythonModuleName(String target) {
+        if (target.contains('_') || target == target.toLowerCase(Locale.ENGLISH)) {
+            return target
+        }
+        target.replaceAll(/([a-z0-9])([A-Z])/, '$1_$2')
+                .replaceAll(/([A-Z]+)([A-Z][a-z])/, '$1_$2')
+                .toLowerCase(Locale.ENGLISH)
+    }
+
+    private static String pythonTestModuleName(String target) {
+        String normalized = target.endsWith('Test') ? target.substring(0, target.length() - 'Test'.length()) : target
+        normalized = pythonModuleName(normalized)
+        normalized.startsWith('test_') ? normalized : "test_${normalized}"
+    }
+
     private static void movePythonResources(Path destinationPath) {
         movePythonResourceFolder(destinationPath, 'views')
         movePythonResourceFolder(destinationPath, 'static')
@@ -239,14 +281,18 @@ class GuideProjectGenerator implements AutoCloseable {
 
     void addLicenses(File folder) {
         String licenseHeader = licenseHeaderText()
-        folder.eachFileRecurse (FILES) { file ->
-            if (
-                    (file.path.endsWith(EXTENSION_JAVA) || file.path.endsWith(EXTENSION_GROOVY) || file.path.endsWith(EXTENSION_KT))
-                    && !file.text.contains("Licensed under")
-            ) {
-                file.text = licenseHeader + file.text
+        Files.walkFileTree(folder.toPath(), new SimpleFileVisitor<Path>() {
+            @Override
+            FileVisitResult visitFile(Path path, BasicFileAttributes attrs) {
+                File file = path.toFile()
+                if (attrs.isRegularFile()
+                        && (file.path.endsWith(EXTENSION_JAVA) || file.path.endsWith(EXTENSION_GROOVY) || file.path.endsWith(EXTENSION_KT))
+                        && !file.text.contains("Licensed under")) {
+                    file.text = licenseHeader + file.text
+                }
+                FileVisitResult.CONTINUE
             }
-        }
+        })
     }
 
     @Memoized
@@ -263,35 +309,27 @@ class GuideProjectGenerator implements AutoCloseable {
         // look for a common 'src' directory shared by multiple languages and copy those files first
         final String srcFolder = 'src'
         Path srcPath = Paths.get(inputDir.absolutePath, appName, srcFolder)
+        Path sourcePath = Paths.get(inputDir.absolutePath, appName, language)
         if (Files.exists(srcPath)) {
-            Path resourcesPath = srcPath.resolve('main').resolve('resources')
-            if (language == PYTHON.toString() && Files.exists(resourcesPath)) {
-                Path configPath = Paths.get(destinationPath.toString(), 'config')
-                Files.createDirectories(configPath)
-                Files.walkFileTree(resourcesPath, new CopyFileVisitor(configPath))
-                Path destinationResourcesPath = Paths.get(destinationPath.toString(), srcFolder, 'main', 'resources')
-                Files.walkFileTree(resourcesPath, new SimpleFileVisitor<Path>() {
-                    @Override
-                    FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
-                        Files.deleteIfExists(destinationResourcesPath.resolve(resourcesPath.relativize(file)))
-                        FileVisitResult.CONTINUE
-                    }
-                })
+            if (language == PYTHON.toString()) {
+                copySharedPythonResources(srcPath, sourcePath, destinationPath)
+                Path pythonResources = srcPath.resolve('main').resolve('resources')
+                Path pythonTestResources = srcPath.resolve('test').resolve('resources')
+                Path pythonTestResourcesLegacy = srcPath.resolve('test-resources')
                 Files.walkFileTree(srcPath, new CopyFileVisitor(Paths.get(destinationPath.toString(), srcFolder)) {
                     @Override
                     FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
-                        if (dir.equals(resourcesPath)) {
+                        if (dir.equals(pythonResources) || dir.equals(pythonTestResources) || dir.equals(pythonTestResourcesLegacy)) {
                             return FileVisitResult.SKIP_SUBTREE
                         }
-                        super.preVisitDirectory(dir, attrs)
+                        return super.preVisitDirectory(dir, attrs)
                     }
                 })
             } else {
                 Files.walkFileTree(srcPath, new CopyFileVisitor(Paths.get(destinationPath.toString(), srcFolder)))
             }
         }
 
-        Path sourcePath = Paths.get(inputDir.absolutePath, appName, language)
         if (!Files.exists(sourcePath)) {
             sourcePath.toFile().mkdir()
         }
@@ -303,6 +341,80 @@ class GuideProjectGenerator implements AutoCloseable {
         }
     }
 
+    private static void ensurePyronautBlockingExecutorConfig(Path applicationConfig) {
+        String config = Files.exists(applicationConfig) ? Files.readString(applicationConfig) : ''
+        if (config.contains('[micronaut.executors.blocking]')) {
+            return
+        }
+        String suffix = config.isEmpty() || config.endsWith('\n') ? '' : '\n'
+        Files.createDirectories(applicationConfig.parent)
+        Files.writeString(applicationConfig, config + suffix + '''
+[micronaut.executors.blocking]
+type = 'CACHED'
+virtual = false
+''')
+    }
+
+    private static void copySharedPythonResources(Path srcPath, Path sourcePath, Path destinationPath) {
+        Path pythonConfigPath = sourcePath.resolve('config')
+        copySharedPythonResourceDirectory(srcPath.resolve('main/resources'), destinationPath.resolve('config'), pythonConfigPath)
+        Path pythonTestConfigPath = sourcePath.resolve('tests-config')
+        copySharedPythonResourceDirectory(srcPath.resolve('test/resources'), destinationPath.resolve('tests-config'), pythonTestConfigPath)
+        copySharedPythonResourceDirectory(srcPath.resolve('test-resources'), destinationPath.resolve('tests-config'), pythonTestConfigPath)
+    }
+
+    private static void copySharedPythonResourceDirectory(Path resourcePath, Path destinationPath, Path pythonSpecificPath) {
+        if (!Files.exists(resourcePath)) {
+            return
+        }
+        def paths = Files.walk(resourcePath)
+        try {
+            paths.filter(Files::isRegularFile).forEach { Path source ->
+                Path relative = resourcePath.relativize(source)
+                if (!GuideUtils.isBootstrapConfiguration(relative) && !isOverriddenByPythonConfig(relative, pythonSpecificPath)) {
+                    Path destination = destinationPath.resolve(relative)
+                    Files.createDirectories(destination.parent)
+                    Files.copy(source, destination, REPLACE_EXISTING)
+                }
+            }
+        } finally {
+            paths.close()
+        }
+    }
+
+    private static boolean isOverriddenByPythonConfig(Path relative, Path pythonSpecificPath) {
+        if (Files.exists(pythonSpecificPath.resolve(relative))) {
+            return true
+        }
+        if (relative.nameCount != 1 || !Files.isDirectory(pythonSpecificPath)) {
+            return false
+        }
+        String filename = relative.fileName.toString()
+        int extensionIndex = filename.lastIndexOf('.')
+        if (extensionIndex < 1) {
+            return false
+        }
+        String basename = filename.substring(0, extensionIndex)
+        if (!isEnvironmentConfigBasename(basename)) {
+            return false
+        }
+        def paths = Files.list(pythonSpecificPath)
+        try {
+            paths.filter(Files::isRegularFile)
+                    .map { Path path -> path.fileName.toString() }
+                    .anyMatch { String name -> name.startsWith("${basename}.") }
+        } finally {
+            paths.close()
+        }
+    }
+
+    private static boolean isEnvironmentConfigBasename(String basename) {
+        basename == 'application' ||
+                basename.startsWith('application-') ||
+                basename == 'bootstrap' ||
+                basename.startsWith('bootstrap-')
+    }
+
     private static File fileToDelete(File destination, String path, GuidesOption guidesOption) {
         Paths.get(destination.absolutePath, path
                 .replace("@lang@", guidesOption.language.toString())
@@ -360,12 +472,12 @@ class GuideProjectGenerator implements AutoCloseable {
 
     private static TestFramework testFrameworkOption(@NonNull Language language,
                                                      @Nullable TestFramework testFramework) {
-        if (testFramework != null) {
-            return testFramework
-        }
         if (language == PYTHON) {
             return PYTEST
         }
+        if (testFramework != null) {
+            return testFramework
+        }
         if (language == GROOVY) {
             return SPOCK
         }