From cb2df58b275ec9f477b47c0cbafa7a3cf08ac091 Mon Sep 17 00:00:00 2001 From: Daniel Quinn Date: Mon, 28 Mar 2016 19:47:11 +0100 Subject: [PATCH] Everything appears to be working --- docs/consumption.rst | 36 +++++++++++++++++++++++++++++ paperless.conf.example | 10 +++++++- scripts/post-consumption-example.sh | 25 ++++++++++++++++++++ src/documents/apps.py | 4 +++- src/documents/signals/handlers.py | 22 ++++++++++++++++++ src/paperless/settings.py | 3 +++ 6 files changed, 98 insertions(+), 2 deletions(-) create mode 100755 scripts/post-consumption-example.sh diff --git a/docs/consumption.rst b/docs/consumption.rst index 33b7f3969..0c584d0d2 100644 --- a/docs/consumption.rst +++ b/docs/consumption.rst @@ -35,6 +35,42 @@ appropriate for your use and put some documents in there. When you're ready, follow the :ref:`consumer ` instructions to get it running. +.. _consumption-directory-hook: + +Hooking into the Consumption Process +------------------------------------ + +Sometimes you may want to do something arbitrary whenever a document is +consumed. Rather than try to predict what you may want to do, Paperless lets +you execute a script of your own choosing every time a document is consumed. + +Just write a script, put it somewhere that Paperless can read & execute, and +then put the path to that script in ``paperless.conf`` with the variable name +``PAPERLESS_POST_CONSUME_SCRIPT``. + + +.. _consumption-directory-hook-variables + +What Can This Script Do? +........................ + +It's your script, so you're limited by own imagination and the laws of physics. +However, the following values are passed to the script in order: + +* Document id +* Generated file name +* Source path +* Thumbnail path +* Download URL +* Thumbnail URL +* Correspondent +* Tags + +The script can be in any language you like, but for a simple shell script +example, you can take a look at ``post-consumption-example.sh`` in the +``scripts`` directory in this project. + + .. _consumption-imap: IMAP (Email) diff --git a/paperless.conf.example b/paperless.conf.example index 9ef9a1b42..094a297cf 100644 --- a/paperless.conf.example +++ b/paperless.conf.example @@ -32,12 +32,20 @@ PAPERLESS_PASSPHRASE="secret" # have a shared secret here. PAPERLESS_SHARED_SECRET="" +# After a document is consumed, Paperless can trigger an arbitrary script if +# you like. This script will be passed a number of arguments for you to work +# with. For more information, please see the documentation. The default is +# blank, which means nothing will be executed. +#PAPERLESS_POST_CONSUME_SCRIPT="/path/to/an/arbitrary/script.sh" + + # # The following values use sensible defaults for modern systems, but if you're -# running Paperless on a low-resource machine (like a Rasberry Pi), modifying +# running Paperless on a low-resource machine (like a Raspberry Pi), modifying # some of these values may be necessary. # + # By default, Paperless will attempt to use all available CPU cores to process # a document, but if you would like to limit that, you can set this value to # an integer: diff --git a/scripts/post-consumption-example.sh b/scripts/post-consumption-example.sh new file mode 100755 index 000000000..ed0dbedd4 --- /dev/null +++ b/scripts/post-consumption-example.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash + +DOCUMENT_FILE_NAME=${1} +DOCUMENT_SOURCE_PATH=${2} +DOCUMENT_THUMBNAIL_PATH=${3} +DOCUMENT_DOWNLOAD_URL=${4} +DOCUMENT_THUMBNAIL_URL=${5} +DOCUMENT_ID=${6} +DOCUMENT_CORRESPONDENT=${7} +DOCUMENT_TAGS=${8} + +echo " + +A document with an id of ${DOCUMENT_ID} was just consumed. I know the +following additional information about it: + +* Generated File Name: ${DOCUMENT_FILE_NAME} +* Source Path: ${DOCUMENT_SOURCE_PATH} +* Thumbnail Path: ${DOCUMENT_THUMBNAIL_PATH} +* Download URL: ${DOCUMENT_DOWNLOAD_URL} +* Thumbnail URL: ${DOCUMENT_THUMBNAIL_URL} +* Correspondent: ${DOCUMENT_CORRESPONDENT} +* Tags: ${DOCUMENT_TAGS} + +" diff --git a/src/documents/apps.py b/src/documents/apps.py index e58c736c0..699b32865 100644 --- a/src/documents/apps.py +++ b/src/documents/apps.py @@ -8,9 +8,11 @@ class DocumentsConfig(AppConfig): def ready(self): from .signals import document_consumption_finished - from .signals.handlers import set_correspondent, set_tags + from .signals.handlers import ( + set_correspondent, set_tags, run_external_script) document_consumption_finished.connect(set_tags) document_consumption_finished.connect(set_correspondent) + document_consumption_finished.connect(run_external_script) AppConfig.ready(self) diff --git a/src/documents/signals/handlers.py b/src/documents/signals/handlers.py index 4e0599ccd..f3d4d3a23 100644 --- a/src/documents/signals/handlers.py +++ b/src/documents/signals/handlers.py @@ -1,5 +1,9 @@ import logging +from subprocess import Popen + +from django.conf import settings + from ..models import Correspondent, Tag @@ -51,3 +55,21 @@ def set_tags(sender, document=None, logging_group=None, **kwargs): ) document.tags.add(*relevant_tags) + + +def run_external_script(sender, document, **kwargs): + + if not settings.POST_CONSUME_SCRIPT: + return + + Popen(( + settings.POST_CONSUME_SCRIPT, + document.file_name, + document.source_path, + document.thumbnail_path, + document.download_url, + document.thumbnail_url, + str(document.id), + str(document.correspondent), + str(",".join(document.tags.all().values_list("slug", flat=True))) + )).wait() diff --git a/src/paperless/settings.py b/src/paperless/settings.py index 69dfac417..85d756bf4 100644 --- a/src/paperless/settings.py +++ b/src/paperless/settings.py @@ -227,6 +227,9 @@ PASSPHRASE = os.getenv("PAPERLESS_PASSPHRASE") # the API. SHARED_SECRET = os.getenv("PAPERLESS_SHARED_SECRET", "") +# Trigger a script after every successful document consumption? +POST_CONSUME_SCRIPT = os.getenv("PAPERLESS_POST_CONSUME_SCRIPT") + # # TODO: Remove after 0.2 #