Doc suggestion for Elementtree (for 2.5? a bit late, I know...)
One little addition to the elementtree docs. In the overview section, adding a paragraph explaining best practice for importing the module might be useful. Some suggested text, for the "overview" section: """ The ElementTree module comes in two forms - a pure-python version (xml.etree.ElementTree) and a C-coded implementation (xml.etree.cElementTree) which is faster. To import the faster code if possible, but fall back to the Python implementation, you can use try: from xml.etree import cElementTree as ET except ImportError: from xml.etree import ElementTree as ET ElementTree is also available as an external module for older Python versions. For portability to these versions, this pattern can be extended to try: from xml.etree import cElementTree as ET except ImportError: try: from xml.etree import ElementTree as ET except ImportError: try: import cElementTree as ET except ImportError: import ElementTree as ET """ I'd put a patch on SF, but guess what? It's down again :-( Paul. PS This actually begs the question - are there platforms where xml.etree.cElementTree is not available? If not, is there a need for both versions? If there are, the wording above should probably be modified to reflect this.
Paul Moore wrote:
One little addition to the elementtree docs. In the overview section, adding a paragraph explaining best practice for importing the module might be useful.
good idea.
PS This actually begs the question - are there platforms where xml.etree.cElementTree is not available?
not really; I usually recommend checking for xml.etree.cElementTree cElementTree elementtree.ElementTree in that order, if you just want to get the "best" implementation. (there are some subtle differences between the C implementations and the Python implementations, so people who do non-standard stuff may want to use xml.etree.ElementTree, but I don't think that has to be mentioned in the overview) </F>
Paul Moore wrote:
The ElementTree module comes in two forms - a pure-python version (xml.etree.ElementTree) and a C-coded implementation (xml.etree.cElementTree) which is faster.
If this is to be in the stdlib, is there any chance of tidying up the convoluted, uninituitive and non-pep8-compliant module naming structure? -- Greg
Greg Ewing wrote:
Paul Moore wrote:
The ElementTree module comes in two forms - a pure-python version (xml.etree.ElementTree) and a C-coded implementation (xml.etree.cElementTree) which is faster.
If this is to be in the stdlib, is there any chance of tidying up the convoluted, uninituitive and non-pep8-compliant module naming structure?
I'm guessing the answer is "no" since the objection was only raised when the code had been incorporated into a release candidate. It was probably "no" from the beginning given that there was already substantial usage of the code before it was adopted for the stdlib. Standards, apparently, are for *other* people :-) It would be good if 3.0 was *much* more hard-nosed about naming conventions. How can we expect the community as a whole to take them seriously if we don't take them seriously ourselves? regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC/Ltd http://www.holdenweb.com Skype: holdenweb http://holdenweb.blogspot.com Recent Ramblings http://del.icio.us/steve.holden
Steve Holden wrote:
Standards, apparently, are for *other* people :-)
ET was written years before the "certain modules should use camelcase" stuff was removed from PEP 8. as a refresher for those of you who have trouble remembering how things were back in early 2004, here's GvR's original style guide: http://www.python.org/doc/essays/styleguide/ Modules that export a single class (or a number of closely related classes, plus some additional support) are often named in MixedCase, with the module name being the same as the class name (e.g. the standard StringIO module). Modules that export a bunch of functions are usually named in all lowercase. /.../ There is an emerging convention that when an extension module written in C or C++ has an accompanying Python module that provides a higher level (e.g. more object oriented) interface, the Python module's name CapWords, while the C/C++ module is named in all lowercase and has a leading underscore (e.g. Tkinter/_tkinter). </F>
Fredrik Lundh wrote:
ET was written years before the "certain modules should use camelcase" stuff was removed from PEP 8.
Maybe so, but I was hoping that additions to the stdlib in this day and age might be adapted to follow modern conventions instead of just being plonked in as-is. -- Greg
Greg Ewing wrote:
Fredrik Lundh wrote:
ET was written years before the "certain modules should use camelcase" stuff was removed from PEP 8.
Maybe so, but I was hoping that additions to the stdlib in this day and age might be adapted to follow modern conventions instead of just being plonked in as-is.
Unfortunately this doesn't work if you want to encourage existing users to migrate to the built-in version. However, let's hope that Python 3000 will have enforcers patrolling the perimeter of the library with shotguns. It does make us look rather dumb when we set rules that our own code doesn't obey - or change the rules after we've already encouraged contributions under other terms. regards Steve -- Steve Holden +44 150 684 7255 +1 800 494 3119 Holden Web LLC/Ltd http://www.holdenweb.com Skype: holdenweb http://holdenweb.blogspot.com Recent Ramblings http://del.icio.us/steve.holden
On Tue, Aug 29, 2006, Greg Ewing wrote:
Fredrik Lundh wrote:
ET was written years before the "certain modules should use camelcase" stuff was removed from PEP 8.
Maybe so, but I was hoping that additions to the stdlib in this day and age might be adapted to follow modern conventions instead of just being plonked in as-is.
You have a point, but I think that for external libraries with a large following the best we can do is set things up so that it's both PEP8 compliant *and* has aliases to the existing setup. From my POV, it's critical to encourage people to switch to the stdlib version if possible (but often writing code that works with the external library is the only way to support multiple Python versions). That parenthetical bit is the real killer, and I don't think even Py3K can completely overcome it if PEP8 continues to evolve. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it." --Brian W. Kernighan
participants (5)
-
Aahz -
Fredrik Lundh -
Greg Ewing -
Paul Moore -
Steve Holden