First, thanks Raymond for your worth useful comment.

* Concerning the usage of the warning module what do you suggest to use then?  To use "print"? 

* Concerning "hook or flag" and the 3 new params in my PR, I think developers would appreciate to give a customized message to their users to inform that something will be removed for X reasons in the X release. The "pending" notion could be removed to keep the API lightweight, but with a well documented feature I don't seen terrible thing to understand here, maybe we need to put more effort on documentation and example (related to my changes).

* Concerning the fact to move deprecation management outside the declaration of the argument, I think it could be misleading to deprecate something in another place in the code, in other words it could introduce some more difficulties to understand the code. If the deprecation is declared in the argument declaration then all the info are centralized in one place and the parser know what to do in this situation.

Thoughts?