Update Rules_Py & Consolidate internal structure (#378)

Change all 'os.getenv[RUNFILES]' to now use the find_runfiles file.
This is in preperation for the rules_python upgrade which changes this
implementation again.

The solution to the upgrade of the Runfiles was based on the work from @NEOatNHNG and his commit: dbb6261
And also done with the help of @PiotrKorkus

Author: MaximilianSoerenPollak

MODULE.bazel

@@ -30,7 +30,7 @@ bazel_dep(name = "rules_pkg", version = "1.1.0")
 # Python version
 #
 ###############################################################################
-bazel_dep(name = "rules_python", version = "1.4.1")
+bazel_dep(name = "rules_python", version = "1.8.3")
 
 PYTHON_VERSION = "3.12"
 
@@ -109,7 +109,7 @@ git_override(
 
 # Add Linter
 bazel_dep(name = "rules_multitool", version = "1.9.0")
-bazel_dep(name = "score_tooling", version = "1.0.5")
+bazel_dep(name = "score_tooling", version = "1.1.0")
 
 multitool_root = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")
 use_repo(multitool_root, "actionlint_hub", "multitool", "ruff_hub", "shellcheck_hub", "yamlfmt_hub")

src/BUILD

@@ -42,7 +42,6 @@ filegroup(
         "//src/extensions/score_source_code_linker:all_sources",
         "//src/extensions/score_sphinx_bundle:all_sources",
         "//src/extensions/score_sync_toml:all_sources",
-        "//src/find_runfiles:all_sources",
         "//src/helper_lib:all_sources",
     ],
     visibility = ["//visibility:public"],

src/extensions/BUILD

@@ -20,4 +20,5 @@ py_library(
     srcs = ["@score_docs_as_code//src/extensions:score_plantuml.py"],
     imports = ["."],
     visibility = ["//visibility:public"],
+    deps = ["@score_docs_as_code//src/helper_lib"],
 )

src/extensions/score_metamodel/BUILD

@@ -49,7 +49,9 @@ py_library(
     imports = ["."],
     visibility = ["//visibility:public"],
     # TODO: Figure out if all requirements are needed or if we can break it down a bit
-    deps = all_requirements + ["@score_docs_as_code//src/helper_lib"],
+    deps = all_requirements + [
+        "@score_docs_as_code//src/helper_lib",
+    ],
 )
 
 score_py_pytest(

src/extensions/score_metamodel/external_needs.py

@@ -12,9 +12,7 @@
 # *******************************************************************************
 
 import json
-import os
 import subprocess
-import sys
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -23,6 +21,8 @@
 from sphinx.util import logging
 from sphinx_needs.needsfile import NeedsList
 
+from src.helper_lib import get_runfiles_dir
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,6 +61,7 @@ def parse_external_needs_sources_from_DATA(v: str) -> list[ExternalNeedsSource]:
         return []
 
     logger.debug(f"Parsing external needs sources: {v}")
+
     data = json.loads(v)
 
     res = [res for el in data if (res := _parse_bazel_external_need(el))]
@@ -138,37 +139,21 @@ def temp(self: NeedsList):
 
 
 def get_external_needs_source(external_needs_source: str) -> list[ExternalNeedsSource]:
-    bazel = external_needs_source or os.getenv("RUNFILES_DIR")
-
-    if bazel:
+    if external_needs_source:
+        # Path taken for all invocations via `bazel`
         external_needs = parse_external_needs_sources_from_DATA(external_needs_source)
     else:
+        # This is the path taken for anything that doesn't
+        # run via `bazel`  e.g. esbonio or other direct executions
         external_needs = parse_external_needs_sources_from_bazel_query()  # pyright: ignore[reportAny]
-
     return external_needs
 
 
 def add_external_needs_json(e: ExternalNeedsSource, config: Config):
-    json_file = f"{e.bazel_module}+/{e.target}/_build/needs/needs.json"
-    if r := os.getenv("RUNFILES_DIR"):
-        logger.debug("Using runfiles to determine external needs JSON file.")
-        fixed_json_file = Path(r) / json_file
-    else:
-        logger.debug(
-            "Running outside bazel. "
-            + "Determining git root for external needs JSON file."
-        )
-        git_root = Path.cwd().resolve()
-        while not (git_root / ".git").exists():
-            git_root = git_root.parent
-            if git_root == Path("/"):
-                sys.exit("Could not find git root.")
-        logger.debug(f"Git root found: {git_root}")
-        fixed_json_file = git_root / "bazel-bin" / "ide_support.runfiles" / json_file
-
-    logger.debug(f"Fixed JSON file path: {json_file} -> {fixed_json_file}")
-    json_file = fixed_json_file
-
+    json_file_raw = f"{e.bazel_module}+/{e.target}/_build/needs/needs.json"
+    r = get_runfiles_dir()
+    json_file = r / json_file_raw
+    logger.debug(f"External needs.json: {json_file}")
     try:
         needs_json_data = json.loads(Path(json_file).read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
     except FileNotFoundError:
@@ -192,11 +177,11 @@ def add_external_needs_json(e: ExternalNeedsSource, config: Config):
 def add_external_docs_sources(e: ExternalNeedsSource, config: Config):
     # Note that bazel does NOT write the files under e.target!
     # {e.bazel_module}+ matches the original git layout!
-    if r := os.getenv("RUNFILES_DIR"):
-        docs_source_path = Path(r) / f"{e.bazel_module}+"
-    else:
+    r = get_runfiles_dir()
+    if "ide_support.runfiles" in str(r):
         logger.error("Combo builds are currently only supported with Bazel.")
         return
+    docs_source_path = Path(r) / f"{e.bazel_module}+"
 
     if "collections" not in config:
         config.collections = {}

src/extensions/score_plantuml.py

@@ -24,48 +24,14 @@
 In addition it sets common PlantUML options, like output to svg_obj.
 """
 
-import os
-import sys
 from pathlib import Path
 
 from sphinx.application import Sphinx
 from sphinx.util import logging
 
-logger = logging.getLogger(__name__)
-
-
-def get_runfiles_dir() -> Path:
-    if r := os.getenv("RUNFILES_DIR"):
-        # Runfiles are only available when running in Bazel.
-        # bazel build and bazel run are both supported.
-        # i.e. `bazel build //:docs` and `bazel run //:docs`.
-        logger.debug("Using runfiles to determine plantuml path.")
+from src.helper_lib import get_runfiles_dir
 
-        runfiles_dir = Path(r)
-
-    else:
-        # The only way to land here is when running from within the virtual
-        # environment created by the `:ide_support` rule in the BUILD file.
-        # i.e. esbonio or manual sphinx-build execution within the virtual
-        # environment.
-        # We'll still use the plantuml binary from the bazel build.
-        # But we need to find it first.
-        logger.debug("Running outside bazel.")
-
-        git_root = Path.cwd().resolve()
-        while not (git_root / ".git").exists():
-            git_root = git_root.parent
-            if git_root == Path("/"):
-                sys.exit("Could not find git root.")
-
-        runfiles_dir = git_root / "bazel-bin" / "ide_support.runfiles"
-
-    if not runfiles_dir.exists():
-        sys.exit(
-            f"Could not find runfiles_dir at {runfiles_dir}. "
-            "Have a look at README.md for instructions on how to build docs."
-        )
-    return runfiles_dir
+logger = logging.getLogger(__name__)
 
 
 def find_correct_path(runfiles: Path) -> Path:

src/extensions/score_sphinx_bundle/BUILD

@@ -31,7 +31,6 @@ py_library(
         "@score_docs_as_code//src/extensions/score_metamodel",
         "@score_docs_as_code//src/extensions/score_source_code_linker",
         "@score_docs_as_code//src/extensions/score_sync_toml",
-        "@score_docs_as_code//src/find_runfiles",
         "@score_docs_as_code//src/helper_lib",
     ],
 )