feat: support for node custom IDs (issue#325) (#331)

Author: ciur

changelog.md

@@ -7,6 +7,7 @@
 ### Adds
 
 - Support for OpenLDAP (RFC 4510) authentication
+- Support for node's custom IDs [Issue#325](https://github.com/papermerge/papermerge-core/issues/325)
 
 ### Fixes
 

papermerge/core/models/document.py

@@ -103,14 +103,19 @@ def create_document(
         page_count=0,
         file_name=None,
         parent=None,
+        id=None,
         **kwargs
     ):
-        doc = Document(
+        attrs = dict(
             title=title,
             lang=lang,
             parent=parent,
             **kwargs
         )
+        if id is not None:
+            attrs['id'] = id
+
+        doc = Document(**attrs)
         doc.save()
 
         document_version = DocumentVersion(

papermerge/core/routers/nodes.py

@@ -79,22 +79,35 @@ def create_node(
     pynode: PyCreateFolder | PyCreateDocument,
     user: schemas.User = Depends(get_current_user)
 ) -> PyFolder | PyDocument:
-
+    """Creates a node
+
+    Node's `ctype` may be either `folder` or `document`.
+    Optionally you may pass ID attribute. If ID is present and has
+    non-emtpy UUID value, then newly create node will be assigned this
+    custom ID.
+    If node has `parent_id` empty then node will not be accessible to user.
+    The only nodes with `parent_id` set to empty value are "user custom folders"
+    like Home and Inbox.
+    """
     try:
         if pynode.ctype == "folder":
-            node = Folder.objects.create(
+            attrs = dict(
                 title=pynode.title,
                 user_id=user.id,
                 parent_id=pynode.parent_id
             )
+            if pynode.id:
+                attrs['id'] = pynode.id
+
+            node = Folder.objects.create(**attrs)
             klass = PyFolder
         else:
             # if user does not specify document's language, get that
             # value from user preferences
             if pynode.lang is None:
                 pynode.lang = settings.OCR__DEFAULT_LANGUAGE
 
-            node = Document.objects.create_document(
+            attrs = dict(
                 title=pynode.title,
                 lang=pynode.lang,
                 user_id=user.id,
@@ -103,6 +116,10 @@ def create_node(
                 page_count=0,
                 file_name=pynode.title
             )
+            if pynode.id:
+                attrs['id'] = pynode.id
+
+            node = Document.objects.create_document(**attrs)
             klass = PyDocument
     except IntegrityError:
         raise HTTPException(

papermerge/core/schemas/documents.py

@@ -126,12 +126,27 @@ def tags_validator(cls, value):
 
 
 class CreateDocument(BaseModel):
+    # UUID may be present to allow custom IDs
+    # See https://github.com/papermerge/papermerge-core/issues/325
+    id: UUID | None = None
     title: str
     ctype: Literal["document"]
     parent_id: UUID | None
     lang: str | None = None
     file_name: str | None = None
 
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "title": "invoice.pdf",
+                    "ctype": "document",
+                    "parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+                }
+            ]
+        }
+    }
+
 
 class Thumbnail(BaseModel):
     url: str

papermerge/core/schemas/folders.py

@@ -37,6 +37,21 @@ def tags_validator(cls, value):
 
 
 class CreateFolder(BaseModel):
+    # UUID may be present to allow custom IDs
+    # See https://github.com/papermerge/papermerge-core/issues/325
+    id: UUID | None = None
     title: str
     ctype: Literal["folder"]
     parent_id: UUID | None
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "title": "My Documents",
+                    "ctype": "folder",
+                    "parent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+                },
+            ]
+        }
+    }

tests/core/views/test_nodes.py

@@ -1,4 +1,5 @@
 import json
+import uuid
 
 import pytest
 from django.urls import reverse
@@ -123,6 +124,58 @@ def test_nodes_move(self):
         assert response.status_code == 200, response.data
 
 
+@pytest.mark.django_db(transaction=True)
+def test_create_document_with_custom_id(auth_api_client: AuthTestClient):
+    """
+    Allow custom ID attribute: if ID attribute is set, then node will set it
+    as its ID.
+    """
+    assert Document.objects.count() == 0
+
+    user = auth_api_client.user
+
+    custom_id = uuid.uuid4()
+
+    payload = dict(
+        id=str(custom_id),
+        ctype='document',
+        # "lang" attribute is not set
+        title='doc1.pdf',
+        parent_id=str(user.home_folder.pk)
+    )
+
+    response = auth_api_client.post('/nodes', json=payload)
+
+    assert response.status_code == 201, response.content
+    assert Document.objects.count() == 1
+    doc = Document.objects.first()
+    assert doc.id == custom_id
+
+
+@pytest.mark.django_db(transaction=True)
+def test_create_folder_with_custom_id(auth_api_client: AuthTestClient):
+    """
+    Allow custom ID attribute: if ID attribute is set, then node will set it
+    as its ID.
+    """
+    user = auth_api_client.user
+
+    custom_id = uuid.uuid4()
+
+    payload = dict(
+        id=str(custom_id),
+        ctype='folder',
+        title='My Documents',
+        parent_id=str(user.home_folder.pk)
+    )
+
+    response = auth_api_client.post('/nodes', json=payload)
+    folder = Folder.objects.get(title='My Documents')
+
+    assert response.status_code == 201, response.content
+    assert folder.id == custom_id
+
+
 @pytest.mark.django_db(transaction=True)
 def test_create_document(auth_api_client: AuthTestClient):
     """