classification
Title: W3C <-> Python DOM type mapping docs need updating
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.1, Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BreamoreBoy, akuchling, docs@python, fdrake, loewis, mike_j_brown, pitrou, terry.reedy
Priority: low Keywords: easy

Created on 2006-05-25 23:33 by mike_j_brown, last changed 2010-07-25 23:07 by akuchling. This issue is now closed.

Messages (14)
msg28652 - (view) Author: Mike Brown (mike_j_brown) Date: 2006-05-25 23:33
I believe the information at
http://docs.python.org/lib/dom-type-mapping.html is
outdated; most if not all boolean return values, at
least in minidom, are handled as BooleanType, not
IntegerType. This should be standard.

Sorry, I don't have a patch to submit for this. Should
be an easy fix though.
msg28653 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2006-06-03 20:42
Logged In: YES 
user_id=11375

Martin, you probably need to make a pronouncement on this.  The DOM 
mapping is supposed to be derived from the IDL mapping for Python, which 
predates Booleans, but methods such as hasChildNodes() return True/False.
I can see at least three answers:

1) Booleans are subtypes of integers, so the docs are not wrong.

2) The docs are wrong and should say Boolean.

3) The methods should be returning regular 0 and 1, not True and False, and 
should be changed.
msg28654 - (view) Author: Mike Brown (mike_j_brown) Date: 2006-06-03 21:01
Logged In: YES 
user_id=371366

If answer #1 is chosen and the others rejected, then the
docs remain misleading, since the average reader just wants
to know what types to expect from an implementation (or
should code into their implementation), and shouldn't be
expected to know the relationship between Booleans and
integers. Is it even reasonable to expect that this
relationship will always be true? In any case, I'd rather
see it made explicit as to why minidom doesn't seem, at
first, to respect the type mapping, at least in current
implementations. It could be as simple as adding Andrew's
comment, phrased as "This DOM mapping is derived from the
IDL mapping for Python, which predates the introduction of
BooleanType, which is currently a subtype of IntegerType.
Implementations may use either type." or some such.
msg28655 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2006-07-30 04:56
Logged In: YES 
user_id=3066

My position on this is that:

1) The docs are not wrong.

2) The docs should be updated to indicate that bool values
are returned where appropriate.

3) It is reasonable that Python developers know the
relationship between bool and int.  That is not something
that can reasonably change in Python 2.x.  It seems unlikely
to change for Python 3000.

4) The strict application of the IDL mapping really hasn't
helped in creating a good DOM-like interface for Python.

Dealing with the last item isn't within scope for handling
this issue.
msg28656 - (view) Author: Martin v. Löwis (loewis) * (Python committer) Date: 2006-07-30 07:25
Logged In: YES 
user_id=21627

I agree with Fred that the documentation is not wrong as it
stands. As this section is meant to apply not only to
minidom, but to all Python DOM implementations, I don't
think the specification can be changed. minidom would
probably still comply (except perhaps for the "specified"
attribute), but other implementations might comply anymore.

If clarification is needed, it should go beyond boolean:
What is "IntegerType"? There is no type with that name in
Python, and, indeed, "unsigned long" cannot alway map to
types.IntType; unsigned long long (used for DOMTimeStamp)
and unsigned short don't get mapped at all in the table.

I think the intention is this: for the "proper" IDL integer
types (short, long, long long, +unsigned), both Python int
and long can be used. For boolean, int, long, and bool can
be used; on input, any non-zero value counts as true, and on
output, only 0 or 1 should be returned (where bool(0) is
False and bool(1) is True).
msg97241 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-01-05 02:08
'IntType' refers to the 2.x alias types.IntType for int.
Such aliases were removed in the 3.x types module, so 'IntType' is a meaningless term in 3.x docs and should be changed to 'int' therein.

