piskvorky · mpenkov · Jul 15, 2019 · Jun 16, 2019 · Jun 16, 2019 · Jun 17, 2019
diff --git a/README.rst b/README.rst
@@ -61,6 +61,14 @@ What?
   ...     break
   '<!doctype html>\n'
 
+  >>> from smart_open import open
+  >>> with open('s3://bucket/key.txt', 'rb', transport_params = {'version_id':'need_key_version_id') as file:
+  ...   for line in file:
+  ...       print(line)
+  b'sdsaf\r\n'
+  b'1234\r\n'
+
+
 Other examples of URLs that ``smart_open`` accepts::
 
     s3://my_bucket/my_key
@@ -257,7 +265,24 @@ Since going over all (or select) keys in an S3 bucket is a very common operation
   ...     print(key, round(len(content) / 2**20))
   annual/monthly_rain/2010.monthly_rain.nc 13
   annual/monthly_rain/2011.monthly_rain.nc 13
-  annual/monthly_rain/2012.monthly_rain.nc 13
+  annual/monthly_rain/2012.monthly_rain.nc 13 
+
+Specific s3 object version
+--------------------------------------
+
+The ``smart_open``'s ``open`` function has the parameter version_id, which allows you to get the desired version of the file from bucket S3.
+
+*Important*: Version control disabled by default. Before starting to use version_id parameter, enable version control in bucket S3. Read https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html
+
+.. code-block:: python
+
+  >>> from smart_open import open
+  >>> with open('s3://bucket/key.txt', 'rb', transport_params = {'version_id':'need_key_version_id') as file:
+  ...   for line in file:
+  ......   print(line)
+  b'sdsaf\r\n'
+  b'1234\r\n'
+
 
 
 Migrating to the new ``open`` function

diff --git a/help.txt b/help.txt
@@ -129,91 +129,38 @@ FUNCTIONS
 
         Examples
         --------
-        >>> from smart_open import open
-        >>>
-        >>> # stream lines from an S3 object
-        >>> for line in open('s3://commoncrawl/robots.txt'):
-        ...    print(repr(line))
-        ...    break
-        'User-Agent: *\n'
-
-        >>> # stream from/to compressed files, with transparent (de)compression:
-        >>> for line in open('smart_open/tests/test_data/1984.txt.gz', encoding='utf-8'):
-        ...    print(repr(line))
-        'It was a bright cold day in April, and the clocks were striking thirteen.\n'
-        'Winston Smith, his chin nuzzled into his breast in an effort to escape the vile\n'
-        'wind, slipped quickly through the glass doors of Victory Mansions, though not\n'
-        'quickly enough to prevent a swirl of gritty dust from entering along with him.\n'
-
-        >>> # can use context managers too:
-        >>> with open('smart_open/tests/test_data/1984.txt.gz') as fin:
-        ...    with open('smart_open/tests/test_data/1984.txt.bz2', 'w') as fout:
-        ...        for line in fin:
-        ...           fout.write(line)
-
-        >>> # can use any IOBase operations, like seek
-        >>> with open('s3://commoncrawl/robots.txt', 'rb') as fin:
-        ...     for line in fin:
-        ...         print(repr(line.decode('utf-8')))
-        ...         break
-        ...     offset = fin.seek(0)  # seek to the beginning
-        ...     print(fin.read(4))
-        'User-Agent: *\n'
-        b'User'
-
-        >>> # stream from HTTP
-        >>> for line in open('http://example.com/index.html'):
-        ...     print(repr(line))
-        ...     break
-        '<!doctype html>\n'
-
-        Other examples of URLs that ``smart_open`` accepts::
-
-          s3://my_bucket/my_key
-          s3://my_key:my_secret@my_bucket/my_key
-          s3://my_key:my_secret@my_server:my_port@my_bucket/my_key
-          hdfs:///path/file
-          hdfs://path/file
-          webhdfs://host:port/path/file
-          ./local/path/file
-          ~/local/path/file
-          local/path/file
-          ./local/path/file.gz
-          file:///home/user/file
-          file:///home/user/file.bz2
-          [ssh|scp|sftp]://username@host//path/file
-
-
+        See README.rst
+
         See Also
         --------
         - `Standard library reference <https://docs.python.org/3.7/library/functions.html#open>`__
         - `smart_open README.rst <https://github.com/RaRe-Technologies/smart_open/blob/master/README.rst>`__
-    
+
     register_compressor(ext, callback)
         Register a callback for transparently decompressing files with a specific extension.
-        
+
         Parameters
         ----------
         ext: str
             The extension.
         callback: callable
             The callback.  It must accept two position arguments, file_obj and mode.
-        
+
         Examples
         --------
-        
+
         Instruct smart_open to use the identity function whenever opening a file
         with a .xz extension (see README.rst for the complete example showing I/O):
-        
+
         >>> def _handle_xz(file_obj, mode):
         ...     import lzma
         ...     return lzma.LZMAFile(filename=file_obj, mode=mode, format=lzma.FORMAT_XZ)
         >>>
         >>> register_compressor('.xz', _handle_xz)
-    
+
     s3_iter_bucket = iter_bucket(bucket_name, prefix='', accept_key=None, key_limit=None, workers=16, retries=3)
         Iterate and download all S3 objects under `s3://bucket_name/prefix`.
-        
+
         Parameters
         ----------
         bucket_name: str
@@ -230,40 +177,39 @@ FUNCTIONS
             The number of subprocesses to use.
         retries: int, optional
             The number of time to retry a failed download.
-        
+
         Yields
         ------
         str
             The full key name (does not include the bucket name).
         bytes
             The full contents of the key.
-        
+
         Notes
         -----
         The keys are processed in parallel, using `workers` processes (default: 16),
         to speed up downloads greatly. If multiprocessing is not available, thus
         _MULTIPROCESSING is False, this parameter will be ignored.
-        
+
         Examples
         --------
-        
+
           >>> # get all JSON files under "mybucket/foo/"
           >>> for key, content in iter_bucket(bucket_name, prefix='foo/', accept_key=lambda key: key.endswith('.json')):
           ...     print key, len(content)
-        
+
           >>> # limit to 10k files, using 32 parallel workers (default is 16)
           >>> for key, content in iter_bucket(bucket_name, key_limit=10000, workers=32):
           ...     print key, len(content)
-    
+
     smart_open(uri, mode='rb', **kw)
+        Deprecated, use smart_open.open instead.
 
 DATA
     __all__ = ['open', 'smart_open', 's3_iter_bucket', 'register_compresso...
 
 VERSION
-    1.8.4
+    1.8.3
 
 FILE
-    /home/misha/git/smart_open/smart_open/__init__.py
-
-
+    c:\users\user\appdata\local\programs\python\python36\lib\site-packages\smart_open\__init__.py
diff --git a/smart_open/s3.py b/smart_open/s3.py
@@ -70,6 +70,7 @@ def open(
         bucket_id,
         key_id,
         mode,
+        version_id=None,
         buffer_size=DEFAULT_BUFFER_SIZE,
         min_part_size=DEFAULT_MIN_PART_SIZE,
         session=None,
@@ -97,6 +98,8 @@ def open(
     multipart_upload_kwargs: dict, optional
         Additional parameters to pass to boto3's initiate_multipart_upload function.
         For writing only.
+    version_id: str, optional
+        Version of the object, used when reading object. If None, will fetch the most recent version.
 
     """
     logger.debug('%r', locals())
@@ -108,10 +111,14 @@ def open(
     if multipart_upload_kwargs is None:
         multipart_upload_kwargs = {}
 
+    if (mode == WRITE_BINARY) and (version_id is not None):
+        raise ValueError("version_id must be None when writing")
+
     if mode == READ_BINARY:
         fileobj = SeekableBufferedInputBase(
             bucket_id,
             key_id,
+            version_id=version_id,
             buffer_size=buffer_size,
             session=session,
             resource_kwargs=resource_kwargs,
@@ -127,10 +134,22 @@ def open(
         )
     else:
         assert False, 'unexpected mode: %r' % mode
-
     return fileobj
 
 
+def _get(s3_object, version=None, **kwargs):
+    if version is not None:
+        kwargs['VersionId'] = version
+    try:
+        return s3_object.get(**kwargs)
+    except botocore.client.ClientError as error:
+        raise IOError(
+            'unable to access bucket: %r key: %r version: %r error: %s' % (
+                s3_object.bucket_name, s3_object.key, version, error
+            )
+        )
+
+
 class RawReader(object):
     """Read an S3 object."""
     def __init__(self, s3_object):
@@ -147,9 +166,10 @@ def read(self, size=-1):
 class SeekableRawReader(object):
     """Read an S3 object."""
 
-    def __init__(self, s3_object, content_length):
+    def __init__(self, s3_object, content_length, version_id=None):
         self._object = s3_object
         self._content_length = content_length
+        self._version_id = version_id
         self.seek(0)
 
     def seek(self, position):
@@ -177,7 +197,7 @@ def seek(self, position):
             #
             self._body = io.BytesIO()
         else:
-            self._body = self._object.get(Range=range_string)['Body']
+            self._body = _get(self._object, self._version_id, Range=range_string)['Body']
 
     def read(self, size=-1):
         if self._position >= self._content_length:
@@ -191,7 +211,7 @@ def read(self, size=-1):
 
 
 class BufferedInputBase(io.BufferedIOBase):
-    def __init__(self, bucket, key, buffer_size=DEFAULT_BUFFER_SIZE,
+    def __init__(self, bucket, key, version_id=None, buffer_size=DEFAULT_BUFFER_SIZE,
                  line_terminator=BINARY_NEWLINE, session=None, resource_kwargs=None):
         if session is None:
             session = boto3.Session()
@@ -200,8 +220,10 @@ def __init__(self, bucket, key, buffer_size=DEFAULT_BUFFER_SIZE,
 
         s3 = session.resource('s3', **resource_kwargs)
         self._object = s3.Object(bucket, key)
+        self._version_id = version_id
         self._raw_reader = RawReader(self._object)
         self._content_length = self._object.content_length
+        self._content_length = _get(self._object, self._version_id)['ContentLength']
         self._current_pos = 0
         self._buffer = smart_open.bytebuffer.ByteBuffer(buffer_size)
         self._eof = False
@@ -328,24 +350,18 @@ class SeekableBufferedInputBase(BufferedInputBase):
 
     Implements the io.BufferedIOBase interface of the standard library."""
 
-    def __init__(self, bucket, key, buffer_size=DEFAULT_BUFFER_SIZE,
+    def __init__(self, bucket, key, version_id=None, buffer_size=DEFAULT_BUFFER_SIZE,
                  line_terminator=BINARY_NEWLINE, session=None, resource_kwargs=None):
         if session is None:
             session = boto3.Session()
         if resource_kwargs is None:
             resource_kwargs = {}
         s3 = session.resource('s3', **resource_kwargs)
         self._object = s3.Object(bucket, key)
+        self._version_id = version_id
+        self._content_length = _get(self._object, self._version_id)['ContentLength']
 
-        try:
-            self._content_length = self._object.content_length
-        except botocore.client.ClientError:
-            raise ValueError(
-                '%r does not exist in the bucket %r, '
-                'or is forbidden for access' % (key, bucket)
-            )
-
-        self._raw_reader = SeekableRawReader(self._object, self._content_length)
+        self._raw_reader = SeekableRawReader(self._object, self._content_length, self._version_id)
         self._current_pos = 0
         self._buffer = smart_open.bytebuffer.ByteBuffer(buffer_size)
         self._eof = False

diff --git a/smart_open/tests/test_s3.py b/smart_open/tests/test_s3.py
@@ -382,7 +382,7 @@ def test_nonexisting_bucket(self):
                 fout.write(expected)
 
     def test_read_nonexisting_key(self):
-        with self.assertRaises(ValueError):
+        with self.assertRaises(IOError):
             with smart_open.s3.open(BUCKET_NAME, 'my_nonexisting_key', 'rb') as fin:
                 fin.read()