<div dir="ltr">I was recently tripped up by a bug in the documentation for the xml.etree.ElementTree write function that I found here:<div><a href="https://docs.python.org/2.7/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree.write">https://docs.python.org/2.7/library/xml.etree.elementtree.html#xml.etree.ElementTree.ElementTree.write</a><br></div><div><br></div><div>The documentation says</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify"> </span><em style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify">xml_declaration</em><span style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify"> controls if an XML declaration should be added to the file. Use False for never, True for always, None for only if not US-ASCII or UTF-8 (default is None). </span><br></blockquote><div><br></div><div>However, setting <i>xml_declaration </i>to True does nothing unless the <i>encoding </i>parameter is also set.</div><div><br></div><div>Here is the relevant code, from Python27\Lib\xml\etree\ElementTree.py:</div><div><div><font face="monospace, monospace">def write(self, file_or_filename,</font></div><div><font face="monospace, monospace">              # keyword arguments</font></div><div><font face="monospace, monospace">              encoding=None,</font></div><div><font face="monospace, monospace">              xml_declaration=None,</font></div><div><font face="monospace, monospace">              default_namespace=None,</font></div><div><font face="monospace, monospace">              method=None):</font></div><div><font face="monospace, monospace">        # assert self._root is not None</font></div><div><font face="monospace, monospace">        if not method:</font></div><div><font face="monospace, monospace">            method = "xml"</font></div><div><font face="monospace, monospace">        elif method not in _serialize:</font></div><div><font face="monospace, monospace">            # FIXME: raise an ImportError for c14n if ElementC14N is missing?</font></div><div><font face="monospace, monospace">            raise ValueError("unknown method %r" % method)</font></div><div><font face="monospace, monospace">        if hasattr(file_or_filename, "write"):</font></div><div><font face="monospace, monospace">            file = file_or_filename</font></div><div><font face="monospace, monospace">        else:</font></div><div><font face="monospace, monospace">            file = open(file_or_filename, "wb")</font></div><div><font face="monospace, monospace">        write = file.write</font></div><div><font face="monospace, monospace">        <b>if not encoding:</b></font></div><div><font face="monospace, monospace">            if method == "c14n":</font></div><div><font face="monospace, monospace">                encoding = "utf-8"</font></div><div><font face="monospace, monospace">            else:</font></div><div><font face="monospace, monospace">                encoding = "us-ascii"</font></div><div><font face="monospace, monospace">        <b>elif xml_declaration</b> or (<b>xml_declaration </b>is None and</font></div><div><font face="monospace, monospace">                                 encoding not in ("utf-8", "us-ascii")):</font></div><div><font face="monospace, monospace">            if method == "xml":</font></div><div><font face="monospace, monospace">                write("<?xml version='1.0' encoding='%s'?>\n" % encoding)</font></div></div><div><br></div><div>The problem is, write does not even look at the value of the <i>xml_declaration </i>unless the <i>encoding </i>parameter was specified. Even then, it won't write the xml version string unless <i>method </i>is set to xml.</div><div><br></div><div>So, to be accurate, the documentation should say something like, </div><div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div><span style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify"> write adds an xml declaration when </span><em style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify">encoding </em><span style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify">is specified and <i>method </i>equals xml and either</span></div><div><em style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify">1) xml_declaration</em><span style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify"> is True, or</span></div><div><span style="color:rgb(0,0,0);font-family:sans-serif;line-height:20.8px;text-align:justify">2) <i>xml_declaration </i>is None and <i>encoding </i>is neither utf-8 or us-ascii</span></div></blockquote></div><div><br></div><div>Frankly, this code is overly complicated for what it is trying to do. I am glad to see it was re-written for Python 3. </div><div><br></div><div>Cheers,</div><div><br></div><div>-- bob felice</div><div><br></div><div><br></div><div> </div></div>