Update docu about the bytes and unicode

docs/api/database.rst

@@ -20,8 +20,8 @@ Database object
 
         Set the database entry for "key" to "value".
 
-        :param string key: Name for this entry
+        :param bytes key: Name for this entry
-        :param string value: Data for this entry
+        :param bytes value: Data for this entry
         :param bool sync: 
             If ``True``, the write will be flushed from the operating system
             buffer cache (by calling WritableFile::Sync()) before the write
@@ -46,7 +46,7 @@ Database object
 
         Remove the database entry for "key".
 
-        :param string key: Name to delete
+        :param bytes key: Name to delete
         :param sync: See :py:meth:`rocksdb.DB.put`
         :param disable_wal: See :py:meth:`rocksdb.DB.put`
         :raises rocksdb.errors.NotFound: If the key did not exists
@@ -74,7 +74,7 @@ Database object
 
     .. py:method:: get(key, verify_checksums=False, fill_cache=True, prefix_seek=False, snapshot=None, read_tier="all")
 
-        :param string key: Name to get
+        :param bytes key: Name to get
 
         :param bool verify_checksums: 
             If ``True``, all data read from underlying storage will be
@@ -110,12 +110,12 @@ Database object
     .. py:method:: multi_get(keys, verify_checksums=False, fill_cache=True, prefix_seek=False, snapshot=None, read_tier="all")
 
         :param keys: Keys to fetch
-        :type keys: list of strings
+        :type keys: list of bytes
 
         For the other params see :py:meth:`rocksdb.DB.get`
 
         :returns:
-            A ``dict`` where the value is either ``string`` or ``None`` if not found
+            A ``dict`` where the value is either ``bytes`` or ``None`` if not found
 
         :raises: If the fetch for a single key fails
         
@@ -131,7 +131,7 @@ Database object
         This check is potentially lighter-weight than invoking DB::get().
         One way to make this lighter weight is to avoid doing any IOs.
 
-        :param string key: Key to check
+        :param bytes key: Key to check
         :param bool fetch: Obtain also the value if found
 
         For the other params see :py:meth:`rocksdb.DB.get`
@@ -146,7 +146,7 @@ Database object
 
         Iterate over the keys
 
-        :param string prefix: Not implemented yet
+        :param bytes prefix: Not implemented yet
 
         For other params see :py:meth:`rocksdb.DB.get`
 
@@ -160,7 +160,7 @@ Database object
 
         Iterate over the values
 
-        :param string prefix: Not implemented yet
+        :param bytes prefix: Not implemented yet
 
         For other params see :py:meth:`rocksdb.DB.get`
 
@@ -174,7 +174,7 @@ Database object
 
         Iterate over the items
 
-        :param string prefix: Not implemented yet
+        :param bytes prefix: Not implemented yet
 
         For other params see :py:meth:`rocksdb.DB.get`
 
@@ -197,18 +197,18 @@ Database object
 
         DB implementations can export properties about their state
         via this method. If "property" is a valid property understood by this
-        DB implementation, a string with its value is returned.
+        DB implementation, a byte string with its value is returned.
         Otherwise ``None``
         
         Valid property names include:
         
-        * ``"rocksdb.num-files-at-level<N>"``: return the number of files at level <N>,
+        * ``b"rocksdb.num-files-at-level<N>"``: return the number of files at level <N>,
             where <N> is an ASCII representation of a level number (e.g. "0").
 
-        * ``"rocksdb.stats"``: returns a multi-line string that describes statistics
+        * ``b"rocksdb.stats"``: returns a multi-line byte string that describes statistics
             about the internal operation of the DB.
 
-        * ``"rocksdb.sstables"``: returns a multi-line string that describes all
+        * ``b"rocksdb.sstables"``: returns a multi-line byte string that describes all
             of the sstables that make up the db contents.
 
     .. py:method:: get_live_files_metadata()
@@ -265,7 +265,7 @@ Iterator
 
     .. py:method:: seek(key)
     
-        :param string key: Position at the first key in the source that at or past
+        :param bytes key: Position at the first key in the source that at or past
  
     Methods to support the python iterator protocol
 
@@ -294,16 +294,16 @@ WriteBatch
      after the following batch is written::
      
         batch = rocksdb.WriteBatch()
