The PEP says:
“Given a set of arguments, the return value, side effects, and
raised exceptions of a function. This does not preclude changes from
reasonable bug fixes.”
That reads like a suggestion that any exception that might be raised
should always be considered a part of the public API. I don’t think we
want that. Traditionally, Python functions don’t document the full set
of exceptions that could possibly be raised, because that would be “all
of them”.
Can the PEP clarify the following?
-
documented exceptions MUST be treated as part of the public API,
and therefore subject to backwards compatibility requirements;
-
undocumented exceptions which are commonly used in “EAFP” style
code SHOULD be so treated;
-
other undocumented exceptions MAY be so treated;
-
but “incidental” exceptions that merely happen to occur due to
bugs or invalid use SHOULD NOT be so treated.
Where capitalised terms MUST, SHOULD, MAY and SHOULD NOT are to be
interpreted as in RFC 2119.
http://ietf.org/rfc/rfc2119.txt
The PEP says:
“Others are explicitly not part of the public API. They can change or
be removed at any time in any way. These include:”
I think it will be useful to avoid future arguments if the PEP is more
explicit about cases that are not part of the public API:
-
anything documented as private, even if it lacks a leading underscore;
(that includes docstrings, but not mere source code comments)
-
any imported module, unless explicit documented as public;
-
in the event of a conflict, where an entity is documented as both
private and public, public takes priority.
To clarify, suppose I have a function without a leading underscore, that
would default to public.
If I merely add a comment # Private function
to the source code, where
users cannot be expected to see it, that’s not sufficient to break the
backwards compatibility requirement.
But if I stick that comment in the docstring of the function or its
module, or document a restriction that anything not otherwise documented
as public should be treated as private, that takes priority.
A module might document that only functions that are listed in __all__
are public and that everything else is an implementation detail that
cannot be relied on. That should be honoured without forcing the module
to add leading underscores.
The PEP says:
“adding an stdlib module with the same name as a third party package is
not acceptable.”
Others have mentioned namesquatters and abandoned packages, but we
should also be explicit that we only care about public third-party
packages. Even if only for the practical reason that it is impossible
for us to do due diligence that module names aren’t already being used
in private.
If we want to add a new std lib module “widgetlib”, the existence of
someone’s private “widgetlib” should not block us from using that name.
(Although, in practice, if someone like Google were to ask nicely
“please don’t use that name, because we’re already using it internally”
we’d probably comply. But that’s the privilege of size, power and
money.)