Mercurial > hg > orthanc-book
comparison Sphinx/source/plugins/python.rst @ 364:234de55ed125
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 |