changeset 364:234de55ed125

usage of the python plugin
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 31 Mar 2020 18:19:14 +0200
parents 9c28eeab2db6
children 49202601d0c8
files Sphinx/source/_templates/layout.html Sphinx/source/developers/creating-plugins.rst Sphinx/source/plugins/python.rst Sphinx/source/users/docker.rst
diffstat 4 files changed, 148 insertions(+), 14 deletions(-) [+]
line wrap: on
line diff
--- a/Sphinx/source/_templates/layout.html	Tue Mar 31 17:27:55 2020 +0200
+++ b/Sphinx/source/_templates/layout.html	Tue Mar 31 18:19:14 2020 +0200
@@ -17,7 +17,7 @@
     </p>
     <p>
 
-      &copy; Copyright 2015-2020, University Hospital of Liège and Osimis, Belgium, and the Orthanc community<br/>
+      &copy; Copyright 2015-2020, University Hospital of Liège and Osimis S.A., Belgium, and the Orthanc community<br/>
       The Orthanc Book is licensed under
       <a href="http://creativecommons.org/licenses/by-sa/4.0/" target="_blank">Creative 
         Commons CC-BY-SA 4.0</a>.<br/>
--- a/Sphinx/source/developers/creating-plugins.rst	Tue Mar 31 17:27:55 2020 +0200
+++ b/Sphinx/source/developers/creating-plugins.rst	Tue Mar 31 18:19:14 2020 +0200
@@ -16,8 +16,13 @@
 <https://sdk.orthanc-server.com/>`__ and must be written in C or
 C++. They must also fullfil the terms of the `GPLv3 license
 <http://www.gnu.org/licenses/quick-guide-gplv3.en.html>`__ that is
-used by the core of Orthanc. Here are some resources about creating
-plugins:
+used by the core of Orthanc.
+
+For developers who are more familiar with Python, it is also possible
+to create plugins using this simpler language. Check out the
+:ref:`dedicated Python plugin <python-plugin>`.
+
+Here are some resources about creating C/C++ plugins:
 
 * Sample code for plugins can be found `in the official Orthanc
   repository
--- a/Sphinx/source/plugins/python.rst	Tue Mar 31 17:27:55 2020 +0200
+++ b/Sphinx/source/plugins/python.rst	Tue Mar 31 18:19:14 2020 +0200
@@ -6,17 +6,24 @@
 
 .. contents::
 
-Work-in-progress.
+Overview
+--------
+   
+This plugin can be used to write :ref:`Orthanc plugins
+<creating-plugins>` using the `Python programming language
+<https://en.wikipedia.org/wiki/Python_(programming_language)>`__
+instead of the more complex C/C++ programming languages.
 
