nfpm.native_libs.deb: add usage comments

Author: cognifloyd

src/python/pants/backend/nfpm/native_libs/deb/search_for_sonames.py

@@ -1,6 +1,15 @@
 # Copyright 2025 Pants project contributors (see CONTRIBUTORS.md).
 # Licensed under the Apache License, Version 2.0 (see LICENSE).
 
+"""A standalone script that uses asyncio to find packages that contain a SONAME.
+
+Rule code should run this script as a subprocess in a sandboxed venv. Generally, that venv should
+be a subset of the pants venv (using the version of packages that pants depends on).
+
+WARNING: This script relies on aiohttp and asyncio, so their are probably incompatibilities
+with rule code in the pants engine. So, avoid importing this script in rule code.
+"""
+
 from __future__ import annotations
 
 import argparse

src/python/pants/backend/nfpm/native_libs/deb/search_for_sonames_integration_test.py

@@ -8,12 +8,17 @@
 
 import pytest
 
+from pants.backend.nfpm.native_libs.deb.rules import (
+    DebPackagesForSonames,
+    DebSearchForSonamesRequest,
+)
+from pants.backend.nfpm.native_libs.deb.rules import rules as native_libs_deb_rules
 from pants.backend.python.util_rules import pex_from_targets
 from pants.engine.rules import QueryRule
 from pants.testutil.rule_runner import RuleRunner
 
-from .rules import DebPackagesForSonames, DebSearchForSonamesRequest
-from .rules import rules as native_libs_deb_rules
+# The relative import emphasizes that `search_for_sonames` is a standalone script that runs
+# from a sandbox root (thus avoiding a dependency on the pants code structure).
 from .search_for_sonames import deb_search_for_sonames
 
 _libldap_soname = "libldap-2.5.so.0"

src/python/pants/backend/nfpm/native_libs/deb/search_for_sonames_test.py

@@ -3,6 +3,8 @@
 
 from __future__ import annotations
 
+# The relative import emphasizes that `search_for_sonames` is a standalone script that runs
+# from a sandbox root (thus avoiding a dependency on the pants code structure).
 from .search_for_sonames import deb_packages_from_html_response
 
 # simplified for readability and to keep it focused