merge upstream ElementTree 1.3 and cElementTree 1.0.6 in /python/trunk/

Modules/celementtree.h

+/* Stuff to export relevant entry points from cElementTree */
+
+/* To use this API, do
+
+   struct cElementTree_CAPI *capi;
+   capi = PyCObject_Import("cElementTree", "CAPI");
+
+   Also check that capi->magic and capi->size matches the values from
+   this header, e.g:
+
+   if (strcmp(capi->magic, cElementTree_CAPI_MAGIC) != 0 ||
+       capi->size < sizeof(struct cElementTree_CAPI) ||
+       capi->version < cElementTree_CAPI_VERSION)
+       ... cannot use this version ...
+
+   See below for a summary of the available API functions.
+
+*/
+
+/* major version */
+#define cElementTree_CAPI_MAGIC  "cElementTree.CAPI 1.0"
+
+/* minor version. new minor versions should always be backwards compatible */
+#define cElementTree_CAPI_VERSION 1
+
+/* struct to store a snapshot of a given Element */
+struct cElementTree_Snapshot
+{
+    /* filled in by snapshot method.  members may be Py_None if not present
+       in the internal structure.  all references are new; use DECREF to clean
+       up */
+    PyObject* tag;
+    PyObject* attrib;
+    PyObject* text;
+    PyObject* tail;
+    PyObject* children; /* only filled in if mode > 0 */
+
+    /* always add new stuff to the end! */
+};
+
+struct cElementTree_CAPI·
+{
+    char* magic; /* set to cElementTree_CAPI_MAGIC */
+    int size; /* set to sizeof(struct cElementTree_CAPI) */
+    int version; /* set to cElementTree_CAPI_VERSION (API version) */
+
+    /* pointers to selected cElementTree helpers.  add new functions at
+       the end, if needed */
+
+    /* Element type (to be used for exact type comparisions) */
+    PyObject* type;

[Antoine Pitrou, 2010/02/15 15:06:56]

The doc/comments should state whether this reference is owned or borrowed (i.e.,
whether one should Py_DECREF it when done with the capi struct).

[flox, 2010/02/15 16:42:32]

Added a statement "borrowed reference".

+
+    /* Check if object is a cElementTree Element, and raises a TypeError
+       if not.  Use this before calling other methods. */
+    /* Returns 0 if ok, -1 if error. */
+    int (*assert)(PyObject* elem);

[Antoine Pitrou, 2010/02/15 15:06:56]

I'm not sure calling this "assert" is a good idea. If some C compiler uses a
#define for the standard "assert", it can refuse to compile or compile to the
wrong symbol. Why not something explicit such as "checktype"?

[flox, 2010/02/15 16:42:32]

Agreed.

+
+    /* Get Element snapshot.  Use mode=1 to get children too. */
+    /* The 'elem' argument must point to a cElementTree Element.  Use
+       'assert' first when in doubt. */
+    /* All references are new, and point to stable versions (that is,·
+       changing the original Element won't affect the snapshot). */
+    /* Py_None may be used for non-existent/empty fields. */
+    /* Returns 0 if ok, -1 if error. */
+    int (*snapshot)(
+        PyObject* elem, struct cElementTree_Snapshot* snapshot, int mode
+        );
+
+    /* Get subelement. */
+    /* The 'elem' argument must point to a cElementTree Element.  Use
+       'assert' first when in doubt. */
+    /* Returns a borrowed reference, or Py_None if the element does not

[Antoine Pitrou, 2010/02/15 15:06:56]

The doc is wrong, because the implementation returns a new reference. Either the
doc or the implementation should be fixed. 

[flox, 2010/02/15 16:42:32]

Fixed the implementation.

+       exist. */
+    PyObject* (*getitem)(PyObject* elem, int index);

[Antoine Pitrou, 2010/02/15 15:06:56]

The index should probably be a Py_ssize_t instead.

[flox, 2010/02/15 16:42:32]

Ok.

+
+    /* always add new stuff to the end! */
+};