Permalink
Browse files

Clarify how the "encoding" parameter fits with tnetstrings spec.

  • Loading branch information...
1 parent af3362d commit 2c251f153f219727eb53ce87261b39d2ad1bea51 @rfk committed Feb 13, 2012
Showing with 11 additions and 12 deletions.
  1. +5 −5 README.rst
  2. +6 −7 tnetstring/__init__.py
View
@@ -1,5 +1,4 @@
-
tnetstring: data serialization using typed netstrings
======================================================
@@ -36,13 +35,14 @@ at once, there's no efficiency gain from using the file-based versions of these
functions. They're only here so you can use load() to read precisely one
item from a file or socket without consuming any extra data.
-By default tnetstrings work only with byte strings, not unicode. If you want
-unicode strings then pass an optional encoding to the various functions,
-like so::
+The tnetstrings specification explicitly states that strings are binary blobs
+and forbids the use of unicode at the protocol level. As a convenience to
+python programmers, this library lets you specify an application-level encoding
+to translate python's unicode strings to and from binary blobs:
>>> print repr(tnetstring.loads("2:\xce\xb1,"))
'\xce\xb1'
>>>
- >>> print repr(tnetstring.loads("2:\xce\xb1,","utf8"))
+ >>> print repr(tnetstring.loads("2:\xce\xb1,", "utf8"))
u'\u03b1'
View
@@ -1,5 +1,4 @@
"""
-
tnetstring: data serialization using typed netstrings
======================================================
@@ -36,15 +35,16 @@
functions. They're only here so you can use load() to read precisely one
item from a file or socket without consuming any extra data.
-By default tnetstrings work only with byte strings, not unicode. If you want
-unicode strings then pass an optional encoding to the various functions,
-like so::
+The tnetstrings specification explicitly states that strings are binary blobs
+and forbids the use of unicode at the protocol level. As a convenience to
+python programmers, this library lets you specify an application-level encoding
+to translate python's unicode strings to and from binary blobs:
>>> print repr(tnetstring.loads("2:\\xce\\xb1,"))
'\\xce\\xb1'
>>>
- >>> print repr(tnetstring.loads("2:\\xce\\xb1,","utf8"))
- u'\u03b1'
+ >>> print repr(tnetstring.loads("2:\\xce\\xb1,", "utf8"))
+ u'\\u03b1'
"""
@@ -390,4 +390,3 @@ def pop(string,encoding=None):
loads = _tnetstring.loads
pop = _tnetstring.pop
-

0 comments on commit 2c251f1

Please sign in to comment.