Mercurial > hg > orthanc-book

comparison Sphinx/source/plugins/python.rst @ 364:234de55ed125

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
usage of the python plugin
author Sebastien Jodogne <s.jodogne@gmail.com>
date Tue, 31 Mar 2020 18:19:14 +0200
parents 1ba75bac55fd
children 181b02cea7ab 5cb37e6b014b
comparison
equal deleted inserted replaced
363:9c28eeab2db6 364:234de55ed125
4 Python plugin for Orthanc 4 Python plugin for Orthanc
5 ========================= 5 =========================
6 6
7 .. contents:: 7 .. contents::
8 8
9 Work-in-progress. 9 Overview
10 10 --------
11 Being a plugin, the Python API has access to more features than 11
12 :ref:`Lua scripts <lua>`. 12 This plugin can be used to write :ref:`Orthanc plugins
13 13 <creating-plugins>` using the `Python programming language
14 The Python API is automatically generated from the `Orthanc plugin SDK 14 <https://en.wikipedia.org/wiki/Python_(programming_language)>`__
15 in C 15 instead of the more complex C/C++ programming languages.
16
17 Python plugins have access to more features and a more consistent SDK
18 than :ref:`Lua scripts <lua>`. The Python API is automatically
19 generated from the `Orthanc plugin SDK in C
16 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.5.7/Plugins/Include/orthanc/OrthancCPlugin.h>`__ 20 <https://hg.orthanc-server.com/orthanc/file/Orthanc-1.5.7/Plugins/Include/orthanc/OrthancCPlugin.h>`__
17 using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler 21 using the `Clang <https://en.wikipedia.org/wiki/Clang>`__ compiler
18 front-end. The coverage of the C SDK is about 75% (105 functions are 22 front-end.
19 automatically wrapped in Python out of a total of 139 functions in C). 23
24 As of initial release 1.0 of the plugin, the coverage of the C SDK is
25 about 75% (105 functions are automatically wrapped in Python out of a
26 total of 139 functions in the Orthanc SDK 1.5.7).
20 27
21 Licensing 28 Licensing
22 --------- 29 ---------
23 30
24 Pay attention to the fact that this plugin is licensed under the terms 31 Pay attention to the fact that this plugin is licensed under the terms
25 of the `AGPL license 32 of the `AGPL license
26 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__. 33 <https://en.wikipedia.org/wiki/GNU_Affero_General_Public_License>`__.
27 34
28 This has an important consequence: If you distribute Orthanc to 35 This has an important consequence: If you distribute Orthanc to
29 clients together with one Python script, or if you make an Orthanc 36 clients together with one Python script, or if you put an Orthanc
30 server equipped with one Python script available on a Web portal, you 37 server equipped with one Python script on a Web portal, you **must**
31 **must** disclose the source code of your Python script to the Orthanc 38 disclose the source code of your Python script to the Orthanc
32 community under the terms of the AGPL license. 39 community under the terms of the AGPL license.
33 40
34 We suggest you to put the source code of your Python scripts on the 41 We suggest you to put the source code of your Python scripts on the
35 dedicated `"OrthancContributed" repository on GitHub 42 dedicated `"OrthancContributed" repository on GitHub
36 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__, 43 <https://github.com/jodogne/OrthancContributed/tree/master/Plugins>`__,
39 group. 46 group.
40 47
41 Check out the :ref:`FAQ about licensing <licensing>` for more context. 48 Check out the :ref:`FAQ about licensing <licensing>` for more context.
42 49
43 50
51 Usage
52 -----
53
54 Docker
55 ......
56
57 .. highlight:: json
58
59 The most direct way of starting Orthanc together with the Python
60 plugin is through :ref:`Docker <docker>`. Let's create the file
61 ``/tmp/hello.py`` that contains the following basic Python script::
62
63 print('Hello world!')
64
65 .. highlight:: json
66
67 Let's also create the file ``/tmp/orthanc.json`` that contains the
68 following minimal :ref:`configuration for Orthanc <configuration>`::
69
70 {
71 "StorageDirectory" : "/var/lib/orthanc/db",
72 "RemoteAccessAllowed" : true,
73 "Plugins" : [
74 "/usr/local/share/orthanc/plugins"
75 ],
76 "PythonScript" : "/etc/orthanc/hello.py"
77 }
78
79 .. highlight:: bash
80
81 Given these two files, Orthanc can be started as follows::
82
83 $ docker run -p 4242:4242 -p 8042:8042 --rm \
84 -v /tmp/orthanc.json:/etc/orthanc/orthanc.json:ro \
85 -v /tmp/hello.py:/etc/orthanc/hello.py:ro \
86 jodogne/orthanc-python
87
88 .. highlight:: text
89
90 You'll see the following excerpt in the log, which indicates that the Python plugin is properly loaded::
91
92 W0331 15:48:12.990661 PluginsManager.cpp:269] Registering plugin 'python' (version mainline)
93 W0331 15:48:12.990691 PluginsManager.cpp:168] Python plugin is initializing
94 W0331 15:48:12.990743 PluginsManager.cpp:168] Using Python script "hello.py" from directory: /etc/orthanc
95 W0331 15:48:12.990819 PluginsManager.cpp:168] Program name: /usr/local/sbin/Orthanc
96 Hello world!
97
98
99 Compiling from source
100 .....................
101
102 .. highlight:: bash
103
104 The procedure to compile this plugin from source is similar to that
105 for the :ref:`core of Orthanc <compiling>`. The following commands
106 should work for most UNIX-like distribution (including GNU/Linux)::
107
108 $ mkdir Build
109 $ cd Build
110 $ cmake .. -DPYTHON_VERSION=3.7 -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release
111 $ make
112
113 Before running CMake, make sure that the Python interpreter and its
114 associated development library are installed. On Ubuntu 18.04 LTS, you
115 would for instance install packages ``libpython3.7-dev`` and
116 ``python3.7``.
117
118 The compilation will produce the shared library ``OrthancPython``,
119 that can be loaded by properly setting the ``Plugins``
120 :ref:`configuration option <configuration>` of Orthanc.
121
122 **Warning:** The shared library is only compatible with the Python
123 interpreter whose version corresponds to the value of the
124 ``PYTHON_VERSION`` argument that was given to CMake.
125
126
127 Microsoft Windows
128 .................
129
130 Pre-compiled binaries for Microsoft Windows `are also available
131 <https://www.orthanc-server.com/browse.php?path=/plugin-python>`__.
132
133 Beware that one version of the Python plugin can only be run against
134 one version of the Python interpreter. This version is clearly
135 indicated in the name of the folder.
136
137 As of release 1.0, the Orthanc project only provides pre-compiled
138 binaries for Microsoft Windows 32bit and Python 2.7. Even though this
139 version of Python is not supported anymore, it can still run on all
140 the versions of Microsoft Windows that have been released for more
141 than 10 years.
142
143 .. highlight:: text
144
145 You are of course free to compile the plugin from sources if you need
146 a more recent version. You'll have to explicitly specify the path to
147 your Python installation while invoking CMake. For instance::
148
149 C:\orthanc-python\Build> cmake .. -DPYTHON_VERSION=2.7 -DPYTHON_WINDOWS_ROOT=C:/Python27 \
150 -DSTATIC_BUILD=ON -DCMAKE_BUILD_TYPE=Release -G "Visual Studio 15 2017"
151
152
153 Configuration options
154 ---------------------
155
156 The only two configuration options that are available for this plugin
157 are the following:
158
159 * ``PythonScript`` indicates where the Python script is located. If
160 this configuration option is not provided, the Python plugin is not
161 started.
162
163 * ``PythonVerbose`` is a Boolean value to make the Python interpreter
164 verbose.
165
44 166
45 Samples 167 Samples
46 ------- 168 -------
47 169
48 Extending the REST API 170 Extending the REST API