Allow to put_file() by name/path. Also add type detection by default.

src/pycdstar3/api.py

@@ -280,11 +280,30 @@ class CDStar:
             else:
                 break
 
-    def put_file(self, vault, archive, name, source, type=None) -> JsonObject:
+    def put_file(self, vault, archive, name, source, type=None, replace=True) -> JsonObject:
+        """ Create or replace a single file on an existing archive.
+
+        If the file exists remotely and `replace=True` is set (default), the file content is overridden but everything
+        else (metadata, type, file id) stays the same. If `replace` is `False` then a file name conflict is an error.
+
+        :param vault: Vault name
+        :param archive: Archive ID
+        :param name: Target file name. May start with `/` (optional) but must not end with `/`.
+        :param source: Readable file, byte buffer or iterator, or a file path that will then be opened in 'rb' mode.
+        :param type: Mime-type to set on the uploaded file. (default: guess based on filename)
+        :param replace: If the remote file already exists, replace its content. (default: True)
+        :return:
+        """
+
         if isinstance(source, PATH_TYPES):
-            raise ValueError("Source must be a file-like object, byte string or iterator yielding byte strings.")
-        return self.rest("PUT", vault, archive, _fix_filename(name), data=source,
-                         headers={'Content-Type': type or "application/x-autodetect"})
+            with open(source, 'rb') as source:
+                return self.put_file(vault, archive, name, source, type=None, replace=True)
+
+        headers = {'Content-Type': type or "application/x-autodetect"}
+        if not replace:
+            headers['If-None-Match'] = "*"
+
+        return self.rest("PUT", vault, archive, _fix_filename(name), data=source, headers=headers)
 
     def get_file(self, vault, archive, name, offset=0) -> FileDownload:
         """ Request a file and return a stream-able :class:`FileDownload`.