From: david-sarah <david-sarah@jacaranda.org>
Date: Sat, 17 Jul 2010 05:46:47 +0000 (-0700)
Subject: fileutil: docstrings for non-obvious usage restrictions on methods of EncryptedTempor... 
X-Git-Url: https://git.rkrishnan.org/pf/content/en/seg?a=commitdiff_plain;h=752897450de27bf46572580bec4b3db25f0541b1;p=tahoe-lafs%2Ftahoe-lafs.git

fileutil: docstrings for non-obvious usage restrictions on methods of EncryptedTemporaryFile.
---

diff --git a/src/allmydata/util/fileutil.py b/src/allmydata/util/fileutil.py
index f671f7ea..cf0cb66a 100644
--- a/src/allmydata/util/fileutil.py
+++ b/src/allmydata/util/fileutil.py
@@ -144,17 +144,23 @@ class EncryptedTemporaryFile:
         return offset
 
     def read(self, size=-1):
+        """A read must not follow a write, or vice-versa, without an intervening seek."""
         index = self.file.tell()
         ciphertext = self.file.read(size)
         plaintext = self._crypt(index, ciphertext)
         return plaintext
 
     def write(self, plaintext):
+        """A read must not follow a write, or vice-versa, without an intervening seek.
+        If seeking and then writing causes a 'hole' in the file, the contents of the
+        hole are unspecified."""
         index = self.file.tell()
         ciphertext = self._crypt(index, plaintext)
         self.file.write(ciphertext)
 
     def truncate(self, newsize):
+        """Truncate or extend the file to 'newsize'. If it is extended, the contents after the
+        old end-of-file are unspecified. The file position after this operation is unspecified."""
         self.file.truncate(newsize)