# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1628783514 -7200
# Node ID a296fe06fd869d173e3d431d3a872909f0fa91b3
# Parent  56d48f6e52ccf359618566bf64453df7ec437a1f
Implementing a custom storage area in Python

diff -r 56d48f6e52cc -r a296fe06fd86 Sphinx/source/plugins/python.rst
--- a/Sphinx/source/plugins/python.rst	Mon Aug 09 18:29:38 2021 +0200
+++ b/Sphinx/source/plugins/python.rst	Thu Aug 12 17:51:54 2021 +0200
@@ -715,6 +715,46 @@
                     :language: python
 
 
+.. _python_storage_area:
+
+Implementing a custom storage area (new in 3.3)
+...............................................
+
+Starting with release 3.3 of the Python plugin, it is possible to
+replace the built-in storage area of Orthanc (that writes
+:ref:`attachments <metadata>` onto the filesystem in the
+``OrthancStorage`` folder by default), by providing 3 Python callbacks
+to the ``orthanc.RegisterStorageArea()`` function:
+
+* The first callback indicates how to **create** an attachment into
+  the storage area.
+
+* The second callback indicates how to **read** an attachment from the
+  storage area.
+
+* The third callback indicates how to **remove** an attachment out of
+  the storage area.
+
+This feature can be used to quickly and easily interface Orthanc with
+any `object-based storage
+<https://en.wikipedia.org/wiki/Object_storage>`__ technology available
+in Python (such as `Ceph
+<https://en.wikipedia.org/wiki/Ceph_(software)>`__ or AWS S3-like
+tools). The performance will not be as good as a C/C++ native plugin
+(cf. the :ref:`cloud storage <object-storage>`, the :ref:`PostgreSQL
+<postgresql>` and the :ref:`MySQL <mysql>` plugins), but it can be
+used for prototyping or for basic setups.
+
+Here is a full, self-explaining sample:
+
+.. literalinclude:: python/storage-area.py
+                    :language: python
+
+The ``contentType`` can be used to apply a special treatment to some
+types of attachments (typically, DICOM instances). This parameter
+takes its values from the ``orthanc.ContentType`` enumeration.
+
+
 Performance and concurrency
 ---------------------------
 
diff -r 56d48f6e52cc -r a296fe06fd86 Sphinx/source/plugins/python/storage-area.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/python/storage-area.py	Thu Aug 12 17:51:54 2021 +0200
@@ -0,0 +1,19 @@
+import orthanc
+import os
+
+def GetPath(uuid, contentType):
+    # Returns the path where to store the given attachment
+    return 'attachment-%d-%s' % (contentType, uuid)
+
+def OnCreate(uuid, contentType, data):
+    with open(GetPath(uuid, contentType), 'wb') as f:
+        f.write(data)
+
+def OnRead(uuid, contentType):
+    with open(GetPath(uuid, contentType), 'rb') as f:
+        return f.read()
+
+def OnRemove(uuid, contentType):
+    os.remove(GetPath(uuid, contentType))
+
+orthanc.RegisterStorageArea(OnCreate, OnRead, OnRemove)