Is it a good idea to use undocumented public code from the Python standard library?

Question

For instance, in multiprocessing.managers there is a function called MakeProxyType. This function isn't in the multiprocessing documentation at all, but its name doesn't begin with an underscore either. Disregarding the subject of whether or not it's actually useful to use MakeProxyType, would it be ok to use this function in my code?

Answer 1

You should clarify with the authors whether the omission of MakeProxyType from the documentation is deliberate or accidental. If it's deliberate, then it can disappear from the API without notice and would be dangerous to use.

Answer 2

It's going to be safe if, and only if, you can check that the implementation does not depend on other, "private" parts of the package (so that you'll just be able to copy and paste it into your own module if and when it should get removed from the standard library), or else you see how to reimplement the same interface in such a fashion (again, as a "plan B" safety strategy against such possible future removals).

Answer 3

If you really need to use the function in your code then you could do this:

try:
  from multiprocessing.managers import MakeProxyType
except ImportError:
   def MakeProxyType(...):
     <copy the code from source>

that way if the function disappears from new versions it will fall back to using the local version, while still benefitting from any bug fixes etc that may go into a newer version.

Of course this could still break if the function changes in an incompatible way, or makes use of other private features of the module.

Answer 4

Usually names which don't start with an underscore are considered part of the public API and we try to maintain compatibility accross versions. You might want to wait for Jesse Noller's answer, though, he's the multiprocessing maintainer and I hear he has an account here ;)