Merge branch 'gacou54:main' into main

ylemarechal · Oct 23, 2023 · ccd093f · ccd093f
2 parents 3b0c012 + 6bd190c
commit ccd093f
Show file tree

Hide file tree

Showing 50 changed files with 3,060 additions and 218 deletions.
diff --git a/.gitignore b/.gitignore
@@ -7,7 +7,6 @@
 
 !README.md
 !docker-compose.yaml
-!pytest.Dockerfile
 
 !.github/
 !.github/**

diff --git a/README.md b/README.md
@@ -79,14 +79,23 @@ new_patient = pyorthanc.Patient(job.content['ID'], client)
 ```
 
 ## Notes on versioning
-PyOrthanc has been rewritten almost entirely from `0.*.*`.
-The new `Orthanc` client is now automatically generated from `https://api.orthanc-server.com/`.
-The version `*.*.` of PyOrthanc will follow Orthanc version 
-(e.g. `pyorthanc 1.11.*` is generated from the API specification of Orthanc `1.11.*`).
+
+The `Orthanc` and `AsyncOrthanc` classes are generated from `https://api.orthanc-server.com/`.
+
+Compatibility of versions between PyOrthanc and the Orthanc REST API are the following.
+Note that recent PyOrthanc versions will likely support older Orthanc version.
+
+| PyOrthanc version | Generated from                                |
+|-------------------|-----------------------------------------------|
+| \>= 1.13.0        | Orthanc API 1.12.1 with Python Plugin 4.0     |
+| 1.12.*            | Orthanc API 1.12.1                            |
+| 1.11.*            | Orthanc API 1.11.3                            |
+| 0.2.*             | Provided Google sheet from Orthanc maintainer |
+
 
 You can still use the old client with
 ```python
-from pyorthanc.deprecated.client import Orthanc
+from pyorthanc.deprecated.client import Orthanc  # Old client wrote by hand
 from pyorthanc.deprecated.client_1_11_3 import Orthanc
 ```
 
@@ -98,6 +107,9 @@ However, the automatic generation allows PyOrthanc to cover all the routes of th
 If you publish using PyOrthanc, we kindly ask that you credit us. PyOrthanc can be found on Zenodo :
 https://zenodo.org/record/7086219 .
 
+## Credits
+The `orthanc_sdk.py` has been generated from the `scripts/data/python-sdk.txt` file,
+which is from the [Python Orthanc Plugin](https://github.com/orthanc-server/orthanc-setup-samples/blob/master/python-samples/python-sdk.txt)
 
 ## Contributing
 You can contribute to this project with the following steps:

diff --git a/docker-compose.yaml b/docker-compose.yaml
@@ -1,15 +1,20 @@
 version: '3.3'
 services:
   orthanc1:
-    image: jodogne/orthanc:1.12.1
+    build:
+      dockerfile: tests/orthanc/orthanc-for-test.Dockerfile
+      context: .
+    environment:
+      PYTHON_PLUGIN_ENABLE: "true"
+      ORTHANC__PYTHON_SCRIPT: "/python/script.py"
     depends_on:
       - orthanc2
   orthanc2:
     image: jodogne/orthanc:1.12.1
   test:
     build:
       context: .
-      dockerfile: pytest.Dockerfile
+      dockerfile: tests/orthanc/pytest.Dockerfile
     depends_on:
       - orthanc1
-      - orthanc2
+      - orthanc2
diff --git a/docs/api/filtering.md b/docs/api/filtering.md
@@ -1,3 +1,7 @@
-::: pyorthanc._filtering
+::: pyorthanc.find
+    :docstring:
+    :members:
+
+::: pyorthanc.trim_patients
     :docstring:
     :members:
diff --git a/docs/api/find.md b/docs/api/find.md
@@ -1,3 +1,21 @@
-::: pyorthanc._find
+::: pyorthanc.find_patients
     :docstring:
-    :members:
+    :members:
+
+::: pyorthanc.find_studies
+    :docstring:
+    :members:
+
+::: pyorthanc.find_series
+    :docstring:
+    :members:
+
+::: pyorthanc.find_instances
+    :docstring:
+    :members:
+
+::: pyorthanc.query_orthanc
+    :docstring:
+    :members:
+
+::: pyorthanc._find.DEFAULT_RESOURCES_LIMIT
diff --git a/docs/api/jobs.md b/docs/api/jobs.md
@@ -0,0 +1,14 @@
+::: pyorthanc.Job
+    options:
+        members: True
+    :docstring:
+    :members:
+
+
+::: pyorthanc.jobs.State
+    :docstring:
+    :members:
+
+::: pyorthanc.jobs.ErrorCode
+    :docstring:
+    :members:
diff --git a/docs/api/modality.md b/docs/api/modality.md
@@ -0,0 +1,11 @@
+::: pyorthanc.Modality
+    options:
+        members: true
+    :docstring:
+    :members:
+
+## RemoteModality
+RemoteModality is an alias for Modality
+```python
+RemoteModality = Modality
+```
diff --git a/docs/api/orthanc_sdk.md b/docs/api/orthanc_sdk.md
@@ -0,0 +1,40 @@
+# Orthanc SDK
+
+The `orthanc_sdk` is useful when developing with the Orthanc's Python Plugin, 
+it exposes `orthanc` module when available (i.e. used as an Orthanc script), 
+or expose the functions/classes signatures when not for linting and autocomplete.
+
+Use it the same way you would use the Python Plugin:
+
+```python
+from pyorthanc import orthanc_sdk
+
+def on_get(output: orthanc_sdk.RestOutput, *_, **__):
+    output.AnswerBuffer('ok', 'text/plain')
+
+orthanc_sdk.RegisterRestCallback('/test', on_get)
+```
+
+
+## How it works
+When developing importing the Orthanc Python Plugin with `import orthanc` will raise a `ModuleNotFoundError`.
+This where the `orthanc_sdk` submodule is interesting. When `orthanc` is available, it uses it.
+When not, `orthanc_sdk` expose mock functions/classes of everything available from `orthanc`, however, these functions/classes does nothing.
+
+```python
+try:
+    from orthanc import *
+
+except ModuleNotFoundError:
+    """Orthanc SDK methods wrapped in python (plugin version 4.0)"""
+    ...
+```
+
+
+## Reference
+
+::: pyorthanc.orthanc_sdk
+    options:
+        members: true
+    :docstring:
+    :members:
diff --git a/docs/api/remote.md b/docs/api/remote.md
diff --git a/docs/api/resources/instance.md b/docs/api/resources/instance.md
@@ -1,3 +1,5 @@
 ::: pyorthanc.Instance
+    options:
+        members: true
     :docstring:
     :members:
diff --git a/docs/api/resources/patient.md b/docs/api/resources/patient.md
@@ -1,3 +1,5 @@
 ::: pyorthanc.Patient
+    options:
+        members: true
     :docstring:
     :members:
diff --git a/docs/api/resources/resource.md b/docs/api/resources/resource.md
@@ -1,3 +1,5 @@
 ::: pyorthanc._resources.Resource
+    options:
+        members: true
     :docstring:
     :members:
diff --git a/docs/api/resources/series.md b/docs/api/resources/series.md
@@ -1,3 +1,5 @@
 ::: pyorthanc.Series
+    options:
+        members: true
     :docstring:
     :members:
diff --git a/docs/api/resources/study.md b/docs/api/resources/study.md
@@ -1,3 +1,5 @@
 ::: pyorthanc.Study
+    options:
+        members: true
     :docstring:
     :members:
diff --git a/docs/index.md b/docs/index.md
@@ -52,6 +52,17 @@ for patient in patients:
                 pydicom_ds = instance.get_pydicom()
 ```
 
+Use the `orthanc_sdk` when developing with the Orthanc's Python Plugin
+
+```python
+from pyorthanc import orthanc_sdk
+
+def on_get(output: orthanc_sdk.RestOutput, *_, **__):
+    output.AnswerBuffer('ok', 'text/plain')
+
+orthanc_sdk.RegisterRestCallback('/test', on_get)
+```
+
 ## [First steps](tutorial/quickstart.md#first-steps)
 ### [Getting started](tutorial/quickstart.md#getting-started)
 * [Import pyorthanc library](tutorial/quickstart.md#import-pyorthanc-library)
@@ -64,9 +75,9 @@ for patient in patients:
 * [Access instance informations](tutorial/quickstart.md#access-instance-informations)
 ### [Advanced examples](tutorial/advanced.md)
 * [Transfer data from a PACS to a Orthanc server](tutorial/advanced.md#transfer-data-from-a-pacs-to-a-orthanc-server)
-### [Releases](releases/releases.md)
-* [Lastest release : 1.12.1](releases/releases.md#lastest-release-1121)
-* [Release 1.11.5](releases/releases.md#release-1115)
+### [Releases](releases.md)
+* [Lastest release : 1.12.1](releases.md#lastest-release-1121)
+* [Release 1.11.5](releases.md#release-1115)
 ## [Contacts](contacts.md#contacts)
 * [Maintainers Team](contacts.md#maintainers-team)
 * [Useful links](contacts.md#useful-links)

diff --git a/docs/releases/releases.md → docs/releases.md b/docs/releases/releases.md → docs/releases.md
@@ -1,18 +1,37 @@
 # Releases 
 
-## Lastest release : 1.12.1
+## PyOrthanc 1.13.0
+Features:
+- Add a new submodule `orthanc_sdk`. 
+  - When used in an Orthanc Python script, it acts as the same as `import orthanc` 
+  - When used outside Orthanc (i.e. when developing a script), expose the same signature as `import orthanc`
+    - This adds autocomplete and linting
+  - Use it with `from pyorthanc import orthanc_sdk`
 
+
+## PyOrthanc 1.12.3
+Fix:
+- Fix bug that occurs when `Orthanc(return_raw_response=True)` is used in functions/classes
+where returning a `httpx.Response` object is not possible.
+
+
+## PyOrthanc: 1.12.2
+Fix:
+- Fix bug where an error is raised at import pyorthanc when using Python 3.8 
+
+
+## PyOrthanc: 1.12.1
 The Orthanc client has been regenerated on the Orthanc 1.12.1 version (source of the [changelist](https://hg.orthanc-server.com/orthanc/file/Orthanc-1.12.1/NEWS)).
 
-From 1.12.1:
+From Orthanc API 1.12.1:
 
     - API version upgraded to 21
     - "/tools/create-dicom" can now be used to create Encapsulated 3D
     - Manufacturing Model IODs (MTL, OBJ, or STL)
     - Added a route to delete the output of an asynchronous job (right now
     - only for archive jobs): e.g. DELETE /jobs/../archive
 
-From 1.12.0:
+From Orthanc API 1.12.0:
 
     - New URIs "/.../{id}/labels/{label}" to test/set/remove labels
     - "/patients/{id}", "/studies/{id}", "/series/{id}" and "/instances/{id}"
@@ -31,9 +50,8 @@ Details:
 
     - All tests made with unittest has been refactored to use pytest
 
-## Release 1.11.5 
-
 
+## PyOrthanc 1.11.5 
 PyOrthanc v1.11.5 follow Orthanc version 1.11.3.
 
 This release mostly improves the `find()` function.  It now takes an `Orthanc` object rather than an URL. This allows better control of the configuration for the connection to the Orthanc server.

diff --git a/docs/releases/roadmap.md b/docs/releases/roadmap.md
diff --git a/docs/tutorial/quickstart.md b/docs/tutorial/quickstart.md
@@ -130,6 +130,24 @@ __Note__ that this function may take a while to run since each resource level is
 Using `find()` on large Orthanc server is not recommended.
 
 
+#### Develop with the Orthanc's Python Plugin
+The `orthanc_sdk` is useful when developing with the Orthanc's Python Plugin,
+it exposes `orthanc` module when available (i.e. used as an Orthanc script),
+or expose the functions/classes signatures when not for linting and autocomplete.
+
+Use it the same way you would use the Python Plugin:
+
+```python
+# Has the same signature as `import orthanc`
+from pyorthanc import orthanc_sdk 
+
+def on_get(output: orthanc_sdk.RestOutput, *_, **__):
+    output.AnswerBuffer('ok', 'text/plain')
+
+orthanc_sdk.RegisterRestCallback('/test', on_get)
+```
+
+
 ## Full basic examples
 
 Be sure that Orthanc is running. The default URL (if running locally) is `http://localhost:8042`.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -17,20 +17,20 @@ nav:
   - 'Api Reference':
       'Orthanc': 'api/client.md'
       'Asynchronous Orthanc': 'api/async_client.md'
-      'Resource': 'api/resources/resource.md'
+      'Orthanc SDK': 'api/orthanc_sdk.md'
       'Patient': 'api/resources/patient.md'
       'Study': 'api/resources/study.md'
       'Series': 'api/resources/series.md'
       'Instance': 'api/resources/instance.md'
       'Find': 'api/find.md'
       'Filtering': 'api/filtering.md'
-      'Remote': 'api/remote.md'
+      'Modality': 'api/modality.md'
+      'Jobs': 'api/jobs.md'
       'Util': 'api/util.md'
+      'Resource': 'api/resources/resource.md'
+      'Retrieve': 'api/retrieve.md'
 
-
-  - 'Releases & Roadmap':
-    - 'Releases': 'releases/releases.md'
-
+  - 'Releases': 'releases.md'
 
   - 'More informations':
     - 'Contributing': 'contributing.md'
@@ -49,6 +49,7 @@ plugins:
       handlers:
         python:
           options:
+            show_root_heading: true
             docstring_style: numpy
       default_handler: python
 #  - toc-md:

diff --git a/pyorthanc/_filtering.py b/pyorthanc/_filtering.py
@@ -2,12 +2,13 @@
 import warnings
 from typing import Callable, Dict, List, Optional, Union
 
-from .async_client import AsyncOrthanc
-from .client import Orthanc
+from . import util
 from ._resources.instance import Instance
 from ._resources.patient import Patient
 from ._resources.series import Series
 from ._resources.study import Study
+from .async_client import AsyncOrthanc
+from .client import Orthanc
 from .util import async_to_sync
 
 
@@ -56,6 +57,9 @@ def find(orthanc: Union[Orthanc, AsyncOrthanc],
     List[Patient]
         List of patients that respect .
     """
+    # In this function, client that return raw responses are not supported.
+    orthanc = util.ensure_non_raw_response(orthanc)
+
     if isinstance(orthanc, AsyncOrthanc):
         return asyncio.run(_async_find(
             async_orthanc=orthanc,