If the Python type for IDL boolean cannot be changed to 'bool', then please make it 'bool or int' so that people will know that they might get either and so that the doc and minidom will agree with each other.
msg97247 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2010-01-05 04:00
I presume you're referring to the documentation for the xml.dom
package (as found at
http://docs.python.org/library/xml.dom.html#type-mapping) rather than
the Python <--> OMG IDL mapping (the link for which appears to have
gone stale).

I'd support the changes you recommend for the xml.dom documentation.
msg97257 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2010-01-05 10:50
I agree that "IntegerType" makes no sense as a "Python Type" (which is how it is referred to here).

Also, the next sentence is a bit obsolete as well:

“Additionally, the DOMString defined in the recommendation is mapped to a Python string or Unicode string. Applications should be able to handle Unicode whenever a string is returned from the DOM.”
msg97291 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-01-06 02:03
Fred: yes, specifically the 3.x versions.

I just noticed that the currently specification is 'IntegerType", which was never used in Python, rather than IntType, which was.

The dead link you refer to is this at the top:
"Python Language Mapping Specification
    This specifies the mapping from OMG IDL to Python."
The current non-working link is
http://www.omg.org/docs/formal/02-11-05.pdf
The new link, which works, is
http://www.omg.org/cgi-bin/doc?formal/02-11-05.pdf
I found this on
http://www.omg.org/cgi-bin/apps/doclist.pl

This should be fixed in all versions.

Antoine: the 3.x version is "Additionally, the DOMString defined in the recommendation is mapped to a bytes or string object. Applications should be able to handle Unicode whenever a string is returned from the DOM." Assuming the first sentence is true, I would just delete the second (for 3.x) as just about every 3.x app must deal with 3.x (unicode) strings.

Summary of recommendations:

1. Replace dead link with new version.

2. Replace 'IntegerType' with 'int' except that entry for IDL boolean should be 'bool or int'.

3a. Could not first sentence referred to above be replaced by a line in the table mapping 'DOMString' to 'string or bytes'? Or is DOMString not an IDL type? Even so, I would put it in the table with a footnote.

3b. Delete obsolete second sentence.

4. Should not the final sentence "The IDL null value is mapped to None, which may be accepted or provided by the implementation whenever null is allowed by the API." be replaced by an additional line in the table
(IDL Type) null .... (Python Type) None
I do not see that rest of sentence adds anything.

Once a set of changes is agreed on, this issue could be reassigned to doc maintainer Georg Brandl to make changes and close this.

Note: my personal concern is with 3.x docs, except that bad link should be fixed for 2.6,7 also.
msg97292 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-01-06 02:13
Addendum. Table 1-2 Basic Data Type Mappings in the referenced OMG document, which maps 'OMG IDL' to 'Python' has 'Integer (<type 'int'>)', later shortened to 'Integer'. (It also has 'Long integer(<type 'long int'>)' and 'Floating Point Number (<type 'float'>)' with similar abbreviations.) So 'IntegerType', possibly mashing together 'Integer' with 'IntType', appears to be an erroneous term from the beginning.
msg111542 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2010-07-25 13:05
Nobody has objected to Terry Reedy's recommendations so can the docs be updated please.
msg111560 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-25 21:34
Unlike with some issues, my in-message recommendations here do not constitute a patch.

docs@python could update the link immediately. I would be willing to review the more extensive patch for 3.x if someone makes one.
msg111563 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2010-07-25 22:11
The current link in the docs works; it's http://www.omg.org/spec/PYTH/1.2/PDF/.
msg111570 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2010-07-25 23:07
Changed on the trunk in rev83149.

I removed both paragraphs after the table, adding null and DOMString to the table, and took the word 'primitive' out of the first sentence (so the table isn't listing just primitive types, but can list DOMString).
History
Date User Action Args
2010-07-25 23:07:10akuchlingsetstatus: open -> closed
resolution: fixed
messages: + msg111570
2010-07-25 22:11:51akuchlingsetmessages: + msg111563
2010-07-25 21:34:33terry.reedysetkeywords: + easy

messages: + msg111560
stage: needs patch
2010-07-25 13:05:54BreamoreBoysetassignee: loewis -> docs@python

messages: + msg111542
nosy: + BreamoreBoy, docs@python
2010-01-06 02:13:10terry.reedysetmessages: + msg97292
2010-01-06 02:03:40terry.reedysetmessages: + msg97291
2010-01-05 10:50:35pitrousetnosy: + pitrou
messages: + msg97257
2010-01-05 04:00:51fdrakesetmessages: + msg97247
2010-01-05 02:08:24terry.reedysetnosy: + terry.reedy

messages: + msg97241
versions: + Python 3.1, Python 3.2, - Python 2.6, Python 3.0
2009-03-21 02:47:34ajaksu2setpriority: normal -> low
type: enhancement
versions: + Python 2.6, Python 3.0, - Python 2.5
2006-05-25 23:33:28mike_j_browncreate