This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Provide some examples for usage of ElementTree methods/attributes
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Daniel.Ellis, Sarbjit.singh, docs@python, eli.bendersky, eric.araujo, ezio.melotti, python-dev, r.david.murray
Priority: normal Keywords: easy, patch

Created on 2012-08-08 06:34 by Sarbjit.singh, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
default_branch_etree_doc.patch Daniel.Ellis, 2012-08-08 20:26 review
default_branch_etree_doc_2.patch Daniel.Ellis, 2012-08-09 13:41 review
2.7_branch_etree_doc.patch Daniel.Ellis, 2012-08-13 16:00 review
default_branch_etree_doc_3.patch Daniel.Ellis, 2012-08-13 16:01 review
2.7_branch_etree_doc_2.patch Daniel.Ellis, 2012-08-14 13:12 review
2.7_branch_etree_doc_3.patch Daniel.Ellis, 2012-08-16 15:29 review
Messages (24)
msg167670 - (view) Author: Sarbjit singh (Sarbjit.singh) Date: 2012-08-08 06:34
Please provide some basic usage examples for ElementTree module documentation. While parsing an xml, most common scenarios will be reading elements from xml, modifying elements, removal of elements. Though there are few examples given for modification of xml element. 

But if you look from beginners learning point of view, its very hard to just get any idea from the example that is currently provided. There is lot of text there, but what would be more helpful is some small examples for each function so that user can quickly understand its usage there only.  I myself is learning Python, but in order to start using this module, i had to search lot of articles on internet on usage of this module. If we could have provided some basic use cases in Python doc itself, user would not have to rely on external sources for learning its usage.

Some Basic Scenarios:
1) Parsing an xml and finding some elements of xml
2) deletion of an element from an xml and writing back
3) Modification of an xml element
4) Usage of XPath queries (some basic usage)
msg167688 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-08 12:38
I have been working with ElementTree for the last few months and would love to help out with this.
msg167691 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-08-08 16:07
Daniel, I would suggest you to start with a basic example that gives an idea about how to use the module and its main functionalities.  If necessary you could add a section at the bottom with more examples.
You can also show how a method works with a short snippet (2-3 lines) just after the documentation of the method, but this doesn't mean that every method should have one.
If you have lot of examples you might consider doing a separate tutorial/howto.

As a reference see the examples in http://docs.python.org/py3k/library/html.parser.html and http://docs.python.org/py3k/library/unittest.html#basic-example.
msg167692 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-08 16:33
Thank you Ezio, I will use that as a reference.  What is the general
workflow for updating documentation across python versions?  Should I check
to see if the documentation for the module changes across python versions
and create patches for each version?  Or is it sufficient to create a patch
for one version?

On Wed, Aug 8, 2012 at 12:07 PM, Ezio Melotti <report@bugs.python.org>wrote:

>
> Ezio Melotti added the comment:
>
> Daniel, I would suggest you to start with a basic example that gives an
> idea about how to use the module and its main functionalities.  If
> necessary you could add a section at the bottom with more examples.
> You can also show how a method works with a short snippet (2-3 lines) just
> after the documentation of the method, but this doesn't mean that every
> method should have one.
> If you have lot of examples you might consider doing a separate
> tutorial/howto.
>
> As a reference see the examples in
> http://docs.python.org/py3k/library/html.parser.html and
> http://docs.python.org/py3k/library/unittest.html#basic-example.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <http://bugs.python.org/issue15586>
> _______________________________________
>
msg167693 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-08-08 16:36
Usually a patch against "default" (i.e. Python 3) is enough, if there are several differences with Python 2 you might want to provide one for 2.7 too.

See also the devguide at http://docs.python.org/devguide/ for more information about the workflow.
msg167700 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-08-08 17:51
Please note that the documentation of ET has been significantly improved in 3.3, with added examples, etc. You can start by backporting whatever is relevant to earlier versions (2.7/3.2) - do not add new documentation contents to 2.7/3.2 before the changes from 3.3 are backported, because we can't have divergent docs.
msg167710 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-08 20:26
I've made a couple more additions/changes to the documentation in the default branch, per Eli's recommendation, since there were already a lot of good examples added.  I'd like to also backport this to 2.7 but wanted to make sure these changes were good before moving forward.  I just saw Eli's message about doing the backporting before making further changes but had already been working on making these changes.  I can go ahead and work on the backport if you feel this patch is too much to do first, but I believe every example I added is backwards compatible.
msg167766 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-08-09 07:45
I provided some comments on your patch in the code-review tool. Thanks for the contribution, Daniel. It's fine to first apply these changes to 3.3 and then backport to 2.7 (I don't think 3.2 is necessary because most users use the online docs anyway).
msg167767 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-08-09 07:47
Sarbjit, if you look at the docs of 3.3, I think most of what you're asking for is there (especially once you count Daniel's commit). What else is missing in your opinion?
msg167770 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-08-09 08:11
Sarbjit: first of all, look at the up-to-date documentation for 3.3 (it's available online at http://docs.python.org/dev/

Then, on a checkout of the 3.3 code (default branch) you can apply Daniel's patch (it's in the "Files" section in this Issue) and look at the updated documentation.

