Two more modifiers for return codes

[henryiii]

I was writing a little tutorial for plumbum and converting one of my more complex bash scripts to plumbum, and I noticed one common use that subprocess.call does well that plumbum works a little harder for. It was in checking and working with return codes. While the exception method is excellent, if you are working with, for example, git, and you want to toggle behavior based on the return code of a command (like git rev-list HEAD..origin), then you have to use .run(retcode=None)[0] or try/except blocks (which then require accessing the stdin/stderr differently in the except block).

I added two modifiers alongside FG and BG, namely TF and RETCODE, that make working with return codes easy and natural in plumbum. They work a lot like BG, for example:

>>> git['rev-list', 'HEAD..origin'] & TF
True
>>> git['rev-list', 'HEAD..origin'] & TF(1)
False
>>> git['rev-list', 'HEAD..origin'] & RETCODE
0

They support foreground execution with FG=True in the call, and TF can take retcode just like FG. Note that the bash syntax for using true/false return codes is &&, so this is a little like it, like BG.

I've added the two new objects, a test, documentation, and docstrings. Also fixed one minor typo in the docstring for FG.

PS: Should I add to the "what's new" documentation, too? I'm assuming you do that, but I'm happy to help if you need me to. Also, let me know if you have recommendations about names, etc, I'm happy to change them and resubmit if you have better ideas.) Thanks for such a brilliant library! I'll send a link to my blog post tutorial when I'm done with it if you want to see it. It should have a plumbum vs. bash example.

[tomerfiliba]

adding a what's new would be great, thanks

[tomerfiliba]

btw, i'm looking for a maintainer to make more regular releases, would you be interested?

[henryiii]

Sure, I'd be happy to help, just let me know what you want me to do. I'll see if I can update the what's new docs in the next couple of days.

[henryiii]

My blog post is here.

[tomerfiliba]

nice post! btw, i made you a collaborator of the project (you should have push access). it would be great if you could update the docs (where applicable) and let me know when everything's right so i'd make a release.