feat: add python api for creating files (#487)

* feat: add utils for creating files

avoids forgetting to set encryption_status

* refactor: rename utils to api

add docs to api

* refactor(api): make arguments more explicit

* refactor(api): use explicit argument names

* chore(api): improve doc formatting

* refactor(api): improve additional argument names

PYTHON_API.md

@@ -0,0 +1,43 @@
+# API Functions
+
+Functions which make interacting with the models easier.
+
+## `create_document_file`
+
+Creates a document and file
+
+### Parameters
+
+- `user` The user creating the document and file.
+- `group` The group creating the document and file.
+- `category` models.Category,
+- `document_title` Name of the document
+- `file_name` Name of the file
+- `file_content` File object
+- `mime_type` File mime type
+- `file_size` File size 
+- `additional_document_attributes` A dictionary containing the optional fields for the document.
+- `additional_file_attributes` A dictionary containing the optional fields for the file.
+
+### Return
+
+- A tuple containing the created document and file.
+
+## `create_file`
+
+Creates a file with thumbnail
+
+### Parameters
+
+- `document` The document associated with the file.
+- `user` The user who created the file.
+- `group` The group who created the file.
+- `name` Name of the file
+- `content` File object
+- `mime_type` File mime type
+- `size` File size
+- `additional_attributes` Kwargs containing the optional fields for the file. 
+
+### Return
+
+- The created file object.

README.md

@@ -42,6 +42,10 @@ To load a set of categories run the following command:
 make load_example_data
 ```
 
+### Usage
+
+If alexandria is installed as a package you can use [PYTHON_API](PYTHON_API.md) for interacting with the models in an easier way.
+
 ### Configuration
 
 Alexandria is a [12factor app](https://12factor.net/) which means that configuration is stored in environment variables.

alexandria/core/api.py

@@ -0,0 +1,96 @@
+import logging
+
+from django.conf import settings
+from django.core.exceptions import ValidationError
+from django.core.files import File
+
+from alexandria.core import models
+
+log = logging.getLogger(__name__)
+
+
+def create_document_file(
+    user: str,
+    group: str,
+    category: models.Category,
+    document_title: str,
+    file_name: str,
+    file_content: File,
+    mime_type: str,
+    file_size: int,
+    additional_document_attributes={},
+    additional_file_attributes={},
+):
+    """
+    Create a document and file with the given attributes.
+
+    This function eases the creation of documents and files by automatically setting important fields.
+    Uses `create_file` to create the file.
+    """
+    document = models.Document.objects.create(
+        title=document_title,
+        category=category,
+        created_by_user=user,
+        created_by_group=group,
+        modified_by_user=user,
+        modified_by_group=group,
+        **additional_document_attributes,
+    )
+    file = create_file(
+        document=document,
+        user=user,
+        group=group,
+        name=file_name,
+        content=file_content,
+        mime_type=mime_type,
+        size=file_size,
+        **additional_file_attributes,
+    )
+
+    return document, file
+
+
+def create_file(
+    document: models.Document,
+    user: str,
+    group: str,
+    name: str,
+    content: File,
+    mime_type: str,
+    size: int,
+    **additional_attributes
+):
+    """
+    Create a file with defaults and generate a thumbnail.
+
+    Use this instead of the normal File.objects.create to ensure that all important fields are set.
+    As well as generating a thumbnail for the file.
+    """
+    file = models.File.objects.create(
+        name=name,
+        content=content,
+        mime_type=mime_type,
+        size=size,
+        document=document,
+        encryption_status=(
+            settings.ALEXANDRIA_ENCRYPTION_METHOD
+            if settings.ALEXANDRIA_ENABLE_AT_REST_ENCRYPTION
+            else None
+        ),
+        created_by_user=user,
+        created_by_group=group,
+        modified_by_user=user,
+        modified_by_group=group,
+        **additional_attributes,
+    )
+
+    try:
+        file.create_thumbnail()
+    except ValidationError as e:  # pragma: no cover
+        log.error(
+            "Object {obj} created successfully. Thumbnail creation failed. Error: {error}".format(
+                obj=file, error=e.messages
+            )
+        )
+
+    return file