Rename trash dir setting, clarify docs

docs/configuration.md

@@ -219,10 +219,10 @@ database, classification model, etc).
 
     Defaults to "../data/", relative to the "src" directory.
 
-#### [`PAPERLESS_TRASH_DIR=<path>`](#PAPERLESS_TRASH_DIR) {#PAPERLESS_TRASH_DIR}
+#### [`PAPERLESS_EMPTY_TRASH_DIR=<path>`](#PAPERLESS_EMPTY_TRASH_DIR) {#PAPERLESS_EMPTY_TRASH_DIR}
 
-: Instead of removing deleted documents, they are moved to this
-directory.
+: When documents are deleted (e.g. after emptying the trash) the original files will be moved here
+instead of being removed from the filesystem. Only the original version is kept.
 
     This must be writeable by the user running paperless. When running
     inside docker, ensure that this path is within a permanent volume
@@ -230,7 +230,9 @@ directory.
 
     Note that the directory must exist prior to using this setting.
 
-    Defaults to empty (i.e. really delete documents).
+    Defaults to empty (i.e. really delete files).
+
+    This setting was previously named PAPERLESS_TRASH_DIR.
 
 #### [`PAPERLESS_MEDIA_ROOT=<path>`](#PAPERLESS_MEDIA_ROOT) {#PAPERLESS_MEDIA_ROOT}
 

docs/usage.md

@@ -482,8 +482,9 @@ as "System".
 
 When you first delete a document it is moved to the 'trash' until either it is explicitly deleted or it is automatically removed after a set amount of time has passed.
 You can set how long documents remain in the trash before being automatically deleted with [`EMPTY_TRASH_DELAY`](configuration.md#EMPTY_TRASH_DELAY), which defaults
-to 30 days. Additionally you may configure a directory where deleted documents are moved to when they are finally deleted with [`PAPERLESS_TRASH_DIR`](configuration.md#PAPERLESS_TRASH_DIR).
-Note that the trash directory only stores the original file, the archive version and all database information is permanently removed once a document is fully deleted.
+to 30 days. Additionally you may configure a directory where deleted files are moved to when they are finally deleted (e.g. the trash is emptied) with
+[`PAPERLESS_EMPTY_TRASH_DIR`](configuration.md#PAPERLESS_EMPTY_TRASH_DIR). Note that the empty trash directory only stores the original file, the archive file and all database
+information is permanently removed once a document is fully deleted.
 
 ## Best practices {#basic-searching}
 

paperless.conf.example

@@ -19,7 +19,7 @@
 
 #PAPERLESS_CONSUMPTION_DIR=../consume
 #PAPERLESS_DATA_DIR=../data
-#PAPERLESS_TRASH_DIR=
+#PAPERLESS_EMPTY_TRASH_DIR=
 #PAPERLESS_MEDIA_ROOT=../media
 #PAPERLESS_STATICDIR=../static
 #PAPERLESS_FILENAME_FORMAT=

src/documents/signals/handlers.py

@@ -304,7 +304,7 @@ def set_storage_path(
 # see empty_trash in documents/tasks.py for signal handling
 def cleanup_document_deletion(sender, instance, **kwargs):
     with FileLock(settings.MEDIA_LOCK):
-        if settings.TRASH_DIR:
+        if settings.EMPTY_TRASH_DIR:
             # Find a non-conflicting filename in case a document with the same
             # name was moved to trash earlier
             counter = 0
@@ -313,7 +313,7 @@ def cleanup_document_deletion(sender, instance, **kwargs):
 
             while True:
                 new_file_path = os.path.join(
-                    settings.TRASH_DIR,
+                    settings.EMPTY_TRASH_DIR,
                     old_filebase + (f"_{counter:02}" if counter else "") + old_fileext,
                 )
 

src/documents/tests/test_file_handling.py

@@ -186,7 +186,7 @@ class TestFileHandling(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
 
     @override_settings(
         FILENAME_FORMAT="{correspondent}/{correspondent}",
-        TRASH_DIR=tempfile.mkdtemp(),
+        EMPTY_TRASH_DIR=tempfile.mkdtemp(),
     )
     def test_document_delete_trash_dir(self):
         document = Document()
@@ -203,15 +203,15 @@ class TestFileHandling(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
         Path(document.source_path).touch()
 
         # Ensure file was moved to trash after delete
-        self.assertIsNotFile(os.path.join(settings.TRASH_DIR, "none", "none.pdf"))
+        self.assertIsNotFile(os.path.join(settings.EMPTY_TRASH_DIR, "none", "none.pdf"))
         document.delete()
         empty_trash([document.pk])
         self.assertIsNotFile(
             os.path.join(settings.ORIGINALS_DIR, "none", "none.pdf"),
         )
         self.assertIsNotDir(os.path.join(settings.ORIGINALS_DIR, "none"))
-        self.assertIsFile(os.path.join(settings.TRASH_DIR, "none.pdf"))
-        self.assertIsNotFile(os.path.join(settings.TRASH_DIR, "none_01.pdf"))
+        self.assertIsFile(os.path.join(settings.EMPTY_TRASH_DIR, "none.pdf"))
+        self.assertIsNotFile(os.path.join(settings.EMPTY_TRASH_DIR, "none_01.pdf"))
 
         # Create an identical document and ensure it is trashed under a new name
         document = Document()
@@ -224,7 +224,7 @@ class TestFileHandling(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
         Path(document.source_path).touch()
         document.delete()
         empty_trash([document.pk])
-        self.assertIsFile(os.path.join(settings.TRASH_DIR, "none_01.pdf"))
+        self.assertIsFile(os.path.join(settings.EMPTY_TRASH_DIR, "none_01.pdf"))
 
     @override_settings(FILENAME_FORMAT="{correspondent}/{correspondent}")
     def test_document_delete_nofile(self):

src/paperless/checks.py

@@ -62,7 +62,7 @@ def paths_check(app_configs, **kwargs):
 
     return (
         path_check("PAPERLESS_DATA_DIR", settings.DATA_DIR)
-        + path_check("PAPERLESS_TRASH_DIR", settings.TRASH_DIR)
+        + path_check("PAPERLESS_EMPTY_TRASH_DIR", settings.EMPTY_TRASH_DIR)
         + path_check("PAPERLESS_MEDIA_ROOT", settings.MEDIA_ROOT)
         + path_check("PAPERLESS_CONSUMPTION_DIR", settings.CONSUMPTION_DIR)
     )

src/paperless/settings.py

@@ -261,7 +261,11 @@ DATA_DIR = __get_path("PAPERLESS_DATA_DIR", BASE_DIR.parent / "data")
 
 NLTK_DIR = __get_path("PAPERLESS_NLTK_DIR", "/usr/share/nltk_data")
 
-TRASH_DIR = os.getenv("PAPERLESS_TRASH_DIR")
+# Check deprecated setting first
+EMPTY_TRASH_DIR = os.getenv(
+    "PAPERLESS_TRASH_DIR",
+    os.getenv("PAPERLESS_EMPTY_TRASH_DIR"),
+)
 
 # Lock file for synchronizing changes to the MEDIA directory across multiple
 # threads.