Added description of what string helper functions in py3compat.py do.

1 files changed, 33 insertions, 0 deletions

diff --git a/lib/Crypto/Util/py3compat.py b/lib/Crypto/Util/py3compat.py
index 139aa73..34e5224 100644
--- a/lib/Crypto/Util/py3compat.py
+++ b/lib/Crypto/Util/py3compat.py
@@ -23,6 +23,39 @@
 # ===================================================================
 
 """Compatibility code for handling string/bytes changes from Python 2.x to Py3k
+
+In Python 2.x, strings (of type ''str'') contain binary data, including encoded
+Unicode text (e.g. UTF-8).  The separate type ''unicode'' holds Unicode text.
+Unicode literals are specified via the u'...' prefix.  Indexing or slicing
+either type always produces a string of the same type as the original.
+Data read from a file is always of '''str'' type.
+
+In Python 3.x, strings (type ''str'') may only contain Unicode text. The u'...'
+prefix and the ''unicode'' type are now redundant.  A new type (called
+''bytes'') has to be used for binary data (including any particular
+''encoding'' of a string).  The b'...' prefix allows one to specify a binary
+literal.  Indexing or slicing a string produces another string.  Slicing a byte
+string produces another byte string, but the indexing operation produces an
+integer.  Data read from a file is of '''str'' type if the file was opened in
+text mode, or of ''bytes'' type otherwise.
+
+Since PyCrypto aims at supporting both Python 2.x and 3.x, the following helper
+functions are used to keep the rest of the library as independent as possible
+from the actual Python version.
+
+In general, the code should always deal with binary strings, and use integers
+instead of 1-byte character strings.
+
+b(s)
+    Take a text string literal (with no prefix or with u'...' prefix) and
+    make a byte string.
+bchr(c)
+    Take an integer and make a 1-character byte string.
+bord(c)
+    Take the result of indexing on a byte string and make an integer.
+tobytes(s)
+    Take a text string, a byte string, or a sequence of character taken from
+    a byte string and make a byte string.
 """
 
 __revision__ = "$Id$"