async-siril 0.2.0

Python async wrapper around Siril astrophotography software.

async-siril

Async Siril is an asyncio based python wrapper around Siril 1.4.0 used for processing astronomy data for astrophotography and science. The library provides a pythonic interface to the Siril command line interface and all of it's commands. Scripts, processes, and workflows can be built with modern async python.

Features

• async/await based using asyncio
• code generated Siril commands from free-astro/siril-doc
• logging with structlog
• example CLI commands built for calibration, registration & stacking workflows examples
• some helpers for common logic (see async_siril.helpers)
• minimal dependencies (asyncio, structlog, psutil, attrs)
• Linux, Mac, & Windows support
• Docker support (see Dockerfile.siril)
• 93% test coverage

Requirements

• Siril installed on your system (https://www.siril.org/)
• Python 3.12 or higher
• uv or pip

Installation

uv add async-siril
# OR
pip install async-siril

Usage

Here is a simple example of how to create a master bias using the library:

import asyncio
import pathlib

from async_siril import SirilCli
from async_siril.command import setext, set32bits, convert, stack
from async_siril.command_types import fits_extension

async def main():
    current_dir = pathlib.Path(__file__).parent
    async with SirilCli(directory=current_dir) as siril:
        await siril.command(setext(fits_extension.FITS_EXT_FIT))
        await siril.command(set32bits())

        await siril.command(convert("bias"))
        await siril.command(stack("bias", out="bias_master"))

if __name__ == "__main__":
    asyncio.run(main())

For advanced use cases you can run the Siril commands directly as strings.

from async_siril import SirilCli

async def main():
    async with SirilCli() as siril:
        await siril.command("setext fits")
        await siril.command("set32bits")
        await siril.command("convert bias")
        await siril.command("stack bias bias_master")

if __name__ == "__main__":
    asyncio.run(main())

By default, any command that fails will throw an exception and shut things down. If you want to catch these types of errors and try again or handle a different way you can use the failable_command method.

from async_siril import SirilCli

async def main():
    async with SirilCli() as siril:
        await siril.command("setext fits")
        await siril.command("set32bits")
        await siril.command("convert bias")
        result = await siril.failable_command("stack bias bias_master")
        if not result:
            print("Stack failed, make a change and try again")

if __name__ == "__main__":
    asyncio.run(main())

Docker (example only)

You can use the example Dockerfile.siril to build a docker image with Siril installed. This is useful for running the examples or for running Siril commands in a container.

docker build -f Dockerfile.siril -t async-siril:latest .

Once built you can test the interface with this (runs uv run ./examples/test_siril.py):

docker run --rm -it --name siril-test async-siril:latest

Roadmap

Please see ROADMAP.md for more details.

Contributing

PRs are welcome & appreciated! See the contributing guide to get started.

FAQ

Why not use pysiril?

pysiril is a great library for interacting with Siril. However, it is not asyncio based and does not provide a pythonic interface to the Siril command line interface.

Siril just added python scripting, how is this different?

The new python scripting added to Siril is a great improvement for in-app scripts. However, sometimes you just need a simple interface for headless operations of Siril.

Acknowledgements

Siril is a fantastic piece of software and I am grateful to the free-astro team for their hard work. Special thanks to Vincent for answering questions and providing support.

License

async-siril is licensed under:

• BSD-3-Clause license (LICENSE or https://opensource.org/licenses/BSD-3-Clause)

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in async-siril by you, as defined in the BSD-3-Clause license, shall be dually licensed as above, without any additional terms or conditions.