-        batch.put("key", "v1")
+        batch.put(b"key", b"v1")
-        batch.delete("key")
+        batch.delete(b"key")
-        batch.put("key", "v2")
+        batch.put(b"key", b"v2")
-        batch.put("key", "v3")
+        batch.put(b"key", b"v3")
 
     .. py:method:: __init__(data=None)
 
         Creates a WriteBatch.
 
-        :param string data:
+        :param bytes data:
             A serialized version of a previous WriteBatch. As retrieved
             from a previous .data() call. If ``None`` a empty WriteBatch is
             generated
@@ -312,21 +312,21 @@ WriteBatch
     
         Store the mapping "key->value" in the database.
 
-        :param string key: Name of the entry to store
+        :param bytes key: Name of the entry to store
-        :param string value: Data of this entry
+        :param bytes value: Data of this entry
 
     .. py:method:: merge(key, value)
     
         Merge "value" with the existing value of "key" in the database.
 
-        :param string key: Name of the entry to merge
+        :param bytes key: Name of the entry to merge
-        :param string value: Data to merge
+        :param bytes value: Data to merge
 
     .. py:method:: delete(key)
  
         If the database contains a mapping for "key", erase it.  Else do nothing.
 
-        :param string key: Key to erase
+        :param bytes key: Key to erase
 
     .. py:method:: clear()
 
@@ -336,7 +336,7 @@ WriteBatch
 
         Retrieve the serialized version of this batch.
 
-        :rtype: string
+        :rtype: ``bytes``
 
     .. py:method:: count()
     

docs/api/interfaces.rst

@@ -15,8 +15,8 @@ Comparator
 
         Three-way comparison.
 
-        :param string a: First field to compare
+        :param bytes a: First field to compare
-        :param string b: Second field to compare
+        :param bytes b: Second field to compare
         :returns: * -1 if a < b
                   * 0 if a == b
                   * 1 if a > b
@@ -35,7 +35,7 @@ Comparator
         Names starting with "rocksdb." are reserved and should not be used
         by any clients of this package.
 
-        :rtype: ``string``
+        :rtype: ``bytes``
 
 Merge Operator
 ==============
@@ -75,11 +75,11 @@ AssociativeMergeOperator
 
         Gives the client a way to express the read -> modify -> write semantics
 
-        :param string key: The key that's associated with this merge operation
+        :param bytes key: The key that's associated with this merge operation
-        :param string existing_value: The current value in the db.
+        :param bytes existing_value: The current value in the db.
                                       ``None`` indicates the key does not exist
                                       before this op
-        :param string value: The value to update/merge the existing_value with
+        :param bytes value: The value to update/merge the existing_value with
 
         :returns: ``True`` and the new value on success.
                   All values passed in will be client-specific values.
@@ -88,7 +88,7 @@ AssociativeMergeOperator
                   The client should assume that this will be treated as an
                   error by the library.
 
-        :rtype: ``(bool, string)``
+        :rtype: ``(bool, bytes)``
 
     .. py:method:: name()
 
@@ -96,7 +96,7 @@ AssociativeMergeOperator
         For example a DB created with one MergeOperator is accessed using a
         different MergeOperator.
 
-        :rtype: ``string``
+        :rtype: ``bytes``
 
 MergeOperator
 -------------
@@ -107,18 +107,18 @@ MergeOperator
 
         Gives the client a way to express the read -> modify -> write semantics
 
-        :param string key: The key that's associated with this merge operation.
+        :param bytes key: The key that's associated with this merge operation.
                            Client could multiplex the merge operator based on it
                            if the key space is partitioned and different subspaces
                            refer to different types of data which have different
                            merge operation semantics
 
-        :param string existing_value: The current value in the db.
+        :param bytes existing_value: The current value in the db.
                                      ``None`` indicates the key does not exist
                                      before this op
 
         :param operand_list: The sequence of merge operations to apply.
-        :type operand_list: list of strings
+        :type operand_list: list of bytes 
 
         :returns: ``True`` and the new value on success.
                   All values passed in will be client-specific values.
@@ -127,7 +127,7 @@ MergeOperator
                   The client should assume that this will be treated as an
                   error by the library.
 
-        :rtype: ``(bool, string)``
+        :rtype: ``(bool, bytes)``
 
     .. py:method:: partial_merge(key, left_operand, right_operand)
 
@@ -147,10 +147,10 @@ MergeOperator
         operations, and apply them in the correct order once a base-value
         (a Put/Delete/End-of-Database) is seen.
 
