Merge pull request #177 from maresb/buffered-copy

Add example of buffered copy to docs

docs/comparison.rst

@@ -54,10 +54,23 @@ S3Path Example:
 
 .. code:: python
 
-   >>> from s3path import S3Path, Path
+   >>> from pathlib import Path
+   >>> from s3path import S3Path
    >>> local_path = Path('/tmp/hello.txt')
    >>> S3Path('/my-bucket/hello.txt').write_text(local_path.read_text())
 
+S3Path Example (buffered, to avoid loading large files into memory):
+
+.. code:: python
+
+   >>> import shutil
+   >>> from pathlib import Path
+   >>> from s3path import S3Path
+   >>> local_path = Path('/tmp/hello.txt')
+   >>> remote_path = S3Path('/my-bucket/hello.txt')
+   >>> with local_path.open('rb') as src, remote_path.open('wb') as dst:
+   >>>     shutil.copyfileobj(src, dst)
+
 boto3 Example:
 
 .. code:: python
@@ -74,7 +87,8 @@ S3Path Example:
 
 .. code:: python
 
-   >>> from s3path import S3Path, Path
+   >>> from pathlib import Path
+   >>> from s3path import S3Path
    >>> local_path = Path('./my_local_image.jpg')
    >>> local_path.write_text(S3Path('/my-bucket/my_image_in_s3.jpg').read_text())
 

tests/test_path_operations.py

@@ -1,3 +1,4 @@
+import shutil
 import sys
 from datetime import timedelta
 from pathlib import Path
@@ -892,3 +893,15 @@ def test_versioned_bucket(s3_mock):
     for path in paths:
         assert not isinstance(path, VersionedS3Path)
         assert path.read_bytes() == file_contents_by_version[-1]
+
+
+def test_buffered_copy(s3_mock):
+    s3 = boto3.resource('s3')
+    s3.create_bucket(Bucket='test-bucket')
+    data = b'test data' * 10_000_000
+    source_path = S3Path('/test-bucket/source')
+    source_path.write_bytes(data)
+    target_path = S3Path('/test-bucket/target')
+    with source_path.open('rb') as source, target_path.open('wb') as target:
+        shutil.copyfileobj(source, target)
+    assert target_path.read_bytes() == data