Fixes wheel submodules discoverability

[kellyguo11]

Description

Fix wheel building process to make submodules discoverable on existing .kit files.
Add rlgames back into the prebuilt wheel.

Type of change

• Documentation update

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have updated the changelog and the corresponding version in the extension's config/extension.toml file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot — PR #5907

Summary

This PR fixes wheel submodule discoverability by preserving config/extension.toml for Kit extension resolution, adds rl-games back into the prebuilt wheel, updates omni.physics.tensors imports across isaaclab_physx, and introduces a _deprioritize_prebundle_paths() utility to prevent CUDA/package conflicts from Isaac Sim's prebundle system.

---

🔬 Isaac Lab Expert

Wheel Build Fix (build.sh) ✅
The previous rm -rf "$ext_dir" nuked the entire promoted extension directory, including config/extension.toml needed by .kit experience files. The fix correctly removes only the inner Python package ($inner) and data/ while keeping the config for Kit's dependency solver. This is the right approach — promoted packages are importable from the top-level copy, but Kit still needs source/<ext>/config/extension.toml.

rl-games Re-addition ✅
Adding rl-games via git+https://github.com/isaac-sim/rl_games.git@python3.11 is reasonable since the mainline PyPI release doesn't yet support Python 3.11. The gym and standard-distutils transitive deps are explicitly included.

omni.physics.tensors.api → omni.physics.tensors ✅
This is a consistent import path correction across isaaclab_physx files. The .api submodule was presumably removed or restructured upstream. All changes place the import in TYPE_CHECKING blocks with from __future__ import annotations for deferred evaluation — the change is uniform and correct.

_deprioritize_prebundle_paths() ✅
Well-documented function that demotes conflicting paths (prebundle, warp.core, ml_archive, etc.) to the end of sys.path rather than removing them. Also rewrites PYTHONPATH for child processes. Called at package init time. Good defensive approach.

---

🔇 Silent Failure Hunter

Risk	Assessment
Missing $inner variable	⚠️ Medium — $inner is used in rm -rf "$inner" but its definition comes from the earlier block (inner="$ext_dir/$pkg"). If the earlier conditional (if [ -d "$inner" ]) fails, this rm -rf targets an empty string. However, rm -rf "" is a no-op on Linux, so this is safe in practice.
_deprioritize_prebundle_paths() runs at import time	ℹ️ Low — Mutating sys.path during __init__.py import is standard practice for Isaac Sim ecosystem. The function only demotes (never removes), so it's non-destructive.
rl-games installed from Git branch	⚠️ Medium — The @python3.11 branch pin is mutable; builds are not reproducible unless that branch is frozen. A commit SHA would be safer for CI reproducibility. However, this mirrors existing practice for this fork.
Deformable object physx import moved to TYPE_CHECKING	ℹ️ Low — Both deformable_object.py and deformable_object_data.py use physx only in type annotations (return types, parameter types, variable annotations). Both files have from __future__ import annotations, so annotations are lazily evaluated strings. Runtime usage goes through self._physics_sim_view (from PhysxManager), not the physx module directly. Safe change.

---

🧪 Test Coverage Analyzer

New test coverage ✅

• test_isaaclab_prebundle_path_sanitizer_exported — verifies _deprioritize_prebundle_paths is callable from the wheel.
• test_promoted_extensions_remain_discoverable_under_source — directly inspects the .whl ZIP layout to verify isaaclab/source/<ext>/config/extension.toml exists alongside promoted top-level packages.

Gaps:

• No test verifies that rl-games is actually installable from the [all] extra (though this would require network access in CI).
• The omni.physics.tensors import changes cannot be tested without Isaac Sim installed; this is expected.

---

🔄 Update (520733a)

New commit since last review (0c589e2→520733a):

• deformable_object.py — Moved import omni.physics.tensors as physx from top-level into TYPE_CHECKING block. The file already had from __future__ import annotations and only uses physx in type annotations (physx.DeformableBodyView return types). Runtime deformable body operations go through self._physics_sim_view, not the physx module directly.
• deformable_object_data.py — Added from __future__ import annotations and TYPE_CHECKING, moved import omni.physics.tensors as physx into TYPE_CHECKING block. Again, physx is only used for type hints (physx.DeformableBodyView in __init__ signature and variable annotation).
• changelog.d/fix-wheel-submodules.rst — Changelog entry: "Fixed PhysX tensor imports when using wheel-installed Isaac Sim packages."

This commit title ("fix deformable test") makes sense — the deformable objects were likely failing when imported from a wheel installation because omni.physics.tensors isn't available at import time in that context. Moving it behind TYPE_CHECKING aligns these two files with the pattern already applied to the rest of the PR.

No new concerns raised. The PR remains clean.

Verdict: LGTM ✅

All changes are consistent with the original PR intent. The deformable object fix completes the TYPE_CHECKING migration for omni.physics.tensors across the entire isaaclab_physx package.

