Skip to content

Remove "lightweight" from minidom description #55588

Closed
Closed
Remove "lightweight" from minidom description#55588
Assignees
ezio-melotti
Labels
docsDocumentation in the Doc dirtopic-XMLtype-featureA feature request or enhancement

Description

@scoder
scoder
opened on Mar 2, 2011
BPO 11379
Nosy @loewis, @freddrake, @rhettinger, @orsenthil, @pitrou, @scoder, @ezio-melotti, @merwok, @florentx
Files
  • issue_11379.1.patch
  • minidom-desc.diff
  • minidom-desc-2.diff
    		•

    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:

    assignee = 'https://github.com/ezio-melotti'
closed_at = <Date 2013-01-22.20:51:53.487>
created_at = <Date 2011-03-02.19:25:07.631>
labels = ['expert-XML', 'type-feature', 'docs']
title = 'Remove "lightweight" from minidom description'
updated_at = <Date 2013-12-22.00:57:59.751>
user = 'https://github.com/scoder'

    bugs.python.org fields:

    activity = <Date 2013-12-22.00:57:59.751>
actor = 'python-dev'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2013-01-22.20:51:53.487>
closer = 'ezio.melotti'
components = ['Documentation', 'XML']
creation = <Date 2011-03-02.19:25:07.631>
creator = 'scoder'
dependencies = []
files = ['24686', '24707', '24732']
hgrepos = []
issue_num = 11379
keywords = ['patch']
message_count = 62.0
messages = ['129914', '129918', '129934', '129936', '129937', '129939', '129944', '129951', '148512', '148558', '148562', '148565', '148566', '148570', '148572', '148578', '148579', '148584', '148585', '148594', '148598', '149604', '149611', '149634', '152836', '152862', '152866', '152924', '154646', '154660', '154673', '154676', '154677', '154735', '154736', '154737', '154756', '154759', '154760', '154766', '154767', '154772', '154773', '154774', '154924', '154952', '154954', '155074', '155077', '155078', '155081', '156021', '156027', '159562', '159569', '177972', '180368', '180374', '180409', '180434', '180435', '206801']
nosy_count = 12.0
nosy_names = ['loewis', 'fdrake', 'rhettinger', 'orsenthil', 'pitrou', 'scoder', 'ezio.melotti', 'eric.araujo', 'flox', 'docs@python', 'tshepang', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue11379'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3', 'Python 3.4']

    Activity

    1. scoder commented on Mar 2, 2011

      @scoder
      scoder
      on Mar 2, 2011
      ContributorAuthor

      http://docs.python.org/library/xml.dom.minidom.html

      presents MiniDOM as a "Lightweight DOM implementation". The word "lightweight" is easily misunderstood as meaning "efficient" or "memory friendly". MiniDOM is well known to be neither of the two.

      The first paragraph then continues:

      """
      xml.dom.minidom is a light-weight implementation of the Document Object Model interface. It is intended to be simpler than the full DOM and also significantly smaller.
      """

      Again, "smaller" can be misread as "low memory footprint", whereas it is actually supposed to refer to an incomplete DOM API implementation. And "simpler" is also clearly exaggerated when compared to the alternative ElementTree package.

      I would like to see this changed and combined with a clear and visible comment that MiniDOM has very high resource profile, e.g.

      """
      19.7. xml.dom.minidom — Pure Python DOM implementation

      xml.dom.minidom is a pure Python implementation of the Document Object Model interface, as known from other programming languages. It is intended to provide a smaller API than the full DOM.

      Note, however, that MiniDOM has a very large memory footprint compared to other Python XML libraries. If you need a fast and memory friendly XML tree implementation with a vastly simpler API, use the xml.etree package instead.
      """

    2. scoder
      assigned
      docspython
      on Mar 2, 2011
    3. scoder
      added
      docsDocumentation in the Doc dir
      on Mar 2, 2011

    4. loewis commented on Mar 2, 2011

      @loewis
      loewismannequin
      on Mar 2, 2011
      Mannequin

      -1. The description is factually correct - minidom *does* have a lower footprint than other Python DOM implementations (such as 4DOM).

    5. scoder commented on Mar 3, 2011

      @scoder
      scoder
      on Mar 3, 2011
      ContributorAuthor

      Well, I'm not aware of many people who use 4DOM these days, and if that's what it's meant to refer to, maybe that should be made more obvious, because it currently is not at all. Even cDomlette uses only half of the memory according to

      http://effbot.org/zone/celementtree.htm

      When you say that the description is "factually correct", that does by no means imply that the average reader will understand how it's meant. My point is that almost everyone who reads this will draw the wrong conclusions.

      Also, when you say "lower footprint", that does not yet make it "light weight" in any way. It still uses something like ten times as much memory as cElementTree or lxml in Python 2 (and likely much more than even that in Python 3), and still something like 4-5 times as much as plain Python ElementTree. That's a huge difference.

      What about this phrasing then:

      """
      MiniDOM has a smaller memory footprint than some of the other DOM compliant implementations for Python (such as 4DOM), but uses about 10x more memory than the faster and simpler xml.etree.cElementTree module.
      """

    6. loewis commented on Mar 3, 2011

      @loewis
      loewismannequin
      on Mar 3, 2011
      Mannequin

      What about this phrasing then:

      """ MiniDOM has a smaller memory footprint than some of the other DOM
      compliant implementations for Python (such as 4DOM), but uses about
      10x more memory than the faster and simpler xml.etree.cElementTree
      module. """

      But that's not a DOM implementation - so it would be comparing apples
      and oranges.

    7. scoder commented on Mar 3, 2011

      @scoder
      scoder
      on Mar 3, 2011
      ContributorAuthor

      It's the tree based API most python users are parsing XML with, though. So I do not agree that it's comparing apples and oranges, not at all. It's comparing tree based XML libraries, only one of which is worth being called "light weight", and that's not the one that is currently carrying that name.

      I think it's worth telling new users what they are committing to when they write code that uses MiniDOM. The documentation should allow them to understand that.

    8. loewis commented on Mar 3, 2011

      @loewis
      loewismannequin
      on Mar 3, 2011
      Mannequin

      It's the tree based API most python users are parsing XML with,
      though. So I do not agree that it's comparing apples and oranges, not
      at all. It's comparing tree based XML libraries, only one of which is
      worth being called "light weight", and that's not the one that is
      currently carrying that name.

      If that is a real concern, I'd rather reduce the memory footprint of
      minidom than put actual performance figures into the documentation
      that will likely outdate over time.

      Notice that the documentation doesn't claim that it is a lightweight
      XML library, only that it's a ligthweight DOM implementation. SAX is,
      of course, even lighter-weight.

    9. scoder commented on Mar 3, 2011

      @scoder
      scoder
      on Mar 3, 2011
      ContributorAuthor

      If that is a real concern, I'd rather reduce the memory footprint of
      minidom than put actual performance figures into the documentation
      that will likely outdate over time.

      Personally, I do not think it's worth putting much work into MiniDOM. I'd rather deprecate it to prevent new code from being written for it, but that's just my personal opinion, and this is the wrong place to discuss that. Given the current performance characteristics, I wouldn't be surprised if there was quite some room for improvements left in the xml.dom package.

      If you dislike the "10x", feel free to use "several times". I doubt that MiniDOM will ever get so much closer to cET and lxml to prove that phrasing wrong.

      Notice that the documentation doesn't claim that it is a lightweight
      XML library, only that it's a ligthweight DOM implementation.

      I imagine that you are as aware as I am that this nuance is easy to miss, especially for a new user. From my experience, it is very common for users, especially those with a Java-ish background, to confuse the terms "DOM" and "XML tree API/library". Hence my push to change the documentation.

      SAX is, of course, even lighter-weight.

      Not so much more light weight than cET's iterparse(), but that's getting OT here.

      Stefan

    10. pitrou commented on Mar 3, 2011

      @pitrou
      pitrou
      on Mar 3, 2011
      Member

      Agreed with Stefan's concern.

    11. scoder commented on Nov 28, 2011

      @scoder
      scoder
      on Nov 28, 2011
      ContributorAuthor

      Ok, so, what do we make of this? I proposed improvements to the wording in the documentation, which make it much clearer for users what they are buying into when they start using minidom. I still think that "factually correct" but clearly misleading documentation is not helpful and that it needs fixing. Here is an updated phrasing that I hope we can settle on:

      """
      :mod:`xml.dom.minidom` --- Pure Python DOM implementation

      [...]

      :mod:`xml.dom.minidom` is a pure Python implementation of the Document Object Model interface, as known from other programming languages. It is intended to provide a smaller and simpler API than the full W3C DOM.

      Note that MiniDOM has a several times larger memory footprint than :mod:`xml.etree.ElementTree`, the light-weight Python XML library in the standard library. If you do not need a (mostly) compliant W3C DOM implementation, but a fast and memory friendly XML tree implementation with an easy to learn API, use that instead.
      """

    12. merwok commented on Nov 29, 2011

      @merwok
      merwok
      on Nov 29, 2011
      Member

      Is memory footprint something important enough to put in the doc? Ease of use is IMO more important, but then it becomes subjective..

    13. scoder commented on Nov 29, 2011

      @scoder
      scoder
      on Nov 29, 2011
      ContributorAuthor

      I find a factor of an order of magnitude worth mentioning, because it prevents certain kinds of usages.

    14. ezio-melotti commented on Nov 29, 2011

      @ezio-melotti
      ezio-melotti
      on Nov 29, 2011
      Member

      Usually we don't talk about performance in the doc, and in my personal experience I didn't notice any major difference between the different implementations (but than again I haven't used them much).
      Talking about the other implementations and their advantages/disadvantages is fine, but things like "MiniDOM has a several times larger memory footprint" seems like FUD to me (see also http://docs.python.org/dev/documenting/style.html#affirmative-tone).

    15. freddrake commented on Nov 29, 2011

      @freddrake
      freddrake
      on Nov 29, 2011
      Member

      Removing "Lightweight" and changing the first paragraph to (something like)

      :mod:`xml.dom.minidom` is an implementation of the Document Object Model
      interface. The API is slightly simpler than the full W3C DOM, but the
      implementation has a significantly higher memory footprint than
      :mod:`xml.dom.etree`.

      would be entirely reasonable.

      (I don't think it's wrong to discuss relative memory footprints in comparison to other modules in the standard library.)

    16. 42 remaining items

    17. ezio-melotti commented on Apr 29, 2012

      @ezio-melotti
      ezio-melotti
      on Apr 29, 2012
      Member

      Any news on this?

    18. merwok commented on Apr 29, 2012

      @merwok
      merwok
      on Apr 29, 2012
      Member

      I’ve been unresponsive of late, sorry, but I’m still here. Will see if I have time tomorrow.

    19. scoder commented on Dec 23, 2012

      @scoder
      scoder
      on Dec 23, 2012
      ContributorAuthor

      Any news on this?

    20. scoder commented on Jan 22, 2013

      @scoder
      scoder
      on Jan 22, 2013
      ContributorAuthor

      I'm not sure if it's a good idea to keep bikeshedding about this for another two years. Personally, I would prefer having someone with commit rights fix this and be done with it.

      Eric's last patch looks ok and parts of it went in already, so it's mostly just the heading that remains to be fixed.

    21. pitrou commented on Jan 22, 2013

      @pitrou
      pitrou
      on Jan 22, 2013
      Member

      Someone should go ahead and apply this. Éric, perhaps?

    22. merwok commented on Jan 22, 2013

      @merwok
      merwok
      on Jan 22, 2013
      Member

      Sure, feel free to commit this.

    23. python-dev commented on Jan 22, 2013

      @python-dev
      python-devmannequin
      on Jan 22, 2013
      Mannequin

      New changeset c2ae1ed03853 by Ezio Melotti in branch '2.7':
      bpo-11379: rephrase minidom documentation to use the term "minimal" instead of "lightweight". Patch by Éric Araujo.
      http://hg.python.org/cpython/rev/c2ae1ed03853

      New changeset b9c0e050c935 by Ezio Melotti in branch '3.2':
      bpo-11379: rephrase minidom documentation to use the term "minimal" instead of "lightweight". Patch by Éric Araujo.
      http://hg.python.org/cpython/rev/b9c0e050c935

      New changeset 8ff512910338 by Ezio Melotti in branch '3.3':
      bpo-11379: merge with 3.2.
      http://hg.python.org/cpython/rev/8ff512910338

      New changeset 9a0cd5363c2a by Ezio Melotti in branch 'default':
      bpo-11379: merge with 3.3.
      http://hg.python.org/cpython/rev/9a0cd5363c2a

    24. ezio-melotti commented on Jan 22, 2013

      @ezio-melotti
      ezio-melotti
      on Jan 22, 2013
      Member

      Fixed, thanks for the patch!

    25. ezio-melotti
      closed this as completedon Jan 22, 2013
    26. ezio-melotti
      assigned
      ezio-melotti
      and unassigned
      docspython
      on Jan 22, 2013
    27. ezio-melotti
      added
      type-featureA feature request or enhancement
      and removed
      performancePerformance or resource usage
      on Jan 22, 2013

    28. python-dev commented on Dec 22, 2013

      @python-dev
      python-devmannequin
      on Dec 22, 2013
      Mannequin

      New changeset 39ea24aaf0e7 by Antoine Pitrou in branch '2.7':
      s/lightweight/minimal/, as per issue bpo-11379.
      http://hg.python.org/cpython/rev/39ea24aaf0e7

      New changeset b63258b6eb4d by Antoine Pitrou in branch '3.3':
      s/lightweight/minimal/, as per issue bpo-11379.
      http://hg.python.org/cpython/rev/b63258b6eb4d

      New changeset d659e7761d59 by Antoine Pitrou in branch 'default':
      s/lightweight/minimal/, as per issue bpo-11379.
      http://hg.python.org/cpython/rev/d659e7761d59

    29. ezio-melotti
      transferred this issue fromon Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    Labels

    docsDocumentation in the Doc dirtopic-XMLtype-featureA feature request or enhancement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions