On 16/11/2010 15:16, Alexander Belopolsky wrote:
What this thread has shown is that there is no consensus on what
public names are and what rules should be followed when changing names
that can be imported from a module. I have opened an issue at
http://bugs.python.org/issue10434 to address this. My vote is to
adopt the definition spelled out in the language reference, copy it to
the library manual and add some discussion of the deprecation
policies.
Whilst the definition in the reference manual is fine it only covers
module level public APIs (which I realise is your particular concern) it
doesn't cover whether a module in a package is public and doesn't cover
class members. The rules for these follow as a natural extension, but if
we are going to bother codifying the rules (which I think is good given
the confusion) then it is worth covering these cases.
I posted a suggested wording in an earlier message:
http://mail.python.org/pipermail/python-dev/2010-November/105476.html
We could also note that existing modules that don't follow these rules
will generally follow the deprecation rules for "accidentally public"
names, but that this will be decided on a case-by-case basis and that
names *obviously* never intended to be public may be changed if it is
believed that they aren't (or really shouldn't be) in use.
All the best,
Michael Foord
I also have a similar question about C API. Here, in absence of
__all__, the answer should be clear: all symbols in public header
files should start with either _Py_ or Py_ and those that start with
Py_ are public. The question is what should be done with names that
start with Py_, but are not documented? Can we add an underscore to
those names? If so, should a (deprecated) alias be made available?
Should they be documented as deprecated?
I think these questions can only be answered on a case by case bases
which choices being:
1. Document.
2. Document as deprecated.
3. Document as deprecated, add underscore prefix and retain a deprecated alias.
4. Add an underscore prefix.
The specific set of names that I would like to consider is the
following from unicode.h. I am marking with (*) the names that I
think should be documented and with (D) those that should be
deprecated:
PyUnicode_GetMax
PyUnicode_Resize (*)
PyUnicode_InternImmortal
PyUnicode_FromOrdinal (*)
PyUnicode_GetDefaultEncoding (D)
PyUnicode_AsDecodedObject
PyUnicode_AsDecodedUnicode
PyUnicode_AsEncodedObject
PyUnicode_AsEncodedUnicode
PyUnicode_BuildEncodingMap
PyUnicode_EncodeDecimal (*)
PyUnicode_Append (*)
PyUnicode_AppendAndDel (*)
PyUnicode_Partition (*)
PyUnicode_RPartition (*)
PyUnicode_RSplit (*)
PyUnicode_IsIdentifier (*)
Py_UNICODE_strlen
Py_UNICODE_strcpy
Py_UNICODE_strcat
Py_UNICODE_strncpy
Py_UNICODE_strcmp
Py_UNICODE_strncmp
Py_UNICODE_strchr
Py_UNICODE_strrchr
On Sat, Nov 13, 2010 at 7:12 AM, Giampaolo Rodolà<g.rod...@gmail.com> wrote:
+1 on everything.
2010/11/11 Alexander Belopolsky<alexander.belopol...@gmail.com>:
2010/11/11 Michael Foord<fuzzy...@voidspace.org.uk>:
..
You mean runtime automation, e.g. creating __all__ on the fly omitting
underscored names?
Writing code to generate a __all__ that duplicates the default behaviour
seems redundant to me.
FWIW, I like having __all__ at the top of the module. It feels like a
table of contents at the start of a chapter. In some cases it may
also serve as an optimization when len(__all__) is much smaller than
len(__dict__). I also don't like _ prefix to become an exclusive
means to express privateness.
I think the current definition of "public names" is a good one and
just needs to be made more visible in the docs. If the module defines
__all__, that should be the ultimate answer to what is public in that
module. (Users should learn to use help(module) instead of
dir(module) for API discovery.) If __all__ is not defined in the
module, I think it is good to introduce it after a careful review of
what it should contain. And __all__ should never contain names that
start with _.
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/g.rodola%40gmail.com
--
http://www.voidspace.org.uk/
READ CAREFULLY. By accepting and reading this email you agree,
on behalf of your employer, to release me from all obligations
and waivers arising from any and all NON-NEGOTIATED agreements,
licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
confidentiality, non-disclosure, non-compete and acceptable use
policies (”BOGUS AGREEMENTS”) that I have entered into with your
employer, its partners, licensors, agents and assigns, in
perpetuity, without prejudice to my ongoing rights and privileges.
You further represent that you have the authority to release me
from any BOGUS AGREEMENTS on behalf of your employer.
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