-        :param string key: the key that is associated with this merge operation.
+        :param bytes key: the key that is associated with this merge operation.
-        :param string left_operand: First operand to merge
+        :param bytes left_operand: First operand to merge
-        :param string right_operand: Second operand to merge
+        :param bytes right_operand: Second operand to merge
-        :rtype: ``(bool, string)``
+        :rtype: ``(bool, bytes)``
 
         .. note::
 
@@ -166,7 +166,7 @@ MergeOperator
         For example a DB created with one MergeOperator is accessed using a
         different MergeOperator.
 
-        :rtype: ``string``
+        :rtype: ``bytes``
 
 FilterPolicy
 ============
@@ -180,17 +180,17 @@ FilterPolicy
         :param keys: list of keys (potentially with duplicates)
                      that are ordered according to the user supplied
                      comparator. 
-        :type keys: list of strings
+        :type keys: list of bytes
 
         :returns: A filter that summarizes keys
-        :rtype: ``string``
+        :rtype: ``bytes``
 
     .. py:method:: key_may_match(key, filter)
 
         Check if the key is maybe in the filter. 
 
-        :param string key: Key for a single entry inside the database
+        :param bytes key: Key for a single entry inside the database
-        :param string filter: Contains the data returned by a preceding call
+        :param bytes filter: Contains the data returned by a preceding call
                               to create_filter on this class
         :returns: This method must return ``True`` if the key was in the list
                   of keys passed to create_filter().
@@ -207,4 +207,4 @@ FilterPolicy
         must be changed.  Otherwise, old incompatible filters may be
         passed to methods of this type.
 
-        :rtype: ``string``
+        :rtype: ``bytes``

docs/index.rst

@@ -7,10 +7,10 @@ Python bindings to the C++ interface of http://rocksdb.org/ using cython::
 
     import rocksdb
     db = rocksdb.DB("test.db", rocksdb.Options(create_if_missing=True))
-    db.put("a", "b")
+    db.put(b"a", b"b")
-    print db.get("a")
+    print db.get(b"a")
 
-Tested with python2.7
+Tested with python2.7 and python3.3
 
 .. toctree::
     :maxdepth: 2
@@ -23,16 +23,8 @@ Tested with python2.7
 RoadMap/TODO
 ------------
 
-* Links from tutorial to API pages (for example merge operator)
-* support python3.3.
-  Make it fix what kind of strings are allow.
-
-  * Arbitrary ``unicode`` and then do some encoding/decoding, like
-    `redis-driver <https://github.com/andymccurdy/redis-py/blob/2.8.0/redis/connection.py#L319>`_
-
-  * Or just ASCII ``bytes`` and let the user handle unicode.
-
 * support prefix API
+* Links from tutorial to API pages (for example merge operator)
 
 Indices and tables
 ==================

docs/tutorial/index.rst

@@ -27,9 +27,9 @@ A more production ready open can look like this ::
     db = rocksdb.DB("test.db", opts)
 
 It assings a cache of 2.5G, uses a bloom filter for faster lookups and keeps
-more data (64 MB) in memory before writting a .sst file
+more data (64 MB) in memory before writting a .sst file.
 
-About bytes and unicode
+About Bytes and Unicode
 ========================
 
 RocksDB stores all data as uninterpreted *byte strings*.
@@ -49,8 +49,7 @@ The only place where you can pass unicode objects are filesytem paths like
 
 * :py:attr:`rocksdb.Options.db_log_dir`
 
-To encode this unicode objects the `sys.getfilesystemencoding()` encoding is used
+To encode this path name, `sys.getfilesystemencoding()` encoding is used.
-
 
 Access
 ======
@@ -58,37 +57,37 @@ Access
 Store, Get, Delete is straight forward ::
 
     # Store
-    db.put("key", "value")
+    db.put(b"key", b"value")
 
     # Get
-    db.get("key")
+    db.get(b"key")
 
     # Delete
-    db.delete("key")
+    db.delete(b"key")
 
 It is also possible to gather modifications and
 apply them in a single operation ::
 
     batch = rocksdb.WriteBatch()
-    batch.put("key", "v1")
+    batch.put(b"key", b"v1")
-    batch.delete("key")
+    batch.delete(b"key")
-    batch.put("key", "v2")
+    batch.put(b"key", b"v2")
-    batch.put("key", "v3")
+    batch.put(b"key", b"v3")
 
     db.write(batch)
 
 Fetch of multiple values at once ::
 
