Modify XML parsing library descriptions to forewarn of content loss hazard

BPO	43561
Nosy	@ridgerat

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['3.7', '3.8', '3.9', 'docs'] title = 'Modify XML parsing library descriptions to forewarn of content loss hazard' updated_at = user = 'https://github.com/ridgerat' ``` bugs.python.org fields: ```python activity = actor = 'ridgerat1611' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'ridgerat1611' dependencies = [] files = [] hgrepos = [] issue_num = 43561 keywords = [] message_count = 1.0 messages = ['389111'] nosy_count = 2.0 nosy_names = ['docs@python', 'ridgerat1611'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = None url = 'https://bugs.python.org/issue43561' versions = ['Python 3.7', 'Python 3.8', 'Python 3.9'] ```

With reference to improvement bpo-43560 :

If those improvements remain unimplemented, or are demoted to "don't fix", users are left in the tricky situation where XML parsing applications can fail, apparently "losing content" in a rare and unpredictable manner. It would be useful to patch the documentation to give users fair warning of this hazard.

For example: the "xml.sax.handler" page in the Python 3.9.2 Documentation for the Python Standard Library (and many prior versions) currently states:

The modified documentation would read something like the following:

----------- ContentHandler.characters(content) -- The Parser will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks... To avoid a situation in which one small content fragment unexpectedly overwrites another one, it is essential for the characters() method to collect content by appending, rather than by assignment. -----------

To give a concrete example, suppose that a Python programming site recommends the following coding to preserve a small text chunk bracketed by "\<p>" tags:

   # Note the name attribute of the current tag group
   def element_handler(self, tagname, attrs) :
       self.CurrentTag = tagname      

   # Record the content from each "p" tag when encountered
   def characters(self, content):
       if self.CurrentTag == "p" :
           self.name = content

Even though that coding could be expected to work most of the time, it is exposed to the hazard that an unanticipated sequence of calls to the characters() function would overwrite data.

Instead, the coding should look something like this.

   # Note the name attribute of the current tag group
   def element_handler(self, tagname, attrs) :
       self.CurrentTag = tagname 
       self.name = ""     

   # Accumulate the content from each "p" tag when encountered
   def characters(self, content):
       if self.CurrentTag == "p":
           self.name.append(content)

python / cpython

Modify XML parsing library descriptions to forewarn of content loss hazard #87727