Sirilpy Python Module API |module_version| Reference ==================================================== The sirilpy python module supports communication with a running Siril instance. It can request representations of the current loaded image plus its metadata, including details of detected stars, as well as the current loaded sequence and most frame metadata. This documentation is autogenerated from version |module_version| of the python module code. It can also run Siril commands using the ``SirilInterface.cmd()`` method, and the intent is to provide a capable interface for writing advanced scripts for Siril to a level not possible with the previous simple script files. For example, scripts can now have PyQt6 or TKinter front ends using the PyQt6 or tkinter and ttkthemes modules, and they can utilise a lot of the ecosystem of Python modules including numpy, scipy, pillow and many more. .. note:: There are some restrictions around modules that require installation of system binary packages for the modules to work. In the initial module release, most methods relating to the image or sequence loaded in Siril are read-only. The intent is that the parameters of the loaded image or sequence can be obtained and used as inputs to scripts, for example for calculations or input to conditionals, but the existing mature Siril command set should in most cases be used to act on the loaded image. Thus header keywords can be set using ``cmd("update_key", "key", "value")``, and most built-in image operations can be carried out using the appropriate Siril command. The main exception to the rule of python methods providing read-only access is the ``set_image_pixeldata()`` method, which allows for setting the pixel data in the loaded image from a numpy array. This means that new pixel processing algorithms can be added using python, initially getting the pixel data from the loaded image using ``get_image_pixeldata()`` and setting it on completion using ``set_image_pixeldata()``. Similar functions are available for getting and setting pixel data from sequence frames. Dependencies ------------ The sirilpy module depends on the following: * numpy >= 1.20.0 * packaging >= 21.0 * pywin32 >= 300 (only on Windows) Siril Script Coding Guidance ---------------------------- * Unlike most python environments, Siril scripts run directly from Siril and the end user may not typically know how to access or how to use the python venv from outside Siril. This means that some tasks that are fairly trivial in typical python scenarios, such as installing packages, become harder. The user cannot be expected to access the command line and install packages themselves using ``python3 -m pip install``. * The module therefore provides the ``ensure_installed()`` method. This uses pip to ensure that modules are installed so that they can be imported. * Siril scripts should **always** provide the author's name, copyright details / license information and contact details such as a YouTube channel, website or forum where they can be contacted in regard to their script. This is advisory for independently distributed scripts and mandatory for any scripts that are submitted to the scripts repository. If you write a script, you are responsible for supporting it. * As the repository grows and the API develops, not all the scripts published will necessarily always be compatible with all versions of Siril that will be in use: * If your script uses Siril commands, you should use the ``requires`` Siril command. This can be called directly in a Siril Script File, or it can be called from a Python script using ``SirilInterface.cmd("requires", "min_version", {"max_version"})`` (max_version is optional) but can be used to ensure scripts designed for older versions of Siril no longer show as applicable to newer versions if the command syntax has changed. * If your script uses any features of the Siril python module added since the initial release, you should call the ``sirilpy.check_module_version()`` method to ensure the installed version meets the requriements of your script. The versions at which features were added will be listed in the API documentation for all features added after the initial public release. * The code that populates the Siril view of the scripts repository will automatically filter out scripts whose Siril version or python module version requirements are not met. * If new classes or methods are added to the module after its initial public release the version at which they were introduced will be annotated in the docstring and the online documentation generated from it. * Siril targets Linux, Windows and MacOS. Script writers are encouraged, where possible, to ensure that their scripts run correctly on all three OSes. Sirilpy Connection ------------------ This submodule provides the main SirilInterface class used for communication between Siril and the python script. All its members are made available at the module root level, there is no need to import connection separately. .. automodule:: sirilpy.connection :members: :undoc-members: :show-inheritance: Sirilpy Data Models ------------------- This submodule provides dataclasses to represent the main Siril data structures. Most dataclasses have corresponding deserialization methods that are used by the SirilInterface methods. All its members are made available at the module root level, there is no need to import models separately. .. automodule:: sirilpy.models :members: :undoc-members: :show-inheritance: Sirilpy Enums ------------- This module provides all the enums that are used within sirilpy. .. automodule:: sirilpy.enums :members: :undoc-members: :show-inheritance: Sirilpy Plotting ---------------- This submodule provides classes and method to access the native Siril plotting functionality. Of course, you can also use matplotlib but this submodule provides access to the same plotting capabilities as used internally within Siril for a more seamless result. All its members are made available at the module root level, there is no need to import models separately. Once populated, the PlotData object can be plotted using ``SirilInterface.xy_plot()``. .. automodule:: sirilpy.plot :members: :undoc-members: :show-inheritance: Sirilpy Utility Methods ----------------------- This submodule provides utility methods for use in Siril python scripts. The most important is ``ensure_installed()`` but there are also methods such as ``download_with_progress()`` which provides a highly robust method for downloading large files with good error recovery through a retries and resume mechanism. .. automodule:: sirilpy.utility :members: :undoc-members: :show-inheritance: Sirilpy GPU Helpers ------------------- This submodule provides helper classes to make it easier to manage GPU framework packages such as ONNX, Torch etc. for use in Siril python scripts. The landscape of these frameworks' support for different GPU architectures on different OSes is rapidly developing and the helpers aim to suggest reliable packages / configurations. This means that the proposed configurations may in some cases be conservative: the aim is to provide a good and robust level of GPU support for as many users as possible in an automated python environment rather than the absolute best, but perhaps fragile, optimisation. .. automodule:: sirilpy.gpuhelper :members: :undoc-members: :show-inheritance: Sirilpy Exceptions ------------------ This submodule provides some customized exceptions to support Siril-specific error handling. All its members are made available at the module root level, there is no need to import it separately. The sirilpy exceptions policy is as follows: * At a low level within sirilpy methods a variety of exception types may be raised (those shown below as well as exceptions raised from other modules such as struct.error). Internal exception types are all descended from SirilError and may therefore be caught using `except SirilError`. Other exception types are re-raised as a SirilError to show the method where they were generated, but the underlying error can still be seen either in a traceback or using the Exception ``__cause__`` property. * Some error types are recoverable errors such as NoImageError, NoSequenceError and CommandError. These exception types can be handled at script level (for example by showing a warning dialog reminding the user to load an image). * Other error types are typically not recoverable, such as SharedMemoryError or SirilConnectionError. .. automodule:: sirilpy.exceptions :members: :undoc-members: :show-inheritance: