W3C <-> Python DOM type mapping docs need updating

[mikejbrown]

BPO	1495229
Nosy	@loewis, @freddrake, @akuchling, @terryjreedy, @pitrou

^{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 2010-07-25.23:07:10.421>
created_at = <Date 2006-05-25.23:33:28.000>
labels = ['easy', 'type-feature', 'docs']
title = 'W3C <-> Python DOM type mapping docs need updating'
updated_at = <Date 2010-07-25.23:07:10.420>
user = 'https://bugs.python.org/mikejbrown'

bugs.python.org fields:

activity = <Date 2010-07-25.23:07:10.420>
actor = 'akuchling'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-07-25.23:07:10.421>
closer = 'akuchling'
components = ['Documentation']
creation = <Date 2006-05-25.23:33:28.000>
creator = 'mike_j_brown'
dependencies = []
files = []
hgrepos = []
issue_num = 1495229
keywords = ['easy']
message_count = 14.0
messages = ['28652', '28653', '28654', '28655', '28656', '97241', '97247', '97257', '97291', '97292', '111542', '111560', '111563', '111570']
nosy_count = 8.0
nosy_names = ['loewis', 'fdrake', 'akuchling', 'mike_j_brown', 'terry.reedy', 'pitrou', 'docs@python', 'BreamoreBoy']
pr_nums = []
priority = 'low'
resolution = 'fixed'
stage = 'needs patch'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue1495229'
versions = ['Python 3.1', 'Python 3.2']

[mikejbrown]

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.

[akuchling]

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.

[mikejbrown]

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.

[freddrake]

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.

[loewis]

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

[terryjreedy]

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

[freddrake]

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.

[pitrou]

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

[terryjreedy]

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.

[terryjreedy]

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.

[BreamoreBoy]

Nobody has objected to Terry Reedy's recommendations so can the docs be updated please.

[terryjreedy]

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.

[akuchling]

The current link in the docs works; it's http://www.omg.org/spec/PYTH/1.2/PDF/.

[akuchling]

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