[Python-Dev] Breaking undocumented API (original) (raw)

Ben Finney ben+python at benfinney.id.au
Tue Nov 9 01:32:05 CET 2010

Bobby Impollonia <bobbyi at gmail.com> writes:

On Mon, Nov 8, 2010 at 2:07 PM, Raymond Hettinger <raymond.hettinger at gmail.com> wrote: > To start with, it doesn't hurt for a maintainer to add an all > entry and to only document the parts of the API we think need to be > exposed.  That way, we can at least declare the parts that are > intended to be public on a go-forward basis.

This does hurt because anyone who was relying on "import *" to get a name which is now omitted from all is going to upgrade and find their program failing with NameErrors. This is a backwards compatible change and shouldn't happen without a deprecation warning first.

It also introduces a (perhaps small, but clearly non-zero) maintenance burden: the name of an object must be added, changed, and removed not only where it is defined, but also in the ‘__all__’ entry.

This burden is avoided when using the spelling of the name itself as the indicator for exposure in the API.

-- \ “In any great organization it is far, far safer to be wrong | `\ with the majority than to be right alone.” —John Kenneth | o_) Galbraith, 1989-07-28 | Ben Finney

More information about the Python-Dev mailing list