feat(py-client): Add a util to guess MIME type (#197)

Author: lcian

clients/python/pyproject.toml

@@ -14,6 +14,7 @@ dependencies = [
     "sentry-sdk>=2.42.1",
     "urllib3>=2.2.2",
     "zstandard>=0.18.0",
+    "filetype>=1.2.0",
 ]
 
 [build-system]

clients/python/src/objectstore_client/client.py

@@ -234,6 +234,9 @@ def put(
         This can be overridden by explicitly giving a `compression` argument.
         Providing `"none"` as the argument will instruct the client to not apply
         any compression to this upload, which is useful for uncompressible formats.
+
+        You can use the utility function `objectstore_client.utils.guess_mime_type`
+        to attempt to guess a `content_type` based on magic bytes.
         """
         headers = self._make_headers()
         body = BytesIO(contents) if isinstance(contents, bytes) else contents

clients/python/src/objectstore_client/utils.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import IO
+
+import filetype  # type: ignore
+
+
+def guess_mime_type(contents: bytes | IO[bytes]) -> str | None:
+    """
+    Guesses the MIME type from the given contents.
+
+    Reads up to 261 bytes from the beginning of the content to determine
+    the MIME type using file header signatures.
+
+    To guess the MIME type from a filename, use `mimetypes.guess_type`,
+    which is part of the standard library.
+    """
+
+    if isinstance(contents, bytes):
+        header = contents[:261]
+    else:
+        if not contents.seekable():
+            return None
+        pos = contents.tell()
+        header = contents.read(261)
+        contents.seek(pos)
+
+    kind = filetype.guess(header)
+    return kind.mime if kind else None