MOST IMPORTANTLY: read http://docs.python.org/devguide/index.html thoroughly - it will answer most of your questions.
msg167785 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-09 13:41
Changes to documentation per Ezio and Eli's suggestions.
msg167786 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-08-09 14:20
My understanding is that we try to keep the documentation of all active branches (2.7, 3.2, and 3.3 currently) in sync except where there are new features/new deprecations in the development version.  So if the 2.7 docs are update, I think the 3.2 docs should be too.  There will be one more release of 3.2, and the Windows version will bundle the docs, so I think it is worthwhile to do.  But I'm not going to do it, so if no one volunteers to do it and apply the patch, that's fine :)
msg167787 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-09 14:43
At the moment, the documentation for 2.7 is behind the documentation for 3.3.  I will be working on backporting this next, but it will be a little more difficult than simply copying the existing documentation, since some key things in etree changed in the transition to 3.x.
msg168122 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-13 16:00
I've updated 2.7 with the examples and made changes where backward compatibility was an issue.
msg168123 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-13 16:01
Fixed typo I made in examples in default branch.
msg168172 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-14 04:21
New changeset fc66730dae4c by Eli Bendersky in branch 'default':
Issue #15586: add some examples to ElementTree documentation. Patch by Daniel Ellis.
http://hg.python.org/cpython/rev/fc66730dae4c
msg168173 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-08-14 04:30
I committed your patch to default (3.3) with some minor fixes. Please go over them as you will need to apply them to the 2.7 patch. I've reviewed the 2.7 patch as well - it's an initial review. Did you execute all the code samples on 2.7?
msg168198 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-14 13:12
Thank you for the review Eli.  I've made your changes and attached the updated patch.  I did run all of the code snippets that are being added on 2.7, and the only thing I found different was the changed print statement.  I don't believe I overlooked anything, but I may have made a mistake.
msg168255 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-08-15 02:01
I noticed a long-standing typo in the latest commit: the country is named Liechtenstein :)
msg168280 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-15 11:27
New changeset 8d90fde35cc6 by Eli Bendersky in branch 'default':
Issue #15586: typo fix. This commit is accompanied by an apology for all Liechtensteiners out there, and a thanks to Eric Araujo for noticing.
http://hg.python.org/cpython/rev/8d90fde35cc6
msg168281 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-08-15 11:38
Daniel, this looks good except that the section numbering is different from 3.3 where the object/function reference sections were nested under "Reference". Could you fix your patch to align the 2.7 doc to this structure?

P.S. Éric's comment also has to be fixed ;)
msg168383 - (view) Author: Daniel Ellis (Daniel.Ellis) Date: 2012-08-16 15:29
Made changes in structure in 2.7 branch to match 3.3 based on Eli's comments.  Updated input prompt in examples per Ezio's review (though the default branch will still need this update).
msg168491 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-18 02:41
New changeset 094423a65a4e by Eli Bendersky in branch '2.7':
Issue #15586: porting ET's new documentation bits to 2.7. Patch by Daniel Ellis
http://hg.python.org/cpython/rev/094423a65a4e
msg168492 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-18 02:43
New changeset 7012f6a74f66 by Eli Bendersky in branch 'default':
Issue #15586: fix prompts in some documentation examples
http://hg.python.org/cpython/rev/7012f6a74f66
History
Date User Action Args
2022-04-11 14:57:34adminsetgithub: 59791
2012-10-15 12:51:30eli.benderskysetstatus: open -> closed
resolution: fixed
stage: needs patch -> resolved
2012-08-18 02:43:23python-devsetmessages: + msg168492
2012-08-18 02:41:40python-devsetmessages: + msg168491
2012-08-16 15:29:36Daniel.Ellissetfiles: + 2.7_branch_etree_doc_3.patch

messages: + msg168383
2012-08-15 11:38:53eli.benderskysetmessages: + msg168281
2012-08-15 11:27:27python-devsetmessages: + msg168280
2012-08-15 02:01:04eric.araujosetnosy: + eric.araujo
messages: + msg168255
2012-08-14 13:12:32Daniel.Ellissetfiles: + 2.7_branch_etree_doc_2.patch

messages: + msg168198
2012-08-14 04:30:34eli.benderskysetmessages: + msg168173
2012-08-14 04:21:02python-devsetnosy: + python-dev
messages: + msg168172
2012-08-13 16:01:02Daniel.Ellissetfiles: + default_branch_etree_doc_3.patch

messages: + msg168123
2012-08-13 16:00:21Daniel.Ellissetfiles: + 2.7_branch_etree_doc.patch

messages: + msg168122
2012-08-09 14:44:00Daniel.Ellissetmessages: + msg167787
2012-08-09 14:21:00r.david.murraysetnosy: + r.david.murray
messages: + msg167786
2012-08-09 13:41:40Daniel.Ellissetfiles: + default_branch_etree_doc_2.patch

messages: + msg167785
2012-08-09 08:11:54eli.benderskysetmessages: + msg167770
2012-08-09 07:47:47eli.benderskysetmessages: + msg167767
2012-08-09 07:46:08eli.benderskysetversions: + Python 2.7
2012-08-09 07:45:49eli.benderskysetmessages: + msg167766
versions: - Python 2.7
2012-08-09 05:22:18eli.benderskysetversions: + Python 2.7, Python 3.3, Python 3.4
2012-08-08 20:26:17Daniel.Ellissetfiles: + default_branch_etree_doc.patch
keywords: + patch
messages: + msg167710
2012-08-08 17:51:52eli.benderskysetmessages: + msg167700
2012-08-08 16:36:46ezio.melottisetmessages: + msg167693
2012-08-08 16:33:28Daniel.Ellissetmessages: + msg167692
2012-08-08 16:07:09ezio.melottisetmessages: + msg167691
2012-08-08 12:38:40Daniel.Ellissetnosy: + Daniel.Ellis
messages: + msg167688
2012-08-08 06:38:36ezio.melottisetkeywords: + easy
nosy: + ezio.melotti

stage: needs patch
2012-08-08 06:34:38Sarbjit.singhcreate