[Python-checkins] peps: Add open issues section, add macros, adjust macro names to implementation.

[martin.v.loewis]

http://hg.python.org/peps/rev/9ab95b0fabaa
changeset:   3931:9ab95b0fabaa
user:        Martin v. Löwis <martin at v.loewis.de>
date:        Sat Aug 27 07:22:44 2011 +0200
summary:
  Add open issues section, add macros, adjust macro names to implementation.

files:
  pep-0393.txt |  45 +++++++++++++++++++++++++++++++--------
  1 files changed, 35 insertions(+), 10 deletions(-)


diff --git a/pep-0393.txt b/pep-0393.txt
--- a/pep-0393.txt
+++ b/pep-0393.txt
@@ -145,10 +145,17 @@
 
 The canonical representation can be accessed using two macros
 PyUnicode_Kind and PyUnicode_Data. PyUnicode_Kind gives one of the
-values PyUnicode_1BYTE (1), PyUnicode_2BYTE (2), or PyUnicode_4BYTE
-(3). PyUnicode_Data gives the void pointer to the data, masking out
-the pointer kind. All these functions call PyUnicode_Ready
-in case the canonical representation hasn't been computed yet.
+values PyUnicode_WCHAR_KIND (0), PyUnicode_1BYTE_KIND (1),
+PyUnicode_2BYTE_KIND (2), or PyUnicode_4BYTE_KIND (3). PyUnicode_DATA
+gives the void pointer to the data. All these functions call
+PyUnicode_Ready in case the canonical representation hasn't been
+computed yet. Access to individual characters should use
+PyUnicode_{READ|WRITE}[_CHAR]:
+ 
+ - PyUnciode_READ(kind, data, index)
+ - PyUnicode_WRITE(kind, data, index, value)
+ - PyUnicode_READ_CHAR(unicode, index)
+ - PyUnicode_WRITE_CHAR(unicode, index, value)
 
 A new function PyUnicode_AsUTF8 is provided to access the UTF-8
 representation. It is thus identical to the existing
@@ -163,13 +170,6 @@
 PyUnicode_AsUnicode is deprecated; it computes the wstr representation
 on first use.
 
-String Operations
------------------
-
-Various convenience functions will be provided to deal with the
-canonical representation, in particular with respect to concatenation
-and slicing.
-
 Stable ABI
 ----------
 
@@ -181,6 +181,30 @@
 about the internals of CPython's data types, include PyUnicodeObject
 instances.  It will need to be slightly updated to track the change.
 
+Open Issues
+===========
+
+- When an application uses the legacy API, it may hold onto
+  the Py_UNICODE* representation, and yet start calling Unicode
+  APIs, which would call PyUnicode_Ready, invalidating the 
+  Py_UNICODE* representation; this would be an incompatible change.
+  The following solutions can be considered:
+
+  * accept it as an incompatible change. Applications using the
+    legacy API will have to fill out the Py_UNICODE buffer completely
+    before calling any API on the string under construction.
+  * require explicit PyUnicode_Ready calls in such applications;
+    fail with a fatal error if a non-ready string is ever read.
+    This would also be an incompatible change, but one that is
+    more easily detected during testing.
+  * as a compromise between these approaches, implicit PyUnicode_Ready
+    calls (i.e. those not deliberately following the construction of
+    a PyUnicode object) could produce a warning if they convert an
+    object.
+
+- Which of the APIs created during the development of the PEP should
+  be public?
+
 Discussion
 ==========
 

-- 
Repository URL: http://hg.python.org/peps