The point is that it acts like __length_hint__
. It’s for situations where having a good guess now is better than having the exact right answer later. The canonical use case I mentioned would be if you are using a distributed workflow to do some sort of dependency resolution. For example, some pseudocode:
def dependency_graph(pkg, _node_cache={}) -> Node:
if pkg_name in _node_cache:
return _node_cache[pkg_name]
# To make it more compact I'm assuming we need to use sdists,
# though in practice we'd only hit this branch if no wheel is
# available.
sdist = get_sdist(pkg) # Blocking, expensive
metadata = get_sdist_metadata(pkg_name)
# BLOCK 1
if metadata.needs_build("Provides-Dist"):
for dep in metadata.provides_dist:
# Assume this is non-blocking; for brevity's sake
# I have skipped any cancellation or de-duplication logic
thread_pool.add(dependency_graph, dep)
metadata = get_wheel_metadata(sdist) # Blocking, expensive
node = Node(metadata.name, metadata.version)
# BLOCK 2
for dep in metadata.provides_dist:
node.add_dependency(dependency_graph(dep))
return _node_cache.setdefault(pkg, node)
Obviously I’ve left out a lot of details there, but you can see the idea — in Block 1, you use the “hint” here to warm the cache in another thread or process while you are waiting for the build backend to get you the canonical answer to “what dependencies are available”. In most cases, the hint will be very close to accurate, so when you get to block 2, resolve_dependencies
would hit the cache.
You could also imagine this sort of thing being used in a situation where you care more about not doing builds than you care about getting the right answer. “I don’t want to execute arbitrary Python code, but I want an estimate of what this dependency graph looks like”. The choices there are to completely ignore any nodes in the dependency graph that don’t supply wheels or to use the hint and get something that is probably pretty close to what you’d expect.
“A field is marked Dynamic
in a wheel if it would be marked Dynamic
when building an sdist.”
TBH I’m not entirely sure what’s confusing about it. What situations can you imagine where this would lead to ambiguity? What actions would you take or not take based on it being marked Dynamic
in a wheel?