azure-storage-blob 12.21.0__py3-none-any.whl → 12.21.0b1__py3-none-any.whl

azure/storage/blob/_download.py

@@ -3,13 +3,13 @@
 # Licensed under the MIT License. See License.txt in the project root for
 # license information.
 # --------------------------------------------------------------------------
-import codecs
+
 import sys
 import threading
 import time
 import warnings
-from io import BytesIO, StringIO
-from typing import Generic, IO, Iterator, Optional, overload, TypeVar, Union
+from io import BytesIO
+from typing import Generic, IO, Iterator, Optional, TypeVar
 
 from azure.core.exceptions import DecodeError, HttpResponseError, IncompleteReadError
 from azure.core.tracing.common import with_current_context
@@ -125,7 +125,7 @@ class _ChunkDownloader(object):  # pylint: disable=too-many-instance-attributes
 
     def process_chunk(self, chunk_start):
         chunk_start, chunk_end = self._calculate_range(chunk_start)
-        chunk_data, _ = self._download_chunk(chunk_start, chunk_end - 1)
+        chunk_data = self._download_chunk(chunk_start, chunk_end - 1)
         length = chunk_end - chunk_start
         if length > 0:
             self._write_to_stream(chunk_data, chunk_start)
@@ -186,8 +186,8 @@ class _ChunkDownloader(object):  # pylint: disable=too-many-instance-attributes
         # No need to download the empty chunk from server if there's no data in the chunk to be downloaded.
         # Do optimize and create empty chunk locally if condition is met.
         if self._do_optimize(download_range[0], download_range[1]):
