Update the interfaces to be clear that, at the storage level, we're d…

…ealing with bytes.

src/ZODB/interfaces.py

@@ -432,6 +432,25 @@ def close():
         should also close all the Connections.
         """
 
+class IStorageTransactionMetaData(Interface):
+    """Provide storage transaction meta data.
+
+    Note that unlike transaction.interfaces.ITransaction, the ``user``
+    and ``description`` attributes are bytes, not text.
+    """
+    user = Attribute("Transaction user")
+    description = Attribute("Transaction Description")
+    extension = Attribute(
+        "A dictionary carrying a transaction's extended_info data")
+
+class IStorageTransactionMetaDataExtensionBytes(IStorageTransactionMetaData):
+    """Provide storage transaction meta data.
+
+    Note that unlike transaction.interfaces.ITransaction, the ``user``
+    and ``description`` attributes are bytes, not text.
+    """
+    extension_bytes = Attribute(
+        "A bytes carrying a transaction's serialized extended_info data")
 
 class IStorage(Interface):
     """A storage is responsible for storing and retrieving data of objects.
@@ -513,11 +532,11 @@ def history(oid, size=1):
             An alias for tid, which expected by older clients.
 
         user_name
-            The user identifier, if any (or an empty string) of the
+            The bytes user identifier, if any (or an empty string) of the
             user on whos behalf the revision was committed.
 
         description
-            The transaction description for the transaction that
+            The bytes transaction description for the transaction that
             committed the revision.
 
         size
@@ -652,8 +671,7 @@ def store(oid, serial, data, version, transaction):
             This must be an empty string. It exists for backward compatibility.
 
         transaction
-            A transaction object.  This should match the current
-            transaction for the storage, set by tpc_begin.
+            The object passed to tpc_begin
 
         Several different exceptions may be raised when an error occurs.
 
@@ -675,6 +693,8 @@ def store(oid, serial, data, version, transaction):
     def tpc_abort(transaction):
         """Abort the transaction.
 
+        The argument is the same object passed to tpc_begin.
+
         Any changes made by the transaction are discarded.
 
         This call is ignored is the storage is not participating in
@@ -685,6 +705,8 @@ def tpc_abort(transaction):
     def tpc_begin(transaction):
         """Begin the two-phase commit process.
 
+        The argument provides IStorageTransactionMetaDataExtensionBytes.
+
         If storage is already participating in a two-phase commit
         using the same transaction, a StorageTransactionError is raised.
 
@@ -703,6 +725,8 @@ def tpc_finish(transaction, func = lambda tid: None):
         a different transaction.  Failure of this method is extremely
         serious.
 
+        The first argument is the same object passed to tpc_begin.
+
         The second argument is a call-back function that must be
         called while the storage transaction lock is held.  It takes
         the new transaction id generated by the transaction.
@@ -714,6 +738,8 @@ def tpc_finish(transaction, func = lambda tid: None):
     def tpc_vote(transaction):
         """Provide a storage with an opportunity to veto a transaction
 
+        The argument is the same object passed to tpc_begin.
+
         This call raises a StorageTransactionError if the storage
         isn't participating in two-phase commit or if it is commiting
         a different transaction.
@@ -790,6 +816,8 @@ def tpc_begin(transaction, tid=None):
         using a different transaction, the call blocks until the
         current transaction ends (commits or aborts).
 
+        The first argument provides IStorageTransactionMetaDataExtensionBytes.
+
         If a transaction id is given, then the transaction will use
         the given id rather than generating a new id.  This is used
         when copying already committed transactions from another
@@ -841,22 +869,22 @@ class IStorageRecordInformation(Interface):
     """Provide information about a single storage record
     """
 
-    oid = Attribute("The object id")
-    tid = Attribute("The transaction id")
-    data = Attribute("The data record")
-    version = Attribute("The version id")
-    data_txn = Attribute("The previous transaction id")
-
+    oid = Attribute("The object id, bytes")
+    tid = Attribute("The transaction id, bytes")
+    data = Attribute("The data record, bytes")
+    data_txn = Attribute("The previous transaction id, bytes")
 
-class IStorageTransactionInformation(Interface):
+class IStorageTransactionInformation(IStorageTransactionMetaData):
     """Provide information about a storage transaction.
 
     Can be iterated over to retrieve the records modified in the transaction.
 
+    Note that this may contain a status field used by FileStorage to
+    support packing. At some point, this will go away when FileStorage
+    has a better pack algoritm.
     """
 
     tid = Attribute("Transaction id")
-    status = Attribute("Transaction Status") # XXX what are valid values?
     user = Attribute("Transaction user")
     description = Attribute("Transaction Description")
     extension = Attribute(
@@ -888,7 +916,6 @@ def iterator(start=None, stop=None):
 
         """
 
-
 class IStorageUndoable(IStorage):
     """A storage supporting transactional undo.
     """
@@ -923,10 +950,10 @@ def undoLog(first, last, filter=None):
             "time":  The time, as float seconds since the epoch, when
                      the transaction committed.
             "user_name":  The value of the `.user` attribute on that
-                          transaction.
+                          transaction, **bytes**.
             "description":  The value of the `.description` attribute on
-                            that transaction.
-            "id`"  A string uniquely identifying the transaction to the
+                            that transaction, **bytes**.
+            "id`"  A bytes uniquely identifying the transaction to the
                    storage.  If it's desired to undo this transaction,
                    this is the `transaction_id` to pass to `undo()`.