Package pyOsirix
Python package pyOsirix provides types, functions, and a command-line
interface for sending requests and receiving responses from Osirix using gRPC messaging protocol. It provides a pythonic-interface of working with Osirix in a user-friendly, industry-standard open format.
pyOsirix provides the following interfaces to interact with Osirix:
- modules (including submodules),
- functions (including methods, properties, coroutines …),
- classes, and
- variables (including class variables, and instance variables).
gRPC is an open source, high performance HTTPS remote procedure call framework developed byGoogle that can run on any enabled environment (https://grpc.io/). It uses language-independentprotocol buffers to serialize the message interchange process, allowing server-client communicationbetween different systems and software languages.
The figure above presents an illustration of the communication pathway between a Linux client running a set of Python commands, sending requests to the server, and waiting for a response before continuing with operation.
Through this mechanisms is possible to query data from OsiriX, process those data in any desired way, and subsequentlysend a request back to OsiriX to view the result (in this case as an automatically generated region of interest). A key advantage of this system is that with negligible overhead for the developer, it is possible to implement client messages in any language supported by gRPC (as of writing thisarticle, this includes C#, C++, Dart, Go, Java, Kotlin, Node.js, Objective-C, PHP, Python and Ruby).
In addition, gRPC also enables secure transfer of messages over a network via the SSL encryption protocol. Such approaches are vital when running an OsiriXgrpc client over a network rather than asa local client on the same machine as the OsiriX server
Documentation is extracted from live objects' docstrings
using Python's __doc__ attribute. Documentation for
variables is found by examining objects' abstract syntax trees.
What objects are documented?
pyOsirix uses pdoc to generate its documentation. pdoc only extracts public API documentation.
Code objects (modules, variables, functions, classes, methods) are considered
public in the modules where they are defined (vs. imported from somewhere else)
as long as their identifiers don't begin with an underscore ( _ ).
If a module defines __all__, then only the identifiers contained
in this list are considered public, regardless of where they were defined.
This can be fine-tuned through __pdoc__ dict.
Where does pdoc get documentation from?
In Python, objects like modules, functions, classes, and methods
have a special attribute __doc__ which contains that object's
documentation string (docstring).
For example, the following code defines a function with a docstring
and shows how to access its contents:
>>> def test():
... """This is a docstring."""
... pass
...
>>> test.__doc__
'This is a docstring.'
It's pretty much the same with classes and modules. See PEP-257 for Python docstring conventions.
These docstrings are set as descriptions for each module, class,
function, and method listed in the documentation produced by pdoc.
pdoc extends the standard use of docstrings in Python in two
important ways: by allowing methods to inherit docstrings, and
by introducing syntax for docstrings for variables.