doc: when to use isrequired
Review Request #1657 - Created Jan. 23, 2015 and submitted
Issue left behind a previous change: "This page used to say to use require_data and is_required. This is likely no longer true. I removed the misleading text, but didn't take the time then to find out The Right Way..." Specifically, I wasn't sure what to do about "expensive" products, for which a Task wants to ask "should I just do the regular, or should I also do the expensive thing?"
What you write is true enough today - I've expanded on the truth and you can take it or leave it. The isrequired bit will be killed by the new tuple-based engine discussed at the summit.
This is true but there is more to it. The return value of
isrequiredis a predicate function over targets or None, so its truthy, not True/False. The idea is if
isrequiredreturns a non-None/Truthy predicate, you can further find out what targets the product type is needed for in-particular by passing the context targets (or the subset you normally operate on) through the predicate.
Only 2 tasks use this extra feature today:
$ find src -name "*.py" | xargs grep "\.isrequired" | grep -v if src/python/pants/backend/jvm/tasks/ivy_resolve.py: create_jardeps_for = self.context.products.isrequired('jar_dependencies') src/python/pants/backend/jvm/tasks/jvmdoc_gen.py: catalog = self.context.products.isrequired(self.jvmdoc().product_type)
Now all that - this mechanism is broken today. I'll have a review to you shortly that corrects the broken bit.