megfile 3.1.6.post1__py3-none-any.whl → 4.0.0.post1__py3-none-any.whl

megfile/lib/base_prefetch_reader.py

@@ -9,16 +9,14 @@ from statistics import mean
 from typing import Optional
 
 from megfile.config import (
-    BACKOFF_FACTOR,
-    BACKOFF_INITIAL,
-    DEFAULT_BLOCK_CAPACITY,
-    DEFAULT_BLOCK_SIZE,
     DEFAULT_MAX_RETRY_TIMES,
     GLOBAL_MAX_WORKERS,
     NEWLINE,
+    READER_BLOCK_SIZE,
+    READER_MAX_BUFFER_SIZE,
 )
 from megfile.interfaces import Readable, Seekable
-from megfile.utils import ProcessLocal, get_human_size, process_local
+from megfile.utils import ProcessLocal, process_local
 
 _logger = get_logger(__name__)
 
@@ -31,35 +29,31 @@ class SeekRecord:
 
 
 class BasePrefetchReader(Readable[bytes], Seekable, ABC):
-    """
-    Reader to fast read the remote file content.
-    This will divide the file content into equal parts of block_size size,
-    and will use LRU to cache at most block_capacity blocks in memory.
-    open(), seek() and read() will trigger prefetch read.
-    The prefetch will cached block_forward blocks of data from offset position
-    (the position after reading if the called function is read).
-    """
-
     def __init__(
         self,
         *,
-        block_size: int = DEFAULT_BLOCK_SIZE,
-        block_capacity: int = DEFAULT_BLOCK_CAPACITY,
+        block_size: int = READER_BLOCK_SIZE,
+        max_buffer_size: int = READER_MAX_BUFFER_SIZE,
         block_forward: Optional[int] = None,
         max_retries: int = DEFAULT_MAX_RETRY_TIMES,
         max_workers: Optional[int] = None,
         **kwargs,
     ):
