[Python-Dev] Convention on functions that shadow existing stdlib functions

[Antoine Pitrou]

On Wed, 27 Jul 2011 16:14:40 +0300
Eli Bendersky <eliben at gmail.com> wrote:
> 
> Will it take long for newbie code to appear with the test.support version?
> Not to mention that grepping code that imports the "unlink" function
> directly doesn't reveal which one is being used.
> 
> I think this is troublesome. I think at least two separate actions are
> required here:
> 
> 1. In the documentation of test.support mention explicitly that it's code
> for CPython's internal use only, and these APIs aren't guaranteed to be
> stable.

There is a top-level note at
http://docs.python.org/dev/library/test.html, but it won't be visible
by people who arrive at an anchor point.

I think officially documenting test.support is a mistake. There is no
guarantee that APIs are stable or will even continue to exist.
Docstrings are sufficient for own our purposes.

> 2. Some functions like unlink and rmtree are obviously redundant, and shadow
> frequently used Python stdlib functions, so I would either kill them
> completely or at least rename them appropriately.

They are not redundant, since they provide slightly different semantics
(for example, they silence errors that happen when the path doesn't
exist).

Regards

Antoine.