-            content_length = download_range[1] - download_range[0] + 1
-            chunk_data = b"\x00" * content_length
+            data_size = download_range[1] - download_range[0] + 1
+            chunk_data = b"\x00" * data_size
         else:
             range_header, range_validation = validate_and_format_range_headers(
                 download_range[0],
@@ -218,14 +218,13 @@ class _ChunkDownloader(object):  # pylint: disable=too-many-instance-attributes
                     if retry_total <= 0:
                         raise HttpResponseError(error, error=error) from error
                     time.sleep(1)
-            content_length = response.content_length
 
             # This makes sure that if_match is set so that we can validate
             # that subsequent downloads are to an unmodified blob
             if self.request_options.get("modified_access_conditions"):
                 self.request_options["modified_access_conditions"].if_match = response.properties.etag
 
-        return chunk_data, content_length
+        return chunk_data
 
 
 class _ChunkIterator(object):
@@ -265,7 +264,7 @@ class _ChunkIterator(object):
 
         try:
             chunk = next(self._iter_chunks)
-            self._current_content += self._iter_downloader.yield_chunk(chunk)[0]
+            self._current_content += self._iter_downloader.yield_chunk(chunk)
         except StopIteration as e:
             self._complete = True
             if self._current_content:
@@ -329,27 +328,14 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
         self._encryption_options = encryption_options or {}
         self._progress_hook = kwargs.pop('progress_hook', None)
         self._request_options = kwargs
-        self._response = None
         self._location_mode = None
-        self._current_content = b''
-        self._file_size = 0
+        self._download_complete = False
+        self._current_content = None
+        self._file_size = None
         self._non_empty_ranges = None
+        self._response = None
         self._encryption_data = None
-
-        # The content download offset, after any processing (decryption), in bytes
-        self._download_offset = 0
-        # The raw download offset, before processing (decryption), in bytes
-        self._raw_download_offset = 0
-        # The offset the stream has been read to in bytes or chars depending on mode
-        self._read_offset = 0
-        # The offset into current_content that has been consumed in bytes or chars depending on mode
-        self._current_content_offset = 0
-
-        self._text_mode: Optional[bool] = None
-        self._decoder = None
-        # Whether the current content is the first chunk of download content or not
-        self._first_chunk = True
-        self._download_start = self._start_range or 0
+        self._offset = 0
 
         # The cls is passed in via download_cls to avoid conflicting arg name with Generic.__new__
         # but needs to be changed to cls in the request options.
@@ -361,14 +347,14 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
         # The service only provides transactional MD5s for chunks under 4MB.
         # If validate_content is on, get only self.MAX_CHUNK_GET_SIZE for the first
         # chunk so a transactional MD5 can be retrieved.
-        first_get_size = (
+        self._first_get_size = (
             self._config.max_single_get_size if not self._validate_content else self._config.max_chunk_get_size
         )
-        initial_request_start = self._download_start
-        if self._end_range is not None and self._end_range - initial_request_start < first_get_size:
+        initial_request_start = self._start_range if self._start_range is not None else 0
+        if self._end_range is not None and self._end_range - self._start_range < self._first_get_size:
             initial_request_end = self._end_range
         else:
-            initial_request_end = initial_request_start + first_get_size - 1
+            initial_request_end = initial_request_start + self._first_get_size - 1
 
         self._initial_range, self._initial_offset = process_range_and_offset(
             initial_request_start,
@@ -383,11 +369,12 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
         self.properties.name = self.name
         self.properties.container = self.container
 
-        # Set the content length to the download size instead of the size of the last range
+        # Set the content length to the download size instead of the size of
+        # the last range
         self.properties.size = self.size
-        self.properties.content_range = (f"bytes {self._download_start}-"
-                                         f"{self._end_range if self._end_range is not None else self._file_size - 1}/"
-                                         f"{self._file_size}")
+
+        # Overwrite the content range to the user requested range
+        self.properties.content_range = f"bytes {self._start_range}-{self._end_range}/{self._file_size}"
 
         # Overwrite the content MD5 as it is the MD5 for the last range instead
         # of the stored MD5
@@ -412,12 +399,6 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
         # Restore cls for download
         self._request_options['cls'] = download_cls
 
-    @property
-    def _download_complete(self):
-        if is_encryption_v2(self._encryption_data):
-            return self._download_offset >= self.size
-        return self._raw_download_offset >= self.size
-
     def _initial_request(self):
         range_header, range_validation = validate_and_format_range_headers(
             self._initial_range[0],
@@ -454,7 +435,7 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
 
                 if self._end_range is not None:
                     # Use the end range index unless it is over the end of the file
-                    self.size = min(self._file_size - self._start_range, self._end_range - self._start_range + 1)
+                    self.size = min(self._file_size, self._end_range - self._start_range + 1)
                 elif self._start_range is not None:
                     self.size = self._file_size - self._start_range
                 else:
@@ -497,8 +478,6 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
                 if retry_total <= 0:
                     raise HttpResponseError(error, error=error) from error
                 time.sleep(1)
-        self._download_offset += len(self._current_content)
-        self._raw_download_offset += response.content_length
 
         # get page ranges to optimize downloading sparse page blob
         if response.properties.blob_type == 'PageBlob':
@@ -512,19 +491,33 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
             except HttpResponseError:
                 pass
 
+        # If the file is small, the download is complete at this point.
+        # If file size is large, download the rest of the file in chunks.
+        # For encryption V2, calculate based on size of decrypted content, not download size.
+        if is_encryption_v2(self._encryption_data):
+            self._download_complete = len(self._current_content) >= self.size
+        else:
+            self._download_complete = response.properties.size >= self.size
+
         if not self._download_complete and self._request_options.get("modified_access_conditions"):
             self._request_options["modified_access_conditions"].if_match = response.properties.etag
 
         return response
 
+    def _get_downloader_start_with_offset(self):
+        # Start where the initial request download ended
+        start = self._initial_range[1] + 1
+        # For encryption V2 only, adjust start to the end of the fetched data rather than download size
+        if self._encryption_options.get("key") is not None or self._encryption_options.get("resolver") is not None:
+            start = (self._start_range or 0) + len(self._current_content)
+
+        # Adjust the start based on any data read past the current content
+        start += (self._offset - len(self._current_content))
+        return start
+
     def chunks(self):
         # type: () -> Iterator[bytes]
-        """
-        Iterate over chunks in the download stream. Note, the iterator returned will
-        iterate over the entire download content, regardless of any data that was
-        previously read.
-
-        NOTE: If the stream has been partially read, some data may be re-downloaded by the iterator.
+        """Iterate over chunks in the download stream.
 
         :returns: An iterator of the chunks in the download stream.
         :rtype: Iterator[bytes]
@@ -538,124 +531,81 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
                 :dedent: 12
                 :caption: Download a blob using chunks().
         """
-        if self._text_mode:
-            raise ValueError("Stream has been partially read in text mode. chunks is not supported in text mode.")
-        if self._encoding:
-            warnings.warn("Encoding is ignored with chunks as only bytes are supported.")
-
-        iter_downloader = None
-        # If we still have the first chunk buffered, use it. Otherwise, download all content again
-        if not self._first_chunk or not self._download_complete:
-            if self._first_chunk:
-                start = self._download_start + len(self._current_content)
-                current_progress = len(self._current_content)
-            else:
-                start = self._download_start
-                current_progress = 0
+        if self.size == 0 or self._download_complete:
+            iter_downloader = None
+        else:
+            data_end = self._file_size
+            if self._end_range is not None:
+                # Use the end range index unless it is over the end of the file
+                data_end = min(self._file_size, self._end_range + 1)
 
-            end = self._download_start + self.size
+            data_start = self._initial_range[1] + 1  # Start where the first download ended
+            # For encryption, adjust start to the end of the fetched data rather than download size
+            if self._encryption_options.get("key") is not None or self._encryption_options.get("resolver") is not None:
+                data_start = (self._start_range or 0) + len(self._current_content)
 
             iter_downloader = _ChunkDownloader(
                 client=self._clients.blob,
                 non_empty_ranges=self._non_empty_ranges,
                 total_size=self.size,
                 chunk_size=self._config.max_chunk_get_size,
-                current_progress=current_progress,
-                start_range=start,
-                end_range=end,
+                current_progress=self._first_get_size,
+                start_range=data_start,
+                end_range=data_end,
+                stream=None,
+                parallel=False,
                 validate_content=self._validate_content,
                 encryption_options=self._encryption_options,
                 encryption_data=self._encryption_data,
                 use_location=self._location_mode,
                 **self._request_options
             )
-
-        initial_content = self._current_content if self._first_chunk else b''
         return _ChunkIterator(
             size=self.size,
-            content=initial_content,
+            content=self._current_content,
             downloader=iter_downloader,
             chunk_size=self._config.max_chunk_get_size)
 
-    @overload
-    def read(self, size: int = -1) -> T:
-        ...
-
-    @overload
-    def read(self, *, chars: Optional[int] = None) -> T:
-        ...
-
-    # pylint: disable-next=too-many-statements,too-many-branches
-    def read(self, size: int = -1, *, chars: Optional[int] = None) -> T:
+    def read(self, size: Optional[int] = -1) -> T:
         """
-        Read the specified bytes or chars from the stream. If `encoding`
-        was specified on `download_blob`, it is recommended to use the
-        chars parameter to read a specific number of chars to avoid decoding
-        errors. If size/chars is unspecified or negative all bytes will be read.
+        Read up to size bytes from the stream and return them. If size
+        is unspecified or is -1, all bytes will be read.
 
-        :param int size:
+        :param Optional[int] size:
             The number of bytes to download from the stream. Leave unspecified
-            or set negative to download all bytes.
-        :keyword Optional[int] chars:
-            The number of chars to download from the stream. Leave unspecified
-            or set negative to download all chars. Note, this can only be used
-            when encoding is specified on `download_blob`.
+            or set to -1 to download all bytes.
         :returns:
             The requested data as bytes or a string if encoding was specified. If
             the return value is empty, there is no more data to read.
         :rtype: T
         """
-        if size > -1 and self._encoding:
-            warnings.warn(
-                "Size parameter specified with text encoding enabled. It is recommended to use chars "
-                "to read a specific number of characters instead."
-            )
-        if size > -1 and chars is not None:
-            raise ValueError("Cannot specify both size and chars.")
-        if not self._encoding and chars is not None:
-            raise ValueError("Must specify encoding to read chars.")
-        if self._text_mode and size > -1:
-            raise ValueError("Stream has been partially read in text mode. Please use chars.")
-        if self._text_mode is False and chars is not None:
-            raise ValueError("Stream has been partially read in bytes mode. Please use size.")
-
+        if size == -1:
+            return self.readall()
         # Empty blob or already read to the end
-        if (size == 0 or chars == 0 or
-                (self._download_complete and self._current_content_offset >= len(self._current_content))):
+        if size == 0 or self._offset >= self.size:
             return b'' if not self._encoding else ''
 
-        if not self._text_mode and chars is not None:
-            self._text_mode = True
-            self._decoder = codecs.getincrementaldecoder(self._encoding)('strict')
-            self._current_content = self._decoder.decode(self._current_content, final=self._download_complete)
-        elif self._text_mode is None:
-            self._text_mode = False
-
-        output_stream: Union[BytesIO, StringIO]
-        if self._text_mode:
-            output_stream = StringIO()
-            size = chars if chars else sys.maxsize
-        else:
-            output_stream = BytesIO()
-            size = size if size > 0 else sys.maxsize
-        readall = size == sys.maxsize
-        count = 0
-
-        # Start by reading from current_content
-        start = self._current_content_offset
-        length = min(len(self._current_content) - self._current_content_offset, size - count)
-        read = output_stream.write(self._current_content[start:start + length])
-
-        count += read
-        self._current_content_offset += read
-        self._read_offset += read
-        self._check_and_report_progress()
-
-        remaining = size - count
-        if remaining > 0 and not self._download_complete:
-            # Create a downloader than can download the rest of the file
-            start = self._download_start + self._download_offset
-            end = self._download_start + self.size
+        stream = BytesIO()
+        remaining_size = size
+
+        # Start by reading from current_content if there is data left
+        if self._offset < len(self._current_content):
+            start = self._offset
+            length = min(remaining_size, len(self._current_content) - self._offset)
+            read = stream.write(self._current_content[start:start + length])
+
+            remaining_size -= read
+            self._offset += read
+            if self._progress_hook:
+                self._progress_hook(self._offset, self.size)
+
+        if remaining_size > 0:
+            start_range = self._get_downloader_start_with_offset()
+
+            # End is the min between the remaining size, the file size, and the end of the specified range
+            end_range = min(start_range + remaining_size, self._file_size)
+            if self._end_range is not None:
+                end_range = min(end_range, self._end_range + 1)
 
             parallel = self._max_concurrency > 1
             downloader = _ChunkDownloader(
@@ -663,10 +613,10 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
                 non_empty_ranges=self._non_empty_ranges,
                 total_size=self.size,
                 chunk_size=self._config.max_chunk_get_size,
-                current_progress=self._read_offset,
-                start_range=start,
-                end_range=end,
-                stream=output_stream,
+                current_progress=self._offset,
+                start_range=start_range,
+                end_range=end_range,
+                stream=stream,
                 parallel=parallel,
                 validate_content=self._validate_content,
                 encryption_options=self._encryption_options,
@@ -675,57 +625,23 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
                 progress_hook=self._progress_hook,
                 **self._request_options
             )
-            self._first_chunk = False
-
-            # When reading all data, have the downloader read everything into the stream.
-            # Else, read one chunk at a time (using the downloader as an iterator) until
-            # the requested size is reached.
-            chunks_iter = downloader.get_chunk_offsets()
-            if readall and not self._text_mode:
-                # Only do parallel if there is more than one chunk left to download
-                if parallel and (self.size - self._download_offset) > self._config.max_chunk_get_size:
-                    import concurrent.futures
-                    with concurrent.futures.ThreadPoolExecutor(self._max_concurrency) as executor:
-                        list(executor.map(
+
+            if parallel and remaining_size > self._config.max_chunk_get_size:
+                import concurrent.futures
+                with concurrent.futures.ThreadPoolExecutor(self._max_concurrency) as executor:
+                    list(executor.map(
                             with_current_context(downloader.process_chunk),
                             downloader.get_chunk_offsets()
                         ))
-                else:
-                    for chunk in chunks_iter:
-                        downloader.process_chunk(chunk)
-
-                self._complete_read()
-
             else:
-                while (chunk := next(chunks_iter, None)) is not None and remaining > 0:
-                    chunk_data, content_length = downloader.yield_chunk(chunk)
-                    self._download_offset += len(chunk_data)
-                    self._raw_download_offset += content_length
-                    self._current_content = self._decoder.decode(
-                        chunk_data, final=self._download_complete) if self._text_mode else chunk_data
-
-                    if remaining < len(self._current_content):
-                        read = output_stream.write(self._current_content[:remaining])
-                    else:
-                        read = output_stream.write(self._current_content)
-
-                    self._current_content_offset = read
-                    self._read_offset += read
-                    remaining -= read
-                    self._check_and_report_progress()
-
-        data = output_stream.getvalue()
-        if not self._text_mode and self._encoding:
-            try:
-                # This is technically incorrect to do, but we have it for backwards compatibility.
-                data = data.decode(self._encoding)
-            except UnicodeDecodeError:
-                warnings.warn(
-                    "Encountered a decoding error while decoding blob data from a partial read. "
-                    "Try using the `chars` keyword instead to read in text mode."
-                )
-                raise
+                for chunk in downloader.get_chunk_offsets():
+                    downloader.process_chunk(chunk)
+
+            self._offset += remaining_size
 
+        data = stream.getvalue()
+        if self._encoding:
+            return data.decode(self._encoding)
         return data
 
     def readall(self) -> T:
@@ -736,7 +652,53 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
         :returns: The requested data as bytes or a string if encoding was specified.
         :rtype: T
         """
-        return self.read()
+        stream = BytesIO()
+        self.readinto(stream)
+        data = stream.getvalue()
+        if self._encoding:
+            return data.decode(self._encoding)
+        return data
+
+    def content_as_bytes(self, max_concurrency=1):
+        """DEPRECATED: Download the contents of this file.
+
+        This operation is blocking until all data is downloaded.
+
+        This method is deprecated, use func:`readall` instead.
+
+        :param int max_concurrency:
+            The number of parallel connections with which to download.
+        :returns: The contents of the file as bytes.
+        :rtype: bytes
+        """
+        warnings.warn(
+            "content_as_bytes is deprecated, use readall instead",
+            DeprecationWarning
+        )
+        self._max_concurrency = max_concurrency
+        return self.readall()
+
+    def content_as_text(self, max_concurrency=1, encoding="UTF-8"):
+        """DEPRECATED: Download the contents of this blob, and decode as text.
+
+        This operation is blocking until all data is downloaded.
+
+        This method is deprecated, use func:`readall` instead.
+
+        :param int max_concurrency:
+            The number of parallel connections with which to download.
+        :param str encoding:
+            Test encoding to decode the downloaded bytes. Default is UTF-8.
+        :returns: The content of the file as a str.
+        :rtype: str
+        """
+        warnings.warn(
+            "content_as_text is deprecated, use readall instead",
+            DeprecationWarning
+        )
+        self._max_concurrency = max_concurrency
+        self._encoding = encoding
+        return self.readall()
 
     def readinto(self, stream: IO[bytes]) -> int:
         """Download the contents of this file to a stream.
@@ -748,11 +710,6 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
         :returns: The number of bytes read.
         :rtype: int
         """
-        if self._text_mode:
-            raise ValueError("Stream has been partially read in text mode. readinto is not supported in text mode.")
-        if self._encoding:
-            warnings.warn("Encoding is ignored with readinto as only byte streams are supported.")
-
         # The stream must be seekable if parallel download is required
         parallel = self._max_concurrency > 1
         if parallel:
@@ -766,34 +723,35 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
                 raise ValueError(error_message) from exc
 
         # If some data has been streamed using `read`, only stream the remaining data
-        remaining_size = self.size - self._read_offset
+        remaining_size = self.size - self._offset
         # Already read to the end
         if remaining_size <= 0:
             return 0
 
-        # Write the current content to the user stream
-        current_remaining = len(self._current_content) - self._current_content_offset
-        start = self._current_content_offset
-        count = stream.write(self._current_content[start:start + current_remaining])
+        # Write the content to the user stream if there is data left
+        if self._offset < len(self._current_content):
+            content = self._current_content[self._offset:]
+            stream.write(content)
+            self._offset += len(content)
+            if self._progress_hook:
+                self._progress_hook(len(content), self.size)
 
-        self._current_content_offset += count
-        self._read_offset += count
-        if self._progress_hook:
-            self._progress_hook(self._read_offset, self.size)
-
-        # If all the data was already downloaded/buffered
         if self._download_complete:
             return remaining_size
 
-        data_start = self._download_start + self._read_offset
-        data_end = self._download_start + self.size
+        data_end = self._file_size
+        if self._end_range is not None:
+            # Use the length unless it is over the end of the file
+            data_end = min(self._file_size, self._end_range + 1)
+
+        data_start = self._get_downloader_start_with_offset()
 
         downloader = _ChunkDownloader(
             client=self._clients.blob,
             non_empty_ranges=self._non_empty_ranges,
             total_size=self.size,
             chunk_size=self._config.max_chunk_get_size,
-            current_progress=self._read_offset,
+            current_progress=self._offset,
             start_range=data_start,
             end_range=data_end,
             stream=stream,
@@ -816,72 +774,8 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
             for chunk in downloader.get_chunk_offsets():
                 downloader.process_chunk(chunk)
 
-        self._complete_read()
         return remaining_size
 
-    def _complete_read(self):
-        """Adjusts all offsets to the end of the download."""
-        self._download_offset = self.size
-        self._raw_download_offset = self.size
-        self._read_offset = self.size
-        self._current_content_offset = len(self._current_content)
-
-    def _check_and_report_progress(self):
-        """Reports progress if necessary."""
-        # Only report progress at the end of each chunk and use download_offset to always report
-        # progress in terms of (approximate) byte count.
-        if self._progress_hook and self._current_content_offset == len(self._current_content):
-            self._progress_hook(self._download_offset, self.size)
-
-    def content_as_bytes(self, max_concurrency=1):
-        """DEPRECATED: Download the contents of this file.
-
-        This operation is blocking until all data is downloaded.
-
-        This method is deprecated, use func:`readall` instead.
-
-        :param int max_concurrency:
-            The number of parallel connections with which to download.
-        :returns: The contents of the file as bytes.
-        :rtype: bytes
-        """
-        warnings.warn(
-            "content_as_bytes is deprecated, use readall instead",
-            DeprecationWarning
-        )
-        if self._text_mode:
-            raise ValueError("Stream has been partially read in text mode. "
-                             "content_as_bytes is not supported in text mode.")
-
-        self._max_concurrency = max_concurrency
-        return self.readall()
-
-    def content_as_text(self, max_concurrency=1, encoding="UTF-8"):
-        """DEPRECATED: Download the contents of this blob, and decode as text.
-
-        This operation is blocking until all data is downloaded.
-
-        This method is deprecated, use func:`readall` instead.
-
-        :param int max_concurrency:
-            The number of parallel connections with which to download.
-        :param str encoding:
-            Test encoding to decode the downloaded bytes. Default is UTF-8.
-        :returns: The content of the file as a str.
-        :rtype: str
-        """
-        warnings.warn(
-            "content_as_text is deprecated, use readall instead",
-            DeprecationWarning
-        )
-        if self._text_mode:
-            raise ValueError("Stream has been partially read in text mode. "
-                             "content_as_text is not supported in text mode.")
-
-        self._max_concurrency = max_concurrency
-        self._encoding = encoding
-        return self.readall()
-
     def download_to_stream(self, stream, max_concurrency=1):
         """DEPRECATED: Download the contents of this blob to a stream.
 
@@ -900,10 +794,6 @@ class StorageStreamDownloader(Generic[T]):  # pylint: disable=too-many-instance-
             "download_to_stream is deprecated, use readinto instead",
             DeprecationWarning
         )
-        if self._text_mode:
-            raise ValueError("Stream has been partially read in text mode. "
-                             "download_to_stream is not supported in text mode.")
-
         self._max_concurrency = max_concurrency
         self.readinto(stream)
         return self.properties