---

_{🤖 Automated review by isaaclab-review-bot | Commit: 520733a}

[greptile-apps]

Greptile Summary

This PR fixes two wheel-build regressions: it corrects the build.sh cleanup step so that promoted extensions retain their config/extension.toml under isaaclab/source/ (required by Kit's dependency resolver), and re-enables rl-games as a first-class optional dependency via a Python 3.11-compatible fork. It also uniformly updates omni.physics.tensors.api → omni.physics.tensors across the isaaclab_physx sensors and assets modules to match the current Isaac Sim SDK layout.

• Wheel layout fix: build.sh now removes only the inner Python package dir and data/ from each promoted extension, leaving config/extension.toml intact so .kit experience files can resolve extension dependencies at launch.
• RL-Games re-enabled: rl-games is added back to python_packages.toml under both the rl-games extra and the all extra, sourced from a Python 3.11-compatible fork; however, the dependency is pinned to a branch name (@python3.11) rather than an immutable commit SHA, which makes builds non-reproducible.
• omni.physics.tensors import fix: All references to the deprecated .api submodule are updated across articulation, deformable-object, rigid-object, and sensor files — four of these are runtime imports and four are TYPE_CHECKING-only.

Confidence Score: 3/5

The wheel layout and physx import fixes look correct and well-tested, but the rl-games dependency is pinned to a mutable git branch rather than a commit hash, meaning installs at different times can silently diverge.

The build.sh and init.py changes are sound and backed by a new smoke test that inspects the wheel ZIP directly. The omni.physics.tensors rename is applied consistently across all affected files. The python_packages.toml change pins rl-games to the branch name python3.11 in both the rl-games extra and the all extra — a branch that can receive new commits at any time without updating the wheel's own pinning.

tools/wheel_builder/res/python_packages.toml — both rl-games occurrences need the branch ref replaced with an immutable commit SHA or tag.

Important Files Changed

Filename	Overview
tools/wheel_builder/build.sh	Replaces blanket rm -rf $ext_dir with targeted removal of only the inner Python package dir and data/, leaving config/extension.toml in place for Kit discovery — logic is correct and well-commented.
tools/wheel_builder/res/init.py	Adds _deprioritize_prebundle_paths() which demotes conflicting Isaac Sim prebundle paths to the end of sys.path and rewrites PYTHONPATH; called at module level on import. Side-effect-on-import pattern is intentional and well-documented.
tools/wheel_builder/res/python_packages.toml	Re-enables rl-games as an optional dependency; dependency is pinned to a git branch name (@python3.11) rather than a commit SHA, making builds non-reproducible — present in both the rl-games extra and the all extra.
source/isaaclab/test/install_ci/misc/test_wheel_builder_smoke.py	Adds two new smoke tests: one verifying _deprioritize_prebundle_paths is exported, and one inspecting the wheel ZIP to confirm each promoted extension retains config/extension.toml under the Kit-discoverable path.
source/isaaclab_physx/isaaclab_physx/assets/deformable_object/deformable_object.py	Runtime import changed from omni.physics.tensors.api to omni.physics.tensors; consistent with all other physx files in this PR.
docs/source/setup/installation/isaaclab_pip_installation.rst	Documentation updated to reflect RL-Games inclusion in [all] and removal of the manual git-install workaround note.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["build.sh — copy source/"] --> B["For each source/isaaclab_FOO/"]
    B --> C["Promote isaaclab_FOO/ to top-level src/isaaclab_FOO/"]
    C --> D["Copy config/ & data/ into top-level package"]
    D --> E["Patch __init__.py relative paths"]
    E --> F["OLD: rm -rf ext_dir (entire dir)"]
    E --> G["NEW: rm -rf inner_pkg_dir + ext_dir/data"]
    G --> H["config/extension.toml stays under isaaclab/source/isaaclab_FOO/config/"]
    H --> I{".kit experience file search"}
    I -->|"app/../source"| J["Kit resolves isaaclab_assets"]
    F -->|"config removed"| K["Kit: isaaclab_assets not found"]

Loading

_{Reviews (1): Last reviewed commit: "update changelog" | Re-trigger Greptile}

[greptile-apps]

Git branch pin — non-reproducible builds

@python3.11 is a branch name, not a commit hash or tag. Once this wheel configuration is published, any subsequent pip install will resolve the ref at install time and may pull a different commit if new work lands on the branch. A future push to python3.11 can silently change rl_games behavior without any change to the wheel's own metadata. Pin to an immutable ref (commit SHA or a signed tag) instead to guarantee reproducible installs.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[greptile-apps]

Duplicate branch-pinned git dependency in [all]

Same mutable @python3.11 branch reference is also present in the all extra. Both occurrences share the same reproducibility risk: concurrent pip install isaaclab[all] runs at different times can resolve to different commits. Fix both to a commit SHA or tag consistently.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!