Add Python templates and onboarding documentation

docs/fundamentals/aspire-sdk-templates.md

@@ -37,6 +37,17 @@ The following Aspire solution templates are available, assume the solution is na
   - **AspireSample.Web**: An [ASP.NET Core Blazor App](/aspnet/core/blazor) project with default Aspire service configurations, this project depends on the [**AspireSample.ServiceDefaults**](#service-defaults) project.
   - **AspireSample.Test**: Either an [MSTest](#mstest-project), [NUnit](#nunit-project), or [xUnit](#xunit-project) test project with project references to the [**AspireSample.AppHost**](#app-host) and an example _WebTests.cs_ file demonstrating an integration test.
 
+<a name="python-app"></a>
+
+- **Aspire Python App**: A full-stack Aspire application with a Python backend and a JavaScript frontend. This template uses a file-based AppHost and includes:
+
+  - **apphost.cs**: A file-based AppHost that orchestrates the Python backend and the JavaScript frontend. It also includes a Redis cache in the solution.
+  - **app**: A Python backend that uses the [FastAPI](https://fastapi.tiangolo.com/) framework with OpenTelemetry instrumentation.
+  - **frontend**: A JavaScript frontend using the [React](https://react.dev/) framework with [Vite](https://vite.dev).
+
+> [!NOTE]
+> You can't yet use the Aspire Python App template in Visual Studio.
+
 ### Project templates
 
 The following Aspire project templates are available:
@@ -96,18 +107,27 @@ To create an Aspire solution or project using the .NET CLI, use the [dotnet new]
 
 To create a basic [Aspire AppHost](app-host-overview.md) project targeting the latest .NET version:
 
-```dotnetcli
-dotnet new aspire-apphost
+```Aspire
+aspire new aspire-apphost
 ```
 
 To create an Aspire starter app, which is a full solution with a sample UI and backing API included:
 
-```dotnetcli
-dotnet new aspire-starter
+```Aspire
+aspire new aspire-starter
 ```
 
+To create an Aspire app with a Python backend and JavaScript frontend:
+
+```Aspire
+aspire new aspire-py-starter
+```
+
+> [!NOTE]
+> The `aspire-py-starter` template is currently under development. For more information, see [Build an Aspire app with Python and JavaScript](../get-started/build-aspire-python-app.md).
+
 > [!TIP]
-> Aspire templates default to using the latest .NET version, even when using an earlier version of the .NET CLI. To manually specify the .NET version, use the `--framework <tfm>` option, e.g. to create a basic [Aspire AppHost](app-host-overview.md) project targeting .NET 8:
+> Aspire templates default to using the latest .NET version. To manually specify the .NET version, use the .NET CLI with the `--framework <tfm>` option, for example to create a basic [Aspire AppHost](app-host-overview.md) project targeting .NET 8:
 >
 > ```dotnetcli
 > dotnet new aspire-apphost --framework net8.0

docs/get-started/build-aspire-apps-with-python.md

@@ -1,16 +1,21 @@
 ---
 title: Orchestrate Python apps in Aspire
-description: Learn how to integrate Python apps into an Aspire AppHost project.
-ms.date: 04/15/2025
+description: Learn how to integrate existing Python apps into an Aspire solution.
+ms.date: 10/17/2025
 ms.custom: sfi-image-nochange
 ---
 
 # Orchestrate Python apps in Aspire
 
-In this article, you learn how to use Python apps in an Aspire AppHost. The sample app in this article demonstrates launching a Python application. The Python extension for Aspire requires the use of virtual environments.
+In this article, you learn how to add existing Python applications to an Aspire solution. This approach is ideal when you have an existing Python codebase and want to add Aspire orchestration and observability to it. The sample app in this article demonstrates launching a Python application with [Flask](https://flask.palletsprojects.com/en/stable/). The Python extension for Aspire requires the use of virtual environments.
+
+> [!TIP]
+> If you're starting a new project from scratch, consider using the Aspire Python template instead. See [Build an Aspire app with Python and JavaScript](build-aspire-python-app.md) for more information.
 
 [!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)]
 
+This tutorial also assumes that you have installed the Aspire CLI. For further instructions, see [Install Aspire CLI](../cli/install.md).
+
 Additionally, you need to install [Python](https://www.python.org/downloads) on your machine. The sample app in this article was built with Python version 3.12.4 and pip version 24.1.2. To verify your Python and pip versions, run the following commands:
 
 ```console
@@ -27,9 +32,20 @@ To download Python (including `pip`), see the [Python download page](https://www
 
 To get started launching a Python project in Aspire, use the starter template to first create an Aspire application host:
 
-```dotnetcli
-dotnet new aspire -o PythonSample
-```
+1. Use the following Aspire CLI command:
+
+    ```Aspire
+    aspire new
+    ```
+
+1. To select the **Starter template**, press <kbd>Enter</kbd>.
+1. For the **project name** type **PythonSample** and then press <kbd>Enter</kbd>.
+1. For the output path, press <kbd>Enter</kbd> to accept the default.
+1. To choose the default template version, press <kbd>Enter</kbd>.
+1. For **Use Redis Cache**, choose **No**.
+1. For **Do you want to create a test project?**, choose **No**.
+
+The Aspire CLI fetches the correct template and uses it to create a new Aspire solution in the **PythonSample** folder.
 
 In the same terminal session, change directories into the newly created project:
 
@@ -39,11 +55,15 @@ cd PythonSample
 
 After the template is created, launch the AppHost with the following command to ensure that the AppHost and the [Aspire dashboard](../fundamentals/dashboard/overview.md) run successfully:
 
-```dotnetcli
-dotnet run --project ./PythonSample.AppHost/PythonSample.AppHost.csproj
+```Aspire
+aspire run
 ```
 
-If the Aspire Dashboard doesn't open, open it with the link in the console output. At this point the dashboard won't show any resources. Stop the AppHost by pressing <kbd>Ctrl + C</kbd> in the terminal.
+The Aspire CLI runs the solution and displays some information about it. To access the Aspire dashboard, hold down <kbd>CTRL</kbd> and then select the **Dashboard** URL.
+
+:::image source="media/aspire-run-access-dashboard.png" lightbox="media/aspire-run-access-dashboard.png" alt-text="Screenshot showing how to access the Aspire dashboard from the output of the Aspire CLI.":::
+
+At this point the dashboard won't show any resources. Stop the AppHost by pressing <kbd>Ctrl + C</kbd> in the terminal.
 
 ## Prepare a Python app
 
@@ -128,17 +148,19 @@ The preceding code creates a simple Flask app that listens on port 8111 and retu
 
 Install the Python hosting package by running the following command:
 
-```dotnetcli
-dotnet add ../PythonSample.AppHost/PythonSample.AppHost.csproj package Aspire.Hosting.Python --version 9.0.0
+```Aspire
+aspire add
 ```
 
+Use the arrow keys to select the **python (Aspire.Hosting.Python)** hosting integration and then press <kbd>Enter</kbd>. Then press <kbd>Enter</kbd> again to select the default version. The Aspire CLI adds the Python hosting integration to the Aspire AppHost project.
+
 After the package is installed, the project XML should have a new package reference similar to the following example:
 
 :::code language="xml" source="snippets/PythonSample/PythonSample.AppHost/PythonSample.AppHost.csproj" highlight="15":::
 
 Replace the _AppHost.cs_ code with the following snippet. This code adds the Python project to Aspire by calling the `AddPythonApp` API and specifying the project name, project path, and the entry point file:
 
-:::code source="snippets/PythonSample/PythonSample.AppHost/AppHost.cs" highlight="6":::
+:::code source="snippets/PythonSample/PythonSample.AppHost/AppHost.cs" highlight="5-15":::
 
 > [!IMPORTANT]
 > The preceding code suppresses the `ASPIREHOSTINGPYTHON001` diagnostic error. This error is generated because the `AddPythonApp` API is experimental and might change in future release. For more information, see [Compiler Error ASPIREHOSTINGPYTHON001](../diagnostics/aspirehostingpython001.md).
@@ -147,15 +169,15 @@ Replace the _AppHost.cs_ code with the following snippet. This code adds the Pyt
 
 Now that you've added the Python hosting package, updated the _AppHost.cs_ file, and created a Python project, you can run the AppHost:
 
-```dotnetcli
-dotnet run --project ../PythonSample.AppHost/PythonSample.AppHost.csproj
+```Aspire
+aspire run
 ```
 
 Launch the dashboard by clicking the link in the console output. The dashboard should display the Python project as a resource.
 
 :::image source="media/python-dashboard.png" lightbox="media/python-dashboard.png" alt-text="Aspire dashboard: Python sample app.":::
 
-Select the **Endpoints** link to open the `hello-python` endpoint in a new browser tab. The browser should display the message "Hello, World!":
+Select the **URLs** link to open the `hello-python` endpoint in a new browser tab. The browser should display the message "Hello, World!":
 
 :::image source="media/python-hello-world.png" lightbox="media/python-hello-world.png" alt-text="Aspire dashboard: Python sample app endpoint.":::
 
@@ -194,10 +216,70 @@ Once the AppHost is running, navigate to the dashboard and select the **Structur
 
 :::image source="media/python-telemetry-in-dashboard.png" lightbox="media/python-telemetry-in-dashboard.png" alt-text="Aspire dashboard: Structured logging from Python process.":::
 
+## Onboard existing Python applications
+
+If you have an existing Python application that you want to add to Aspire, here are some key considerations and best practices:
+
+### Common Python frameworks
+
+Aspire works with various Python web frameworks. The most common ones include:
+
+- **[Flask](https://flask.palletsprojects.com/en/stable/)**: A lightweight WSGI web application framework.
+- **[FastAPI](https://fastapi.tiangolo.com/)**: A modern, fast web framework for building APIs with Python.
+- **[Django](https://www.djangoproject.com/)**: A high-level web framework that encourages rapid development.
+
+The integration process is similar across frameworks:
+
+1. Ensure your application can read configuration from environment variables.
+1. Add OpenTelemetry instrumentation for observability.
+1. Use the `AddPythonApp` API in your AppHost to orchestrate the application.
+
+### Migration tips
+
+When migrating an existing Python application to Aspire:
+
+1. **Virtual environments**: Ensure your application uses a virtual environment (`.venv` directory).
+1. **Dependencies**: List all dependencies in a `requirements.txt` file.
+1. **Configuration**: Use environment variables for configuration instead of hardcoded values.
+1. **Port binding**: Make your application read the port from an environment variable (commonly `PORT`).
+1. **Logging**: Configure logging to work with OpenTelemetry for better observability.
+
+### Common pitfalls
+
+Be aware of these common issues when onboarding Python apps:
+
+- **Certificate issues**: When running locally, you might need to set `ASPIRE_ALLOW_UNSECURED_TRANSPORT=true` in your AppHost launch settings.
+- **Path issues**: Ensure the path to your Python entry point file is correct relative to the AppHost project.
+- **Virtual environment activation**: The `AddPythonApp` API handles virtual environment activation automatically—you don't need to activate it manually.
+- **Python version compatibility**: Ensure your Python version is compatible with the packages you're using.
+
+### Multiple Python services
+
+If you have multiple Python services, you can add them all to the same AppHost:
+
+```csharp
+var builder = DistributedApplication.CreateBuilder(args);
+
+var pythonApi = builder.AddPythonApp("python-api", "../python-api", "main.py")
+    .WithHttpEndpoint(port: 8111);
+
+var pythonWorker = builder.AddPythonApp("python-worker", "../python-worker", "worker.py");
+
+builder.Build().Run();
+```
+
 ## Summary
 
-While there are several considerations that are beyond the scope of this article, you learned how to build Aspire solution that integrates with Python. You also learned how to use the `AddPythonApp` API to host Python apps.
+In this article, you learned how to integrate existing Python applications into an Aspire solution. You learned how to:
+
+- Prepare a Python application with a virtual environment.
+- Install the Aspire Python hosting package.
+- Use the `AddPythonApp` API in the AppHost to orchestrate Python apps.
+- Add OpenTelemetry for observability.
+- Handle common pitfalls and best practices for migrating existing Python apps.
 
 ## See also
 
+- [Build an Aspire app with Python and JavaScript](build-aspire-python-app.md)
 - [GitHub: Aspire Samples—Python hosting integration](https://github.com/dotnet/aspire-samples/tree/main/samples/AspireWithPython)
+- [GitHub: Aspire issue #11865 - Python Templates](https://github.com/dotnet/aspire/issues/11865)