-        self._is_auto_scaling = block_forward is None
+        if max_buffer_size == 0:
+            block_capacity = block_forward = 0
+        else:
+            block_capacity = max(max_buffer_size // block_size, 1)
+
+        self._is_auto_scaling = False
         if block_forward is None:
-            block_forward = max(block_capacity - 1, 1)
-
-        if block_capacity <= block_forward:
-            # TODO: replace AssertionError with ValueError in 4.0.0
-            raise AssertionError(
-                "block_capacity should greater than block_forward, "
-                "got: block_capacity=%s, block_forward=%s"
-                % (block_capacity, block_forward)
+            block_forward = max(block_capacity - 1, 0)
+            self._is_auto_scaling = block_forward > 0
+
+        if 0 < block_capacity <= block_forward:
+            raise ValueError(
+                "max_buffer_size should greater than block_forward * block_size, "
+                "got: max_buffer_size=%s, block_size=%s, block_forward=%s"
+                % (max_buffer_size, block_size, block_forward)
             )
 
         # user maybe put block_size with 'numpy.uint64' type
@@ -77,8 +71,7 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
         self._content_size = self._get_content_size()
         self._block_stop = ceil(self._content_size / block_size)
 
-        self.__offset = 0
-        self._backoff_size = BACKOFF_INITIAL
+        self._offset = 0
         self._cached_buffer = None
         self._block_index = None  # Current block index
         self._seek_history = []
@@ -102,7 +95,7 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
         pass
 
     @property
-    def _futures(self):
+    def _futures(self) -> "LRUCacheFutureManager":
         return self._process_local("futures", self._get_futures)
 
     def _get_futures(self):
@@ -120,21 +113,6 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
     def tell(self) -> int:
         return self._offset
 
-    @property
-    def _offset(self) -> int:
-        return self.__offset
-
-    @_offset.setter
-    def _offset(self, value: int):
-        if value > self._backoff_size:
-            _logger.debug(
-                "reading file: %r, current offset / total size: %s / %s"
-                % (self.name, get_human_size(value), get_human_size(self._content_size))
-            )
-        while value > self._backoff_size:
-            self._backoff_size *= BACKOFF_FACTOR
-        self.__offset = value
-
     def seek(self, offset: int, whence: int = os.SEEK_SET) -> int:
         """Change stream position.
 
@@ -176,9 +154,6 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
         if self.closed:
             raise IOError("file already closed: %r" % self.name)
 
-        if len(self._seek_history) > 0:
-            self._seek_history[-1].read_count += 1
-
         if self._offset >= self._content_size:
             return b""
 
@@ -187,31 +162,9 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
         else:
             size = min(size, self._content_size - self._offset)
 
-        if self._block_forward == 1:
-            block_index = self._offset // self._block_size
-            if len(self._seek_history) > 0:
-                mean_read_count = mean(item.read_count for item in self._seek_history)
-            else:
-                mean_read_count = 0
-            if block_index not in self._futures and mean_read_count < 3:
-                # No using LRP will be better if read() are always called less than 3
-                # times after seek()
-                return self._read(size)
-
-        data = self._buffer.read(size)
-        if len(data) == size:
-            self._offset += len(data)
-            return data
-
-        buffer = BytesIO()
-        buffer.write(data)
-        while buffer.tell() < size:
-            remain_size = size - buffer.tell()
-            data = self._next_buffer.read(remain_size)
-            buffer.write(data)
-
-        self._offset += buffer.tell()
-        return buffer.getvalue()
+        buffer = bytearray(size)
+        self.readinto(buffer)
+        return bytes(buffer)
 
     def readline(self, size: Optional[int] = None) -> bytes:
         """Next line from the file, as a bytes object.
@@ -270,12 +223,31 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
         if self.closed:
             raise IOError("file already closed: %r" % self.name)
 
+        if len(self._seek_history) > 0:
+            self._seek_history[-1].read_count += 1
+
         if self._offset >= self._content_size:
             return 0
 
         size = len(buffer)
         size = min(size, self._content_size - self._offset)
 
+        if self._block_capacity == 0:
+            buffer[:size] = self._read(size)
+            return size
+
+        if self._block_forward == 0:
+            block_index = self._offset // self._block_size
+            if len(self._seek_history) > 0:
+                mean_read_count = mean(item.read_count for item in self._seek_history)
+            else:
+                mean_read_count = 0
+            if block_index not in self._futures and mean_read_count < 3:
+                # No using LRP will be better if read() are always called less than 3
+                # times after seek()
+                buffer[:size] = self._read(size)
+                return size
+
         data = self._buffer.read(size)
         buffer[: len(data)] = data
         if len(data) == size:
@@ -306,13 +278,22 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
 
     @property
     def _buffer(self) -> BytesIO:
+        if self._block_capacity == 0:
+            buffer = self._fetch_buffer(index=self._block_index)
+            buffer.seek(self._cached_offset)
+            self._cached_offset = None
+            return buffer
+
         if self._cached_offset is not None:
-            start = self._block_index
-            stop = min(start + self._block_forward, self._block_stop)
+            if self._block_forward > 0:  # pyre-ignore[58]
+                start = self._block_index
+                stop = min(start + self._block_forward, self._block_stop)
 
-            # reversed(range(start, stop))
-            for index in range(stop - 1, start - 1, -1):
-                self._submit_future(index)
+                # reversed(range(start, stop))
+                for index in range(stop, start - 1, -1):
+                    self._submit_future(index)
+            else:
+                self._submit_future(self._block_index)
             self._cleanup_futures()
 
             self._cached_buffer = self._fetch_future_result(self._block_index)
@@ -335,7 +316,7 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
     def _seek_buffer(self, index: int, offset: int = 0):
         # The corresponding block is probably not downloaded when seek to a new position
         # So record the offset first, set it when it is accessed
-        if self._is_auto_scaling:  # When user doesn't define forward
+        if self._is_auto_scaling:
             history = []
             for item in self._seek_history:
                 if item.seek_count > self._block_capacity * 2:
@@ -349,8 +330,11 @@ class BasePrefetchReader(Readable[bytes], Seekable, ABC):
             history.append(SeekRecord(index))
             self._seek_history = history
             self._block_forward = max(
-                (self._block_capacity - 1) // len(self._seek_history), 1
+                self._block_capacity // len(self._seek_history), 0
             )
+            if self._block_forward == 0:
+                self._is_auto_scaling = False
+                self._seek_history = []
 
         self._cached_offset = offset
         self._block_index = index

megfile/lib/combine_reader.py

@@ -118,3 +118,8 @@ class CombineReader(Readable, Seekable):
     def _close(self):
         for file_object in self._file_objects:
             file_object.close()
+
+    def __del__(self) -> None:
+        # CombineReader not close files in __del__
+        # user should use `close()` or use `with`
+        pass

megfile/lib/glob.py

@@ -72,8 +72,7 @@ def iglob(
     if recursive and _isrecursive(pathname):
         s = next(it)  # skip empty string
         if s:
-            # TODO: replace AssertionError with OSError in 4.0.0
-            raise AssertionError("iglob with recursive=True error")
+            raise OSError("iglob with recursive=True error")
     return it
 
 
@@ -87,8 +86,7 @@ def _iglob(pathname: str, recursive: bool, dironly: bool, fs: FSFunc) -> Iterato
         dirname = "://".join([protocol, dirname])
     if not has_magic(pathname):
         if dironly:
-            # TODO: replace AssertionError with OSError in 4.0.0
-            raise AssertionError("can't use dironly with non-magic patterns in _iglob")
+            raise OSError("can't use dironly with non-magic patterns in _iglob")
         if basename:
             if fs.exists(pathname):
                 yield pathname
@@ -150,8 +148,7 @@ def _glob0(dirname: str, basename: str, dironly: bool, fs: FSFunc) -> List[str]:
 # directory.
 def _glob2(dirname: str, pattern: str, dironly: bool, fs: FSFunc) -> Iterator[str]:
     if not _isrecursive(pattern):
-        # TODO: replace AssertionError with OSError in 4.0.0
-        raise AssertionError("error call '_glob2' with non-glob pattern")
+        raise OSError("error call '_glob2' with non-glob pattern")
     yield pattern[:0]
     yield from _rlistdir(dirname, dironly, fs)
 

megfile/lib/hdfs_prefetch_reader.py

@@ -2,9 +2,9 @@ from io import BytesIO
 from typing import Optional
 
 from megfile.config import (
-    DEFAULT_BLOCK_CAPACITY,
-    DEFAULT_BLOCK_SIZE,
     HDFS_MAX_RETRY_TIMES,
+    READER_BLOCK_SIZE,
+    READER_MAX_BUFFER_SIZE,
 )
 from megfile.errors import raise_hdfs_error
 from megfile.lib.base_prefetch_reader import BasePrefetchReader
@@ -13,8 +13,8 @@ from megfile.lib.base_prefetch_reader import BasePrefetchReader
 class HdfsPrefetchReader(BasePrefetchReader):
     """
     Reader to fast read the hdfs content. This will divide the file content into equal
-    parts of block_size size, and will use LRU to cache at most block_capacity blocks
-    in memory.
+    parts of block_size size, and will use LRU to cache at most blocks in
+    max_buffer_size memory.
 
     open(), seek() and read() will trigger prefetch read. The prefetch will cached
     block_forward blocks of data from offset position (the position after reading
@@ -26,8 +26,8 @@ class HdfsPrefetchReader(BasePrefetchReader):
         hdfs_path: str,
         *,
         client,
-        block_size: int = DEFAULT_BLOCK_SIZE,
-        block_capacity: int = DEFAULT_BLOCK_CAPACITY,
+        block_size: int = READER_BLOCK_SIZE,
+        max_buffer_size: int = READER_MAX_BUFFER_SIZE,
         block_forward: Optional[int] = None,
         max_retries: int = HDFS_MAX_RETRY_TIMES,
         max_workers: Optional[int] = None,
@@ -39,7 +39,7 @@ class HdfsPrefetchReader(BasePrefetchReader):
 
         super().__init__(
             block_size=block_size,
-            block_capacity=block_capacity,
+            max_buffer_size=max_buffer_size,
             block_forward=block_forward,
             max_retries=max_retries,
             max_workers=max_workers,

megfile/lib/http_prefetch_reader.py

@@ -4,9 +4,9 @@ from typing import Optional
 import requests
 
 from megfile.config import (
-    DEFAULT_BLOCK_CAPACITY,
-    DEFAULT_BLOCK_SIZE,
     HTTP_MAX_RETRY_TIMES,
+    READER_BLOCK_SIZE,
+    READER_MAX_BUFFER_SIZE,
 )
 from megfile.errors import (
     HttpBodyIncompleteError,
@@ -26,7 +26,7 @@ class HttpPrefetchReader(BasePrefetchReader):
     Reader to fast read the http content, service must support Accept-Ranges.
 
     This will divide the file content into equal parts of block_size size, and will use
-    LRU to cache at most block_capacity blocks in memory.
+    LRU to cache at most blocks in max_buffer_size memory.
 
     open(), seek() and read() will trigger prefetch read.
 
@@ -39,8 +39,8 @@ class HttpPrefetchReader(BasePrefetchReader):
         url: PathLike,
         *,
         content_size: Optional[int] = None,
-        block_size: int = DEFAULT_BLOCK_SIZE,
-        block_capacity: int = DEFAULT_BLOCK_CAPACITY,
+        block_size: int = READER_BLOCK_SIZE,
+        max_buffer_size: int = READER_MAX_BUFFER_SIZE,
         block_forward: Optional[int] = None,
         max_retries: int = HTTP_MAX_RETRY_TIMES,
         max_workers: Optional[int] = None,
@@ -50,7 +50,7 @@ class HttpPrefetchReader(BasePrefetchReader):
 
         super().__init__(
             block_size=block_size,
-            block_capacity=block_capacity,
+            max_buffer_size=max_buffer_size,
             block_forward=block_forward,
             max_retries=max_retries,
             max_workers=max_workers,

megfile/lib/s3_buffered_writer.py

@@ -1,3 +1,4 @@
+import os
 from collections import OrderedDict
 from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
 from io import BytesIO
@@ -6,16 +7,14 @@ from threading import Lock
 from typing import NamedTuple, Optional
 
 from megfile.config import (
-    BACKOFF_FACTOR,
-    BACKOFF_INITIAL,
-    DEFAULT_MAX_BLOCK_SIZE,
-    DEFAULT_MAX_BUFFER_SIZE,
-    DEFAULT_MIN_BLOCK_SIZE,
+    DEFAULT_WRITER_BLOCK_AUTOSCALE,
     GLOBAL_MAX_WORKERS,
+    WRITER_BLOCK_SIZE,
+    WRITER_MAX_BUFFER_SIZE,
 )
 from megfile.errors import raise_s3_error
 from megfile.interfaces import Writable
-from megfile.utils import get_human_size, process_local
+from megfile.utils import process_local
 
 _logger = get_logger(__name__)
 """
@@ -39,15 +38,19 @@ class PartResult(_PartResult):
 
 
 class S3BufferedWriter(Writable[bytes]):
+    # Multi-upload part size must be between 5 MiB and 5 GiB.
+    # There is no minimum size limit on the last part of your multipart upload.
+    MIN_BLOCK_SIZE = 8 * 2**20
+
     def __init__(
         self,
         bucket: str,
         key: str,
         *,
         s3_client,
-        block_size: int = DEFAULT_MIN_BLOCK_SIZE,
-        max_block_size: int = DEFAULT_MAX_BLOCK_SIZE,
-        max_buffer_size: int = DEFAULT_MAX_BUFFER_SIZE,
+        block_size: int = WRITER_BLOCK_SIZE,
+        block_autoscale: bool = DEFAULT_WRITER_BLOCK_AUTOSCALE,
+        max_buffer_size: int = WRITER_MAX_BUFFER_SIZE,
         max_workers: Optional[int] = None,
         profile_name: Optional[str] = None,
     ):
@@ -57,17 +60,17 @@ class S3BufferedWriter(Writable[bytes]):
         self._profile_name = profile_name
 
         # user maybe put block_size with 'numpy.uint64' type
-        self._block_size = int(block_size)
+        self._base_block_size = int(block_size)
+        self._block_autoscale = block_autoscale
 
-        self._max_block_size = max_block_size
         self._max_buffer_size = max_buffer_size
         self._total_buffer_size = 0
         self._offset = 0
-        self.__content_size = 0
-        self._backoff_size = BACKOFF_INITIAL
+        self._content_size = 0
         self._buffer = BytesIO()
 
-        self._futures = OrderedDict()
+        self._futures_result = OrderedDict()
+        self._uploading_futures = set()
         self._is_global_executor = False
         if max_workers is None:
             self._executor = process_local(
@@ -101,53 +104,42 @@ class S3BufferedWriter(Writable[bytes]):
         return self._offset
 
     @property
-    def _content_size(self) -> int:
-        return self.__content_size
-
-    @_content_size.setter
-    def _content_size(self, value: int):
-        if value > self._backoff_size:
-            _logger.debug(
-                "writing file: %r, current size: %s"
-                % (self.name, get_human_size(value))
-            )
-        while value > self._backoff_size:
-            self._backoff_size *= BACKOFF_FACTOR
-        self.__content_size = value
+    def _block_size(self) -> int:
+        if self._block_autoscale:
+            if self._part_number < 10:
+                return self._base_block_size
+            elif self._part_number < 100:
+                return min(self._base_block_size * 2, self._max_buffer_size)
+            elif self._part_number < 1000:
+                return min(self._base_block_size * 4, self._max_buffer_size)
+            elif self._part_number < 10000:
+                return min(self._base_block_size * 8, self._max_buffer_size)
+            return min(self._base_block_size * 16, self._max_buffer_size)  # unreachable
+        return self._base_block_size
 
     @property
     def _is_multipart(self) -> bool:
-        return len(self._futures) > 0
+        return len(self._futures_result) > 0 or len(self._uploading_futures) > 0
 
     @property
     def _upload_id(self) -> str:
-        with self.__upload_id_lock:
-            if self.__upload_id is None:
-                with raise_s3_error(self.name):
-                    self.__upload_id = self._client.create_multipart_upload(
-                        Bucket=self._bucket, Key=self._key
-                    )["UploadId"]
-            return self.__upload_id
-
-    @property
-    def _buffer_size(self):
-        return self._total_buffer_size - sum(
-            future.result().content_size
-            for future in self._futures.values()
-            if future.done()
-        )
-
-    @property
-    def _uploading_futures(self):
-        return [future for future in self._futures.values() if not future.done()]
+        if self.__upload_id is None:
+            with self.__upload_id_lock:
+                if self.__upload_id is None:
+                    with raise_s3_error(self.name):
+                        self.__upload_id = self._client.create_multipart_upload(
+                            Bucket=self._bucket, Key=self._key
+                        )["UploadId"]
+        return self.__upload_id
 
     @property
     def _multipart_upload(self):
-        return {
-            "Parts": [
-                future.result().asdict() for _, future in sorted(self._futures.items())
-            ]
-        }
+        for future in self._uploading_futures:
+            result = future.result()
+            self._total_buffer_size -= result.content_size
+            self._futures_result[result.part_number] = result.asdict()
+        self._uploading_futures = set()
+        return {"Parts": [result for _, result in sorted(self._futures_result.items())]}
 
     def _upload_buffer(self, part_number, content):
         with raise_s3_error(self.name):
@@ -163,33 +155,47 @@ class S3BufferedWriter(Writable[bytes]):
                 len(content),
             )
 
-    def _submit_upload_buffer(self, part_number, content):
-        self._futures[part_number] = self._executor.submit(
-            self._upload_buffer, part_number, content
+    def _submit_upload_buffer(self, part_number: int, content: bytes):
+        self._uploading_futures.add(
+            self._executor.submit(self._upload_buffer, part_number, content)
         )
         self._total_buffer_size += len(content)
-        while self._buffer_size > self._max_buffer_size:
-            wait(self._uploading_futures, return_when=FIRST_COMPLETED)
+
+        while (
+            self._uploading_futures and self._total_buffer_size >= self._max_buffer_size
+        ):
+            wait_result = wait(self._uploading_futures, return_when=FIRST_COMPLETED)
+            for future in wait_result.done:
+                result = future.result()
+                self._total_buffer_size -= result.content_size
+                self._futures_result[result.part_number] = result.asdict()
+            self._uploading_futures = wait_result.not_done
 
     def _submit_upload_content(self, content: bytes):
         # s3 part needs at least 5MB,
         # so we need to divide content into equal-size parts,
         # and give last part more size.
         # e.g. 257MB can be divided into 2 parts, 128MB and 129MB
-        offset = 0
-        while len(content) - offset - self._max_block_size > self._block_size:
+        block_size = self._block_size
+        while len(content) - block_size > self.MIN_BLOCK_SIZE:
+            self._part_number += 1
+            current_content, content = (
+                content[:block_size],
+                content[block_size:],
+            )
+            self._submit_upload_buffer(self._part_number, current_content)
+            block_size = self._block_size
+
+        if content:
             self._part_number += 1
-            offset_stop = offset + self._max_block_size
-            self._submit_upload_buffer(self._part_number, content[offset:offset_stop])
-            offset = offset_stop
-        self._part_number += 1
-        self._submit_upload_buffer(self._part_number, content[offset:])
+            self._submit_upload_buffer(self._part_number, content)
 
     def _submit_futures(self):
         content = self._buffer.getvalue()
         if len(content) == 0:
             return
-        self._buffer = BytesIO()
+        self._buffer.seek(0, os.SEEK_SET)
+        self._buffer.truncate()
         self._submit_upload_content(content)
 
     def write(self, data: bytes) -> int:

megfile/lib/s3_cached_handler.py

@@ -19,8 +19,7 @@ class S3CachedHandler(S3MemoryHandler):
         profile_name: Optional[str] = None,
     ):
         if mode not in ("rb", "wb", "ab", "rb+", "wb+", "ab+"):
-            # TODO: replace AssertionError with ValueError in 4.0.0
-            raise AssertionError("unacceptable mode: %r" % mode)
+            raise ValueError("unacceptable mode: %r" % mode)
 
         self._bucket = bucket
         self._key = key

megfile/lib/s3_limited_seekable_writer.py

@@ -4,9 +4,7 @@ from logging import getLogger as get_logger
 from typing import Optional
 
 from megfile.config import (
-    DEFAULT_MAX_BLOCK_SIZE,
-    DEFAULT_MAX_BUFFER_SIZE,
-    DEFAULT_MIN_BLOCK_SIZE,
+    WRITER_MAX_BUFFER_SIZE,
 )
 from megfile.errors import raise_s3_error
 from megfile.interfaces import Seekable
@@ -29,11 +27,10 @@ class S3LimitedSeekableWriter(S3BufferedWriter, Seekable):
         key: str,
         *,
         s3_client,
-        block_size: int = DEFAULT_MIN_BLOCK_SIZE,
+        block_size: int = S3BufferedWriter.MIN_BLOCK_SIZE,
         head_block_size: Optional[int] = None,
         tail_block_size: Optional[int] = None,
-        max_block_size: int = DEFAULT_MAX_BLOCK_SIZE,
-        max_buffer_size: int = DEFAULT_MAX_BUFFER_SIZE,
+        max_buffer_size: int = WRITER_MAX_BUFFER_SIZE,
         max_workers: Optional[int] = None,
         profile_name: Optional[str] = None,
     ):
@@ -42,7 +39,6 @@ class S3LimitedSeekableWriter(S3BufferedWriter, Seekable):
             key,
             s3_client=s3_client,
             block_size=block_size,
-            max_block_size=max_block_size,
             max_buffer_size=max_buffer_size,
             max_workers=max_workers,
             profile_name=profile_name,

megfile/lib/s3_memory_handler.py

@@ -22,8 +22,7 @@ class S3MemoryHandler(Readable[bytes], Seekable, Writable[bytes]):
         profile_name: Optional[str] = None,
     ):
         if mode not in ("rb", "wb", "ab", "rb+", "wb+", "ab+"):
-            # TODO: replace AssertionError with ValueError in 4.0.0
-            raise AssertionError("unacceptable mode: %r" % mode)
+            raise ValueError("unacceptable mode: %r" % mode)
 
         self._bucket = bucket
         self._key = key

megfile/lib/s3_pipe_handler.py

@@ -35,8 +35,7 @@ class S3PipeHandler(Readable[bytes], Writable[bytes]):
         profile_name: Optional[str] = None,
     ):
         if mode not in ("rb", "wb"):
-            # TODO: replace AssertionError with ValueError in 4.0.0
-            raise AssertionError("unacceptable mode: %r" % mode)
+            raise ValueError("unacceptable mode: %r" % mode)
 
         self._bucket = bucket
         self._key = key