Provide some examples for usage of ElementTree methods/attributes

[Sarbjitsingh]

BPO	15586
Nosy	@ezio-melotti, @merwok, @bitdancer
Files	default_branch_etree_doc.patch default_branch_etree_doc_2.patch 2.7_branch_etree_doc.patch default_branch_etree_doc_3.patch 2.7_branch_etree_doc_2.patch 2.7_branch_etree_doc_3.patch

^{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 = None
closed_at = <Date 2012-10-15.12:51:30.913>
created_at = <Date 2012-08-08.06:34:38.517>
labels = ['easy', 'type-feature', 'docs']
title = 'Provide some examples for usage of ElementTree methods/attributes'
updated_at = <Date 2012-10-15.12:51:30.912>
user = 'https://bugs.python.org/Sarbjitsingh'

bugs.python.org fields:

activity = <Date 2012-10-15.12:51:30.912>
actor = 'eli.bendersky'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-10-15.12:51:30.913>
closer = 'eli.bendersky'
components = ['Documentation']
creation = <Date 2012-08-08.06:34:38.517>
creator = 'Sarbjit.singh'
dependencies = []
files = ['26726', '26741', '26785', '26786', '26802', '26853']
hgrepos = []
issue_num = 15586
keywords = ['patch', 'easy']
message_count = 24.0
messages = ['167670', '167688', '167691', '167692', '167693', '167700', '167710', '167766', '167767', '167770', '167785', '167786', '167787', '168122', '168123', '168172', '168173', '168198', '168255', '168280', '168281', '168383', '168491', '168492']
nosy_count = 8.0
nosy_names = ['ezio.melotti', 'eric.araujo', 'r.david.murray', 'eli.bendersky', 'docs@python', 'python-dev', 'Daniel.Ellis', 'Sarbjit.singh']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15586'
versions = ['Python 2.7', 'Python 3.3', 'Python 3.4']

[Sarbjitsingh]

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)

[DanielEllis]

I have been working with ElementTree for the last few months and would love to help out with this.

[ezio-melotti]

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.

[DanielEllis]

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\>

---

[ezio-melotti]

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.

[elibendersky]

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.

[DanielEllis]

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.

[elibendersky]

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).

[elibendersky]

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?

[elibendersky]

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.

[DanielEllis]

Changes to documentation per Ezio and Eli's suggestions.