Default behaviour improvements and explanations

  * New settings.py parameter: MINIO_BUCKET_CHECK_ON_SAVE [default=False]
  * New section in README.md: Behaviour

DjangoExampleProject/settings.py

@@ -171,4 +171,4 @@
 ]
 MINIO_MEDIA_FILES_BUCKET = 'my-media-files-bucket'  # replacement for STATIC_ROOT
 MINIO_STATIC_FILES_BUCKET = 'my-static-files-bucket'  # replacement for MEDIA_ROOT
-MINIO_BUCKET_EXISTENCE_CHECK_BEFORE_SAVE = True  # Create bucket if missing, then save
+MINIO_BUCKET_CHECK_ON_SAVE = False  # Create bucket if missing, then save

README.md

@@ -59,7 +59,7 @@ MINIO_PUBLIC_BUCKETS = [
 MINIO_POLICY_HOOKS: List[Tuple[str, dict]] = []
 # MINIO_MEDIA_FILES_BUCKET = 'my-media-files-bucket'  # replacement for MEDIA_ROOT
 # MINIO_STATIC_FILES_BUCKET = 'my-static-files-bucket'  # replacement for STATIC_ROOT
-MINIO_BUCKET_EXISTENCE_CHECK_BEFORE_SAVE = True  # Default: True // Creates bucket if missing, then save
+MINIO_BUCKET_CHECK_ON_SAVE = True  # Default: True // Creates bucket if missing, then save
 ```
 
 4. Implement your own Attachment handler and integrate **django-minio-backend**:
@@ -157,6 +157,21 @@ In case a bucket is missing or its configuration differs, it gets created and co
 ### Reference Implementation
 For a reference implementation, see [Examples](examples).
 
+## Behaviour
+The following list summarises the key characteristics of **django-minio-backend**:
+  * Bucket existence is **not** checked on save by default.
+    To enable this guard, set `MINIO_BUCKET_CHECK_ON_SAVE = True` in your `settings.py`.
+  * Bucket existences are **not** checked on Django start by default.
+    To enable this guard, set `MINIO_CONSISTENCY_CHECK_ON_START = True` in your `settings.py`.
+  * Many configuration errors are validated through `AppConfig` but not every error can be captured there.
+  * Files with the same name in the same bucket are **not** replaced on save by default. Django will store the newer file with an altered file name
+    To allow replacing existing files, pass the `replace_existing=True` kwarg to `MinioBackend`.
+    For example: `image = models.ImageField(storage=MinioBackend(bucket_name='images-public', replace_existing=True))`
+  * Depending on your configuration, **django-minio-backend** may communicate over two kind of interfaces: internal and external.
+    If your `settings.py` defines a different value for `MINIO_ENDPOINT` and `MINIO_EXTERNAL_ENDPOINT`, then the former will be used for internal communication
+    between Django and MinIO, and the latter for generating URLs for users. This behaviour optimises the network communication.
+  * The uploaded object's content-type is guessed during save. If `mimetypes.guess_type` fails to determine the correct content-type, then it falls back to `application/octet-stream`.
+
 ## Compatibility
   * Django 2.2 or later
   * Python 3.6.0 or later

django_minio_backend/models.py

@@ -91,6 +91,7 @@ def __init__(self,
         self.__MINIO_SECRET_KEY: str = get_setting("MINIO_SECRET_KEY")
         self.__MINIO_USE_HTTPS: bool = get_setting("MINIO_USE_HTTPS")
         self.__MINIO_EXTERNAL_ENDPOINT_USE_HTTPS: bool = get_setting("MINIO_EXTERNAL_ENDPOINT_USE_HTTPS", self.__MINIO_USE_HTTPS)
+        self.__MINIO_BUCKET_CHECK_ON_SAVE: bool = get_setting("MINIO_BUCKET_CHECK_ON_SAVE", False)
 
         self.__BASE_URL = ("https://" if self.__MINIO_USE_HTTPS else "http://") + self.__MINIO_ENDPOINT
         self.__BASE_URL_EXTERNAL = ("https://" if self.__MINIO_EXTERNAL_ENDPOINT_USE_HTTPS else "http://") + self.__MINIO_EXTERNAL_ENDPOINT
@@ -133,8 +134,8 @@ def _save(self, file_path_name: str, content: InMemoryUploadedFile) -> str:
         :param content (InMemoryUploadedFile): File object
         :return:
         """
-        if get_setting("MINIO_BUCKET_EXISTENCE_CHECK_BEFORE_SAVE", True):
-            # Check if bucket exists, create if not
+        if self.__MINIO_BUCKET_CHECK_ON_SAVE:
+            # Create bucket if not exists
             self.check_bucket_existence()
 
         # Check if object with name already exists; delete if so