-    db.put("key1", "v1")
+    db.put(b"key1", b"v1")
-    db.put("key2", "v2")
+    db.put(b"key2", b"v2")
 
-    ret = db.multi_get(["key1", "key2", "key3"])
+    ret = db.multi_get([b"key1", b"key2", b"key3"])
 
-    # prints "v1"
+    # prints b"v1"
-    print ret["key1"]
+    print ret[b"key1"]
 
     # prints None
-    print ret["key3"]
+    print ret[b"key3"]
 
 Iteration
 =========
@@ -96,22 +95,22 @@ Iteration
 Iterators behave slightly different than expected. Per default they are not
 valid. So you have to call one of its seek methods first ::
 
-    db.put("key1", "v1")
+    db.put(b"key1", b"v1")
-    db.put("key2", "v2")
+    db.put(b"key2", b"v2")
-    db.put("key3", "v3")
+    db.put(b"key3", b"v3")
 
     it = db.iterkeys()
     it.seek_to_first()
 
-    # prints ['key1', 'key2', 'key3']
+    # prints [b'key1', b'key2', b'key3']
     print list(it)
 
     it.seek_to_last()
-    # prints ['key3']
+    # prints [b'key3']
     print list(it)
 
-    it.seek('key2')
+    it.seek(b'key2')
-    # prints ['key2', 'key3']
+    # prints [b'key2', b'key3']
     print list(it)
 
 There are also methods to iterate over values/items ::
@@ -119,13 +118,13 @@ There are also methods to iterate over values/items ::
     it = db.itervalues()
     it.seek_to_first()
 
-    # prints ['v1', 'v2', 'v3']
+    # prints [b'v1', b'v2', b'v3']
     print list(it)
 
     it = db.iteritems()
     it.seek_to_first()
 
-    # prints [('key1', 'v1'), ('key2, 'v2'), ('key3', 'v3')]
+    # prints [(b'key1', b'v1'), (b'key2, b'v2'), (b'key3', b'v3')]
     print list(it)
 
 Reversed iteration ::
@@ -133,7 +132,7 @@ Reversed iteration ::
     it = db.iteritems()
     it.seek_to_last()
 
-    # prints [('key3', 'v3'), ('key2', 'v2'), ('key1', 'v1')]
+    # prints [(b'key3', b'v3'), (b'key2', b'v2'), (b'key1', b'v1')]
     print list(reversed(it))
 
 
@@ -142,23 +141,23 @@ Snapshots
 
 Snapshots are nice to get a consistent view on the database ::
 
-    self.db.put("a", "1")
+    self.db.put(b"a", b"1")
-    self.db.put("b", "2")
+    self.db.put(b"b", b"2")
 
     snapshot = self.db.snapshot()
-    self.db.put("a", "2")
+    self.db.put(b"a", b"2")
-    self.db.delete("b")
+    self.db.delete(b"b")
 
     it = self.db.iteritems()
     it.seek_to_first()
 
-    # prints {'a': '2'}
+    # prints {b'a': b'2'}
     print dict(it)
 
     it = self.db.iteritems(snapshot=snapshot)
     it.seek_to_first()
 
-    # prints {'a': '1', 'b': '2'}
+    # prints {b'a': b'1', b'b': b'2'}
     print dict(it)
 
 
@@ -172,11 +171,12 @@ The simple Associative merge ::
     class AssocCounter(rocksdb.interfaces.AssociativeMergeOperator):
         def merge(self, key, existing_value, value):
             if existing_value:
-                return (True, str(int(existing_value) + int(value)))
+                s = int(existing_value) + int(value)
+                return (True, str(s).encode('ascii'))
             return (True, value)
 
         def name(self):
-            return 'AssocCounter'
+            return b'AssocCounter'
 
 
     opts = rocksdb.Options()
@@ -184,8 +184,10 @@ The simple Associative merge ::
     opts.merge_operator = AssocCounter()
     db = rocksdb.DB('test.db', opts)
 
-    db.merge("a", "1")
+    db.merge(b"a", b"1")
-    db.merge("a", "1")
+    db.merge(b"a", b"1")
+
+    # prints b'2'
+    print db.get(b"a")
+
 
-    # prints '2'
-    print db.get("a")