From 64c43ea417b52c6acebf02e0d50bec8c289fe90a Mon Sep 17 00:00:00 2001
From: Julio Castillo <jccb@google.com>
Date: Sat, 28 Jun 2025 20:48:07 +0200
Subject: [PATCH] Add PEP 723 dependencies to tfdoc.py, versions.py and
 build_service_agents.py (#3203)

---
 CONTRIBUTING.md               |  2 ++
 tools/build_service_agents.py | 18 ++++++++++++++++++
 tools/tfdoc.py                | 10 +++++++++-
 tools/versions.py             |  7 +++++++
 4 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5204f6b40..ad0f08af9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -634,6 +634,8 @@ pip install -r tests/requirements.txt
 pip install -r tools/requirements.txt
 ```
 
+Some of our tools declare their dependencies in a [PEP 723-style](https://peps.python.org/pep-0723/) format, allowing you to execute them directly with `uv run`. For instance, `tools/tfdoc.py` includes its dependencies inline. As a result, when you run `uv run tools/tfdoc.py`, `uv` will automatically download the necessary dependencies for you.
+
 #### Automated checks on PRs
 
 We run two GitHub workflows on PRs:
diff --git a/tools/build_service_agents.py b/tools/build_service_agents.py
index 8dc023d8f..55b4ff573 100755
--- a/tools/build_service_agents.py
+++ b/tools/build_service_agents.py
@@ -13,6 +13,16 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+#
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#    "BeautifulSoup4",
+#    "click",
+#    "requests",
+#    "pyyaml",
+# ]
+# ///
 
 from dataclasses import asdict, dataclass
 from itertools import chain
@@ -43,6 +53,11 @@ ALIASES = {
     'serverless-robot-prod': ['cloudrun', 'run'],
 }
 
+IGNORED_AGENTS = [
+    # Alloydb has two agents. Ignore the non-primary one
+    'c-PROJECT_NUMBER-IDENTIFIER@gcp-sa-alloydb.iam.gserviceaccount.com'
+]
+
 E2E_SERVICES = [
     "alloydb.googleapis.com",
     "analyticshub.googleapis.com",
@@ -110,6 +125,9 @@ def main(e2e=False):
       continue
 
     identity = col1.p.get_text()
+    if identity in IGNORED_AGENTS:
+      continue
+
     # skip agents that are not contained in a project
     if 'PROJECT_NUMBER' not in identity:
       continue
diff --git a/tools/tfdoc.py b/tools/tfdoc.py
index 9cbd17d74..fb764195c 100755
--- a/tools/tfdoc.py
+++ b/tools/tfdoc.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -13,6 +13,14 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+#
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#    "click",
+#    "marko",
+# ]
+# ///
 '''Generate tables for Terraform root module files, outputs and variables.
 
 This tool generates nicely formatted Markdown tables from Terraform source
diff --git a/tools/versions.py b/tools/versions.py
index 2960e8ff3..7fe189f10 100755
--- a/tools/versions.py
+++ b/tools/versions.py
@@ -13,6 +13,13 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+#
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#    "click",
+# ]
+# ///
 
 import re
 from pathlib import Path