uploader: simplify Python implementation for review

Reduce orchestration and transport duplication, clarify module boundaries and lifecycle reporting, and centralize uploader test runfile setup. Keep the existing uploader behavior while making the implementation and migration tracker easier to review and maintain.

Validated with the 449-test Python tooling suite, all 199 //tools tests, shellcheck, PowerShell parsing, buildifier, compileall, and git diff checks.

Author: tonyredondo

.github/workflows/ci.yml

@@ -4,6 +4,9 @@
 # This product includes software developed at Datadog
 # (https://www.datadoghq.com/) Copyright 2025-Present Datadog, Inc.
 
+# Validate supported hosts and generated consumer artifacts before merge.
+# The uploader smoke catches launcher/runfiles failures that imports cannot expose.
+
 name: CI
 
 on:

docs/python_parallel_uploader_migration_plan.md

@@ -4,6 +4,9 @@
 # This product includes software developed at Datadog
 # (https://www.datadoghq.com/) Copyright 2025-Present Datadog, Inc.
 
+# Export host-side Test Optimization tools and their dependency-free runtimes.
+# The uploader sources are runfiles because consumers execute them after Bazel tests.
+
 exports_files(
     [
         "bep_artifact_stage_helper.py",

tools/core/BUILD.bazel

@@ -4,4 +4,7 @@
 # This product includes software developed at Datadog
 # (https://www.datadoghq.com/) Copyright 2025-Present Datadog, Inc.
 
-"""Shared, dependency-free runtime helpers for Test Optimization tools."""
+"""Dependency-free helpers shared by executable Test Optimization tools.
+
+This package keeps host-side infrastructure independent from uploader internals.
+"""

tools/core/topt_runtime/__init__.py

@@ -4,7 +4,10 @@
 # This product includes software developed at Datadog
 # (https://www.datadoghq.com/) Copyright 2025-Present Datadog, Inc.
 
-"""Immutable runfiles lookup prepared once before uploader workers start."""
+"""Resolve Bazel runfiles into one immutable lookup snapshot.
+
+Centralizing lookup keeps launchers portable and workers isolated from env changes.
+"""
 
 from __future__ import annotations
 

tools/core/topt_runtime/runfiles.py

@@ -5,7 +5,10 @@
 # This product includes software developed at Datadog
 # (https://www.datadoghq.com/) Copyright 2025-Present Datadog, Inc.
 
-"""Minimal bootstrap for the cross-platform Test Optimization uploader."""
+"""Bootstrap the shared uploader package from a stable Bazel entrypoint.
+
+Keeping this file behavior-free lets both platform launchers invoke one runtime.
+"""
 
 from uploader_py.main import main
 

tools/core/uploader_main.py

@@ -4,7 +4,10 @@
 # This product includes software developed at Datadog
 # (https://www.datadoghq.com/) Copyright 2025-Present Datadog, Inc.
 
-"""Cross-platform Datadog Test Optimization uploader runtime."""
+"""Expose the stable public surface of the cross-platform uploader package.
+
+The narrow package boundary prevents callers from depending on internal stages.
+"""
 
 from .models import MAX_TEST_PAYLOAD_BYTES