Output hiding about invoke HOT 8 CLOSED

I've got this working; see 6583973 and friends. run("command", hide=True) is the API for the time being, and hides both stdout and stderr. I didn't think it was worth it to split it into different kwargs at this point in time.

On the other hand there are legit use cases for hiding either/or/both, and if we don't do it now, we might paint ourselves into an API corner. So.

Options:

• Current implementation: hide hides both, unable to hide just one or the other by default.
  • Unacceptable for many advanced use cases, e.g. hide normal output for command foo but show any (unexpected) stderr in case of problems.
• hide hides both, hide_stdout hides just stdout, hide_stderr ditto.
  • 3 kwargs == inflated API, not great/kinda ugly.
  • Handling edge cases, e.g. run("command", hide=True, hide_stderr=False) would be extra code/possible bugs, and more mental burden for users.
• hide hides stdout only, hide_stderr hides stderr, must give both to hide both.
  • Only 2 kwargs, matches some APIs I've seen before
  • But no handy one-shot when you want full hiding.
    • Unless we go the @mattrobenolt route and provide a convenience global value equal to {'hide': True, 'hide_stderr', True}, and suggest to users that they can: run("command", **hide_both) or similar.
• Variant of the above: the two kwargs are simply stdout and stderr and default to True; set to False to hide either/both.
  • Still no handy one-shot (again barring the global+kwargs option above)
  • Also slightly confusing, since we are still capturing these streams, just not showing them. (Minor, but still.)
  • But slightly less verbose than the other incarnation, and more explicit. Other version's hide name doesn't obviously imply "just stdout".
• A single hide (or inverse show) kwarg that takes a variable argument determining what to do, e.g. hide='stdout' or show='both' (though as that would be default, you'd only use it as show=None or `show='neither').
  • Smallest API, same in all cases
  • Doesn't play well with advanced uses like kwarg composition (e.g. where one may be combining kwarg dicts and desire to override just one stream's option without necessarily knowing what the current value is). Not sure that's a sufficient argument against.
  • Potential for typos (could use constants, though I am unsure if that is a worthwhile tradeoff.)

from invoke.

I think that invoke API would be best improved by using hide to hide stdout and using hide_stderr to hide stderr.

That being said I think most use cases would be hiding stdout. so the difference in naming hide vs hide_stderr is alright.

Unfortunate that they aren't as explicit as they can be but I feel that hide adequately describes what is being done. Plus there is always documentation to clarify the ambiguity of hide vs. simply using stdout

from invoke.

@myusuf3 What are your thoughts on the now-revised 4th option, run("command", hide='stderr')? I am actually leaning that way myself now.

from invoke.

I actually dont mind that interface. What I dont like is the cumbersome show kwarg it adds confusion and I dont see it being used much at all since people want granular control of output.

Unless we make everything default off, and do something like show='stderr', show='stdout', or show='both' that might be hawtness.

from invoke.

No, I think hide makes more sense than show, given that showing is the default behavior. (And I may not have been clear, but that 4th option didn't mean to have both hide and show existing -- just one or the other.)

from invoke.

In that case, hide in the way show was used above makes most sense.

from invoke.

I've expanded the implementation as follows:

• run(hide=None) is the default and hides nothing.
• run(hide='out') hides just stdout. Note I shortened the identifier; 'std' is superfluous IMO.
• run(hide='err') hides just stderr.
• run(hide='both') hides both streams.

This is actually implemented inside run with a normalizer that turns that argument into a tuple like (), ('out',) or ('out', 'err'), as that simplifies the behavior in the Popen subclass that actually implements printing-to-stream.

Given that reality I am leaning slightly towards @mattrobenolt's suggestion of having this iterable value be the public API too, and using "constants" as convenient shortcuts. E.g.:

• run(hide=[]) would be the new default
• run(hide=['out']) would be the "literal" way of hiding stdout
• from module import OUT; run(hide=OUT) would be the "convenient" way of hiding stdout (where module.OUT == ['out'])
  • I'm really not sure I want to use all-caps, though, so it might be out or maybe streams.out or whatever.
• from module import BOTH; run(hide=BOTH) would be the convenient way of hiding both streams.

However I still think the current/latest implementation is the best marriage of flexibility & terseness, so I will close this for now, with the strong possibility of changing it prior to 1.0. (Not only maybe changing it to the above, but also returning to one of the multi-kwarg options, as I feel shitty about locking out proper functional-style kwarg composition.)

from invoke.

👍

from invoke.