-Being a plugin, the Python API has access to more features than
-:ref:`Lua scripts <lua>`. 
-
-The Python API is automatically generated from the `Orthanc plugin SDK
-in C
+Python plugins have access to more features and a more consistent SDK
+than :ref:`Lua scripts <lua>`. The Python API is automatically
+generated from the `Orthanc plugin SDK in C
 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.5.7/Plugins/Include/orthanc/OrthancCPlugin.h>`__
 using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler
-front-end.  The coverage of the C SDK is about 75% (105 functions are
-automatically wrapped in Python out of a total of 139 functions in C).
+front-end.
+
+As of initial release 1.0 of the plugin, the coverage of the C SDK is
+about 75% (105 functions are automatically wrapped in Python out of a
+total of 139 functions in the Orthanc SDK 1.5.7).
 
 Licensing
 ---------
@@ -26,9 +33,9 @@
 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__.
 
 This has an important consequence: If you distribute Orthanc to
-clients together with one Python script, or if you make an Orthanc
-server equipped with one Python script available on a Web portal, you
-**must** disclose the source code of your Python script to the Orthanc
+clients together with one Python script, or if you put an Orthanc
+server equipped with one Python script on a Web portal, you **must**
+disclose the source code of your Python script to the Orthanc
 community under the terms of the AGPL license.
 
 We suggest you to put the source code of your Python scripts on the
@@ -41,6 +48,121 @@
 Check out the :ref:`FAQ about licensing <licensing>` for more context.
 
 
+Usage
+-----
+
+Docker
+......
+
+.. highlight:: json
+
+The most direct way of starting Orthanc together with the Python
+plugin is through :ref:`Docker <docker>`. Let's create the file
+``/tmp/hello.py`` that contains the following basic Python script::
+
+  print('Hello world!')
+
+.. highlight:: json
+
+Let's also create the file ``/tmp/orthanc.json`` that contains the
+following minimal :ref:`configuration for Orthanc <configuration>`::
+                 
+  {
+    "StorageDirectory" : "/var/lib/orthanc/db",
+    "RemoteAccessAllowed" : true,
+    "Plugins" : [ 
+      "/usr/local/share/orthanc/plugins"
+    ],
+    "PythonScript" : "/etc/orthanc/hello.py"
+  }
+    
+.. highlight:: bash
+
+Given these two files, Orthanc can be started as follows::
+               
+  $ docker run -p 4242:4242 -p 8042:8042 --rm \
+    -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro \
+    -v /tmp/hello.py:/etc/orthanc/hello.py:ro \
+    jodogne/orthanc-python
+
+.. highlight:: text
+
+You'll see the following excerpt in the log, which indicates that the Python plugin is properly loaded::
+
+  W0331 15:48:12.990661 PluginsManager.cpp:269] Registering plugin 'python' (version mainline)
+  W0331 15:48:12.990691 PluginsManager.cpp:168] Python plugin is initializing
+  W0331 15:48:12.990743 PluginsManager.cpp:168] Using Python script "hello.py" from directory: /etc/orthanc
+  W0331 15:48:12.990819 PluginsManager.cpp:168] Program name: /usr/local/sbin/Orthanc
+  Hello world!
+
+
+Compiling from source
+.....................
+
+.. highlight:: bash
+
+The procedure to compile this plugin from source is similar to that
+for the :ref:`core of Orthanc <compiling>`. The following commands
+should work for most UNIX-like distribution (including GNU/Linux)::
+
+  $ mkdir Build
+  $ cd Build
+  $ cmake .. -DPYTHON_VERSION=3.7 -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
+  $ make
+
+Before running CMake, make sure that the Python interpreter and its
+associated development library are installed. On Ubuntu 18.04 LTS, you
+would for instance install packages ``libpython3.7-dev`` and
+``python3.7``.
+   
+The compilation will produce the shared library ``OrthancPython``,
+that can be loaded by properly setting the ``Plugins``
+:ref:`configuration option <configuration>` of Orthanc.
+
+**Warning:** The shared library is only compatible with the Python
+interpreter whose version corresponds to the value of the
+``PYTHON_VERSION`` argument that was given to CMake.
+     
+  
+Microsoft Windows
+.................
+
+Pre-compiled binaries for Microsoft Windows `are also available
+<https://www.orthanc-server.com/browse.php?path=/plugin-python>`__.
+
+Beware that one version of the Python plugin can only be run against
+one version of the Python interpreter. This version is clearly
+indicated in the name of the folder.
+
+As of release 1.0, the Orthanc project only provides pre-compiled
+binaries for Microsoft Windows 32bit and Python 2.7. Even though this
+version of Python is not supported anymore, it can still run on all
+the versions of Microsoft Windows that have been released for more
+than 10 years.
+
+.. highlight:: text
+
+You are of course free to compile the plugin from sources if you need
+a more recent version. You'll have to explicitly specify the path to
+your Python installation while invoking CMake. For instance::
+
+  C:\orthanc-python\Build> cmake .. -DPYTHON_VERSION=2.7 -DPYTHON_WINDOWS_ROOT=C:/Python27 \
+                                    -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release -G "Visual Studio 15 2017"
+
+
+Configuration options
+---------------------
+
+The only two configuration options that are available for this plugin
+are the following:
+
+* ``PythonScript`` indicates where the Python script is located.  If
+  this configuration option is not provided, the Python plugin is not
+  started.
+
+* ``PythonVerbose`` is a Boolean value to make the Python interpreter
+  verbose.
+  
 
 Samples
 -------
--- a/Sphinx/source/users/docker.rst	Tue Mar 31 17:27:55 2020 +0200
+++ b/Sphinx/source/users/docker.rst	Tue Mar 31 18:19:14 2020 +0200
@@ -86,6 +86,13 @@
 
   $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins
 
+If you have an interest in the :ref:`Python plugin <python-plugin>`,
+you can use the ``orthanc-python`` image. The latter image is a
+heavier version of the ``orthanc-plugins`` image, as it embeds the
+Python 3.7 interpreter. Here is how to start this image::
+
+  $ docker run -p 4242:4242 -p 8042:8042 --rm jodogne/orthanc-plugins
+  
 
 Fine-tuning the configuration
 -----------------------------