Merge pull request #40 from aiokitchen/feature/39-adoption

Backport features from #37

Author: mosquito

README.md

@@ -65,6 +65,13 @@ async def main():
         async with client.delete("bucket/key") as resp:
             assert resp == HTTPStatus.NO_CONTENT
 
+        # Server-side copy
+        async with client.copy("bucket/src-key", "bucket/dst-key") as resp:
+            assert resp.status == HTTPStatus.OK
+
+        # Rename (copy + delete source, not atomic)
+        await client.rename("bucket/old-key", "bucket/new-key")
+
         # List objects by prefix
         async for result, prefixes in client.list_objects_v2(
             "bucket/", prefix="prefix",
@@ -358,6 +365,87 @@ async def main():
 asyncio.run(main())
 ```
 
+## Content-Type inference
+
+When uploading objects the client automatically infers the `Content-Type`
+header from the object key (or local file path) using Python's
+`mimetypes.guess_type`. For example, uploading to `bucket/photo.jpg` will
+set `Content-Type: image/jpeg`. If the type cannot be determined it falls
+back to `application/octet-stream`.
+
+You can always override this by passing an explicit `Content-Type` header:
+
+```python
+async with client.put(
+    "bucket/data.bin",
+    some_bytes,
+    headers={"Content-Type": "application/x-custom"},
+) as resp:
+    ...
+```
+
+## Custom metadata
+
+S3 allows you to attach arbitrary key-value metadata to objects using
+`x-amz-meta-<key>` headers. You can pass these via the `headers` parameter
+on any upload method.
+
+With `client.put()`:
+
+```python
+async with client.put(
+    "bucket/report.json",
+    b'{"result": 42}',
+    headers={
+        "x-amz-meta-author": "alice",
+        "x-amz-meta-version": "3",
+    },
+) as resp:
+    assert resp.status == 200
+```
+
+With `client.put_file()`:
+
+```python
+resp = await client.put_file(
+    "bucket/photo.jpg",
+    "/path/to/photo.jpg",
+    headers={
+        "x-amz-meta-camera": "Nikon D850",
+        "x-amz-meta-location": "Paris",
+    },
+)
+```
+
+With `client.put_file_multipart()`:
+
+```python
+await client.put_file_multipart(
+    "bucket/bigfile.csv",
+    "/path/to/bigfile.csv",
+    headers={
+        "Content-Type": "text/csv",
+        "x-amz-meta-source": "etl-pipeline",
+    },
+    workers_count=8,
+)
+```
+
+Metadata can also be set or replaced during a server-side copy by passing
+`replace_metadata=True`:
+
+```python
+async with client.copy(
+    "bucket/src-key",
+    "bucket/dst-key",
+    replace_metadata=True,
+    headers={
+        "x-amz-meta-status": "archived",
+    },
+) as resp:
+    assert resp.status == 200
+```
+
 ## Parallel download to file
 
 S3 supports `GET` requests with `Range` header. It's possible to download

aiohttp_s3_client/client.py

@@ -1,6 +1,8 @@
 import asyncio
 import hashlib
 import logging
+import mimetypes
+import sys
 import threading
 from collections.abc import (
     AsyncIterable,
@@ -11,7 +13,6 @@
 )
 from functools import cached_property
 from http import HTTPStatus
-from mimetypes import guess_type
 from mmap import PAGESIZE
 from pathlib import Path
 from tempfile import TemporaryFile
@@ -51,6 +52,16 @@
 EMPTY_STR_HASH = hashlib.sha256(b"").hexdigest()
 PART_SIZE = 5 * 1024 * 1024  # 5MB
 
+if sys.version_info >= (3, 13):
+
+    def _guess_content_type(path: str) -> str | None:
+        return mimetypes.guess_file_type(path)[0]
+else:
+
+    def _guess_content_type(path: str) -> str | None:
+        return mimetypes.guess_type(path)[0]
+
+
 HeadersType = dict | CIMultiDict | CIMultiDictProxy
 
 
@@ -208,12 +219,19 @@ def _make_headers(headers: HeadersType | None) -> CIMultiDict:
     def _prepare_headers(
         self,
         headers: HeadersType | None,
-        file_path: str = "",
+        path_hint: str = "",
     ) -> CIMultiDict:
+        """Prepare headers and infer Content-Type when not explicitly set.
+
+        If a ``Content-Type`` header is already present it is left unchanged.
+        Otherwise the type is guessed from *path_hint* (typically the object
+        key or a local file path) using :func:`mimetypes.guess_type`, falling
+        back to ``application/octet-stream``.
+        """
         headers = self._make_headers(headers)
 
         if hdrs.CONTENT_TYPE not in headers:
-            content_type = guess_type(file_path)[0]
+            content_type = _guess_content_type(path_hint)
             if content_type is None:
                 content_type = "application/octet-stream"
 
@@ -227,15 +245,35 @@ def put(
         data: bytes | str | AsyncIterable[bytes],
         **kwargs,
     ) -> RequestContextManager:
-        return self.request("PUT", object_name, data=data, **kwargs)
+        headers = self._prepare_headers(
+            kwargs.pop("headers", None),
+            object_name,
+        )
+        return self.request(
+            "PUT",
+            object_name,
+            data=data,
+            headers=headers,
+            **kwargs,
+        )
 
     def post(
         self,
         object_name: str,
         data: bytes | str | AsyncIterable[bytes] | None = None,
         **kwargs,
     ) -> RequestContextManager:
-        return self.request("POST", object_name, data=data, **kwargs)
+        headers = self._prepare_headers(
+            kwargs.pop("headers", None),
+            object_name,
+        )
+        return self.request(
+            "POST",
+            object_name,
+            data=data,
+            headers=headers,
+            **kwargs,
+        )
 
     async def put_file(
         self,
@@ -324,6 +362,8 @@ async def put_file_multipart(
             part_size,
         )
 
+        headers = self._prepare_headers(headers, str(file_path))
+
         async with (
             Reader(
                 file_path,
@@ -399,6 +439,8 @@ async def put_multipart(
             for integrity purposes
         """
 
+        headers = self._prepare_headers(headers, str(object_name))
+
         with TemporaryFile() as fp:
 
             def place_temp_file():
@@ -706,6 +748,86 @@ def presign_url(
             )
         )
 
+    def copy(
+        self,
+        source: str,
+        destination: str,
+        *,
+        headers: HeadersType | None = None,
+        replace_metadata: bool = False,
+        content_type: str | None = None,
+        content_sha256: str = EMPTY_STR_HASH,
+        **kwargs,
+    ) -> RequestContextManager:
+        """Server-side copy of an S3 object.
+
+        source: source object key (e.g. ``bucket/key``)
+        destination: destination object key
+        headers: additional headers
+        replace_metadata: when *True* the destination receives the supplied
+            metadata instead of inheriting the source metadata
+        content_type: optional Content-Type override for the destination
+        """
+        headers = self._prepare_headers(headers, destination)
+        source_url = self._url / source.lstrip("/")
+        headers["x-amz-copy-source"] = quote(
+            source_url.path,
+            safe="/",
+        )
+        if replace_metadata:
+            headers["x-amz-metadata-directive"] = "REPLACE"
+        if content_type is not None:
+            headers[hdrs.CONTENT_TYPE] = content_type
+        return self.request(
+            "PUT",
+            destination,
+            headers=headers,
+            content_sha256=content_sha256,
+            **kwargs,
+        )
+
+    async def rename(
+        self,
+        source: str,
+        destination: str,
+        *,
+        headers: HeadersType | None = None,
+        **kwargs,
+    ) -> None:
+        """Move an S3 object by copying then deleting the source.
+
+        This operation is **not** atomic — if the delete fails after a
+        successful copy, the object will exist at both locations.
+
+        source: source object key
+        destination: destination object key
+        headers: additional headers forwarded to ``copy()``
+        """
+        async with self.copy(
+            source,
+            destination,
+            headers=headers,
+            **kwargs,
+        ) as resp:
+            if resp.status != HTTPStatus.OK:
+                payload = await resp.text()
+                raise AwsUploadError(
+                    resp,
+                    f"Copy failed with status {resp.status}: {payload}",
+                )
+
+        async with self.delete(source) as resp:
+            if resp.status not in (
+                HTTPStatus.OK,
+                HTTPStatus.NO_CONTENT,
+            ):
+                payload = await resp.text()
+                raise AwsError(
+                    resp,
+                    f"Delete of source failed with status "
+                    f"{resp.status}: {payload}",
+                )
+
     def multipart_upload(self, object_name: str) -> "MultipartUploader":
         """
         Get S3MultipartUploader for object_name

tests/test_simple.py

@@ -237,3 +237,34 @@ async def gen():
     headers = call.kwargs.get("headers")
     trailer = "STREAMING-UNSIGNED-PAYLOAD-TRAILER"
     assert headers.get("x-amz-content-sha256") == trailer
+
+
+async def test_copy_object(s3_client: S3Client, s3_read):
+    data = b"hello, copy"
+    source = "/test/copy-source"
+    destination = "/test/copy-destination"
+
+    resp = await s3_client.put(source, data)
+    assert resp.status == HTTPStatus.OK
+
+    async with s3_client.copy(source, destination) as resp:
+        assert resp.status == HTTPStatus.OK
+
+    assert (await s3_read(source)) == data
+    assert (await s3_read(destination)) == data
+
+
+async def test_rename_object(s3_client: S3Client, s3_read):
+    data = b"hello, rename"
+    source = "/test/rename-source"
+    destination = "/test/rename-destination"
+
+    resp = await s3_client.put(source, data)
+    assert resp.status == HTTPStatus.OK
+
+    await s3_client.rename(source, destination)
+
+    assert (await s3_read(destination)) == data
+
+    async with s3_client.get(source) as resp:
+        assert resp.status == HTTPStatus.NOT_FOUND