properties: use proper Sphinx deprecations docs
pypo: use depr. decorator, add depr. reason

Add the reason for the deprecation and for keeping the function around.
Taken from the original commit message.
styleguide: documenting deprecation of features