Add ciphertext_destination write preconditions to docstring.
PiperOrigin-RevId: 267572487
diff --git a/python/streaming_aead/streaming_aead.py b/python/streaming_aead/streaming_aead.py
index 5d5a074..42a51d6 100644
--- a/python/streaming_aead/streaming_aead.py
+++ b/python/streaming_aead/streaming_aead.py
@@ -35,6 +35,7 @@
@abc.abstractmethod
def new_encrypting_stream(self, ciphertext_destination: BinaryIO,
associated_data: bytes) -> BinaryIO:
+ # pyformat: disable
"""Get a new encrypting stream that writes to ciphertext_destination.
Args:
@@ -45,6 +46,17 @@
not included in the ciphertext and must be passed in as a parameter for
decryption.
+ The ciphertext_destination's write() method is expected to present one of
+ the following three behaviours in the case of a partial or failed write():
+ - return a non-negative integer number of bytes written
+ - return None (equivalent to returning 0)
+ - raise BlockingIOError with characters_written set correctly to a
+ non-negative integer (equivalent to returning that integer)
+ In the case of a full write, the number of bytes written should be returned.
+
+ The standard BufferedIOBase and RawIOBase base classes exhibit these
+ behaviours and are hence supported.
+
Returns:
An encrypting file object wrapper around 'ciphertext_destination', such
that any bytes written to the wrapper are AEAD-encrypted using
@@ -67,6 +79,7 @@
Raises:
tink.TinkError if the creation fails.
"""
+ # pyformat: enable
raise NotImplementedError()
@abc.abstractmethod
