[SQL-CVS] r1895 - SQLObject/docs

[<sub...@co...>]

Author: phd
Date: 2006-09-01 07:14:02 -0600 (Fri, 01 Sep 2006)
New Revision: 1895

Modified:
   SQLObject/docs/News.txt
   SQLObject/docs/SQLObject.txt
Log:
Updated docs.


Modified: SQLObject/docs/News.txt
===================================================================
--- SQLObject/docs/News.txt	2006-09-01 13:12:58 UTC (rev 1894)
+++ SQLObject/docs/News.txt	2006-09-01 13:14:02 UTC (rev 1895)
@@ -109,6 +109,25 @@
 Bug Fixes
 ---------
 
+* Fixed a longstanding problem with UnicodeCol - at last you can use unicode
+  strings in .select() and .selectBy() queries. There are some limitations,
+  though:
+
+  - only simple q-magic fields are supported; no expressions;
+  - only == and <> operators are supported;
+
+  The following code works::
+
+    MyTable.select(u'value' == MyTable.q.name)
+    MyTable.select(MyTable.q.name <> u'value')
+    MyTable.select(OR(MyTable.q.col1 == u'value1', MyTable.q.col2 <> u'value2'))
+    MyTable.selectBy(name = u'value')
+    MyTable.selectBy(col1=u'value1', col2=u'value2')
+
+  The following still does not work::
+
+    MyTable.select((MyTable.q.name + MyTable.q.surname) == u'value')
+
 * Cull patch (clear cache).
 
 * .destroySelf() inside a transaction.

Modified: SQLObject/docs/SQLObject.txt
===================================================================
--- SQLObject/docs/SQLObject.txt	2006-09-01 13:12:58 UTC (rev 1894)
+++ SQLObject/docs/SQLObject.txt	2006-09-01 13:14:02 UTC (rev 1895)
@@ -1128,11 +1128,28 @@
     A subclass of `StringCol`.  Also accepts a dbEncoding keyword
     argument, which defaults to ``"UTF-8"``.  Values coming in and
     out from the database will be encoded and decoded.  **Note**:
-    parameters in queries will not be automatically encoded, so if
-    you do a query matching a UnicodeCol column you must apply the
-    encoding yourself.
+    there are some limitations on using UnicodeCol in queries:
 
+    - only simple q-magic fields are supported; no expressions;
+    - only == and <> operators are supported;
 
+    The following code works::
+
+        MyTable.select(u'value' == MyTable.q.name)
+        MyTable.select(MyTable.q.name <> u'value')
+        MyTable.select(OR(MyTable.q.col1 == u'value1', MyTable.q.col2 <> u'value2'))
+        MyTable.selectBy(name = u'value')
+        MyTable.selectBy(col1=u'value1', col2=u'value2')
+
+    The following does not work::
+
+        MyTable.select((MyTable.q.name + MyTable.q.surname) == u'value')
+
+    In that case you must apply the encoding yourself::
+
+        MyTable.select((MyTable.q.name + MyTable.q.surname) == u'value'.encode(dbEncoding))
+
+
 .. Relationships_:
 
 Relationships Between Classes/Tables