docs

Author: aignas

python/private/attributes.bzl

@@ -260,7 +260,7 @@ The order of this list can matter because it affects the order that information
 from dependencies is merged in, which can be relevant depending on the ordering
 mode of depsets that are merged.
 
-* {obj}`PyInfo.venv_symlinks` uses topological ordering.
+* {obj}`PyInfo.venv_symlinks` uses default ordering.
 
 See {obj}`PyInfo` for more information about the ordering of its depsets and
 how its fields are merged.

python/private/common.bzl

@@ -373,8 +373,8 @@ def _third_party_first(targets):
     """Sort targets to allow for deterministic depset merging.
 
     First return the third party deps so that the depsets get merged in a way to allow
-    topological traversal so that the first dependency that is met during traversing
-    will be a third party dep.
+    traversal so that the first dependency that is met during traversing will be a third party
+    dep.
 
     This is because the DAG is going from first-party deps to third-party deps and usually
     no third-party deps include first-party deps.

python/private/py_executable.bzl

@@ -650,10 +650,6 @@ def _create_venv_symlinks(ctx, venv_dir_map):
 
     # maps venv-relative path to the runfiles path it should point to
     entries = depset(
-        # NOTE: Topological ordering is used so that dependencies closer to the
-        # binary have precedence in creating their symlinks. This allows the
-        # binary a modicum of control over the result.
-        order = "topological",
         transitive = [
             dep[PyInfo].venv_symlinks
             for dep in ctx.attr.deps
@@ -692,7 +688,8 @@ def _build_link_map(entries):
 
         if version_by_pkg.setdefault(entry.package, entry.version) != entry.version:
             # We ignore duplicates by design. The dependency closer to the
-            # binary gets precedence due to the topological ordering.
+            # binary gets precedence due to how we merge the third_party dependencies
+            # first.
             continue
         elif entry.venv_path in kind_map:
             # NOTE @aignas 2025-06-05: This branch should be hit only for first party
@@ -701,9 +698,9 @@ def _build_link_map(entries):
         else:
             kind_map[entry.venv_path] = entry.link_to_path
 
-    # An empty link_to value means to not create the site package symlink.
-    # Because of the topological ordering, this allows binaries to remove
-    # entries by having an earlier dependency produce empty link_to values.
+    # An empty link_to value means to not create the site package symlink. Because of the
+    # ordering, this allows binaries to remove entries by having an earlier dependency produce
+    # empty link_to values.
     for link_map in pkg_link_map.values():
         for kind, kind_map in link_map.items():
             for dir_path, link_to in kind_map.items():

python/private/py_info.bzl

@@ -115,7 +115,7 @@ def _PyInfo_init(
         transitive_original_sources = depset(),
         direct_pyi_files = depset(),
         transitive_pyi_files = depset(),
-        venv_symlinks = depset(order = "topological")):
+        venv_symlinks = depset()):
     _check_arg_type("transitive_sources", "depset", transitive_sources)
 
     # Verify it's postorder compatible, but retain is original ordering.
@@ -220,7 +220,15 @@ Python targets. These are accumulated from the transitive `deps`.
 The order of the depset is not guaranteed and may be changed in the future. It
 is recommended to use `default` order (the default).
 """,
-        "package": "TODO",
+        "package": """
+:type: str
+
+The source third-party dependency name, which is normalized to PEP440 schema with
+`-` replaced with `_`.
+
+::::{versionadded} VERSION_NEXT_FEATURE
+::::
+""",
         "transitive_implicit_pyc_files": """
 :type: depset[File]
 
@@ -312,13 +320,13 @@ This field is currently unused in Bazel and may go away in the future.
         "venv_symlinks": """
 :type: depset[VenvSymlinkEntry]
 
-A depset with `topological` ordering.
+A depset with default ordering.
 
 :::{include} /_includes/experimental_api.md
 :::
 
 :::{tip}
-The topological ordering means dependencies earlier and closer to the consumer
+The way we merge depsets means dependencies earlier and closer to the consumer
 have precedence. This allows e.g. a binary to add dependencies that override
 values from further way dependencies, such as forcing symlinks to point to
 specific paths or preventing symlinks from being created.
@@ -380,9 +388,6 @@ def _PyInfoBuilder_typedef():
 
     :::{field} venv_symlinks
     :type: DepsetBuilder[tuple[str | None, str]]
-
-    NOTE: This depset has `topological` order
-    :::
     """
 
 def _PyInfoBuilder_new():
@@ -422,7 +427,7 @@ def _PyInfoBuilder_new():
         transitive_pyc_files = builders.DepsetBuilder(),
         transitive_pyi_files = builders.DepsetBuilder(),
         transitive_sources = builders.DepsetBuilder(),
-        venv_symlinks = builders.DepsetBuilder(order = "topological"),
+        venv_symlinks = builders.DepsetBuilder(),
     )
     return self
 

python/private/py_library.bzl

@@ -92,14 +92,18 @@ won't be understood as namespace packages; they'll be seen as regular packages.
 likely lead to conflicts with other targets that contribute to the namespace.
 
 :::{tip}
-This attributes populates {obj}`PyInfo.venv_symlinks`, which is
-a topologically ordered depset. This means dependencies closer and earlier
+This attributes populates {obj}`PyInfo.venv_symlinks` a custom ordered depset - third party dependencies come first when the depsets are merged. This means dependencies closer and earlier
 to a consumer have precedence. See {obj}`PyInfo.venv_symlinks` for
 more information.
 :::
 
 :::{versionadded} 1.4.0
 :::
+:::{versionchanged} VERSION_NEXT_FEATURE
+The topological order has been reverted and instead we merge the depsets for all of the
+targets in the {attr}`py_library.deps` in a particular way - first merging depsets
+of the third-party PyPI dependencies and then merging the first-party dependencies.
+:::
 """,
         ),
         "_add_srcs_to_runfiles_flag": lambda: attrb.Label(