[gnome-devel-docs] tutorials python: pages on strings and properties updated

[Marta Maria Casetti <mmcasetti src gnome org>]

commit 1f255eff495fc59c454f3dc890d6e4e807f91166
Author: Marta Maria Casetti <mmcasetti gmail com>
Date:   Fri Aug 3 13:08:44 2012 +0100

    tutorials python: pages on strings and properties updated

 platform-demos/C/properties.py.page |    6 +++-
 platform-demos/C/strings.py.page    |   41 ++++++++++++++++++++++++++++------
 2 files changed, 37 insertions(+), 10 deletions(-)
---
diff --git a/platform-demos/C/properties.py.page b/platform-demos/C/properties.py.page
index 69a3aa7..9303f38 100644
--- a/platform-demos/C/properties.py.page
+++ b/platform-demos/C/properties.py.page
@@ -5,7 +5,7 @@
       id="properties.py">
 
 <info>
-  <link type="guide" xref="beginner.py#tutorials"/>
+  <link type="guide" xref="tutorial.py#theory"/>
   <revision version="0.1" date="2012-06-24" status="draft"/>
 
   <desc>An explanation of properties, getters and setters.</desc>
@@ -39,7 +39,9 @@ label.set_label("Hello World")
 label.set_angle(25)
 label.set_halign(Gtk.Align.END)</code>
 
-<p>Once you have created such a label, you can get the text with the getter <code>label.get_label()</code>. Instead of using getters and setters you can also get and set the properties with <code>widget.get_property("prop-name")</code> and <code>widget.set_property("prop-name", value)</code>, respectively.</p>
+<p>Once you have created such a label, you can get the text with the getter <code>label.get_label()</code>.</p>
+
+<p>Instead of using getters and setters you can also get and set the properties with <code>get_property("prop-name")</code> and <code>set_property("prop-name", value)</code>, respectively.</p>
 
 </section>
 <section id="references">
diff --git a/platform-demos/C/strings.py.page b/platform-demos/C/strings.py.page
index a9fea61..441085a 100644
--- a/platform-demos/C/strings.py.page
+++ b/platform-demos/C/strings.py.page
@@ -5,7 +5,7 @@
       id="strings.py">
 
 <info>
-  <link type="guide" xref="beginner.py#tutorials"/>
+  <link type="guide" xref="tutorial.py#theory"/>
   <revision version="0.1" date="2012-06-16" status="draft"/>
 
   <desc>An explanation of how to deal with strings in Python and GTK+.</desc>
@@ -41,16 +41,16 @@
 
 </section>
 
-<section id="python">
-<title>Strings in Python</title>
+<section id="python-2">
+<title>Strings in Python 2</title>
 
 <p>Python 2 comes with two different kinds of objects that can be used to represent strings, <code>str</code> and <code>unicode</code>. Instances of <code>unicode</code> are used to express Unicode strings, whereas instances of the <code>str</code> type are byte representations (the encoded string). Under the hood, Python represents Unicode strings as either 16- or 32-bit integers, depending on how the Python interpreter was compiled.</p>
 
 <code><![CDATA[
 >>> unicode_string = u"Fu\u00dfb\u00e4lle"
->>> print unicode_string
-FuÃbÃlle
-]]></code>
+>>> print unicode_string]]>
+Fu&#223;b&#228;lle
+</code>
 
 <p>Unicode strings can be converted to 8-bit strings with <code>unicode.encode()</code>. Pythonâs 8-bit strings have a <code>str.decode()</code> method that interprets the string using the given encoding (that is, it is the inverse of the <code>unicode.encode()</code>):</p>
 
@@ -69,6 +69,27 @@ True]]></code>
 
 </section>
 
+<section id="python-3">
+<title>Strings in Python 3</title>
+
+<p>Since Python 3.0, all strings are stored as Unicode in an instance of the <code>str</code> type. Encoded strings on the other hand are represented as binary data in the form of instances of the bytes type. Conceptionally, <code>str</code> refers to text, whereas bytes refers to data. Use <code>encode()</code> to go from <code>str</code> to <code>bytes</code>, and <code>decode()</code> to go from <code>bytes</code> to <code>str</code>.</p>
+
+<p>In addition, it is no longer possible to mix Unicode strings with encoded strings, because it will result in a <code>TypeError</code>:</p>
+
+<code><![CDATA[
+>>> text = "Fu\u00dfb\u00e4lle"
+>>> data = b" sind rund"
+>>> text + data
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+TypeError: Can't convert 'bytes' object to str implicitly
+>>> text + data.decode("utf-8")
+'FuÃbÃlle sind rund'
+>>> text.encode("utf-8") + data
+b'Fu\xc3\x9fb\xc3\xa4lle sind rund']]></code>
+
+</section>
+
 <section id="gtk">
 <title>Unicode in GTK+</title>
 
@@ -90,14 +111,18 @@ True]]></code>
 
 <p>would return <code>False</code>, with the warning <code>__main__:1: UnicodeWarning: Unicode equal comparison failed to convert both arguments to Unicode - interpreting them as being unequal</code> (<code>Gtk.Label.get_text()</code> will always return a <code>str</code> instance; therefore, <code>txt</code> and <code>unicode_string</code> are not equal).</p>
 
-<p>This is especially important if you want to internationalize your program using <link href="http://docs.python.org/library/gettext.html";><code>gettext</code></link>. You have to make sure that <code>gettext</code> will return UTF-8 encoded 8-bit strings for all languages. In general it is recommended to not use <code>unicode</code> objects in GTK+ applications at all and only use UTF-8 encoded <code>str</code> objects since GTK+ does not fully integrate with <code>unicode</code> objects.</p>
+<p>This is especially important if you want to internationalize your program using <link href="http://docs.python.org/library/gettext.html";><code>gettext</code></link>. You have to make sure that <code>gettext</code> will return UTF-8 encoded 8-bit strings for all languages.</p>
+
+<p>In general it is recommended to not use <code>unicode</code> objects in GTK+ applications at all, and only use UTF-8 encoded <code>str</code> objects since GTK+ does not fully integrate with <code>unicode</code> objects.</p>
+
+<p>With Python 3.x things are much more consistent, because PyGObject will automatically encode/decode to/from UTF-8 if you pass a string to a method or a method returns a string. Strings, or text, will always be represented as instances of <code>str</code> only:</p>
 
 </section>
 
 <section id="references">
 <title>References</title>
 
-<p><link href="http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html";>How To Deal With Strings - The Python GTK+ 3 Tutorial</link> (includes also a discussion on Python 3)</p>
+<p><link href="http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html";>How To Deal With Strings - The Python GTK+ 3 Tutorial</link></p>
 
 </section>