.. index:: ! PyCPL -- Python Language Bindings for CPL

.. _pycpl-home:

PyCPL -- Python Language Bindings for CPL
=========================================

*PyCPL* provides Python3 language bindings for the complete programming API of
the `ESO Common Pipeline Library (CPL) <https://www.eso.org/sci/software/cpl/>`__
toolkit, including the CPL plugin interface.

Using *PyCPL* it is possible to run the recipes of all available
`ESO instrument pipeline packages <https://www.eso.org/sci/software/pipelines/>`__ from
Python (from scripts or the interpreter prompt) and makes it possible to write recipes
in Python which are compliant with ESO standards. *PyCPL* is complemented by *PyEsoRex*,
a command line tool which can serve as a drop-in replacement of *EsoRex*, which
can execute both, existing pipeline recipes implemented using the CPL C API, and
recipes implemented using the *PyCPL* Python API.


.. _pycpl-release_notes:

Release Notes
-------------

The latest release is *PyCPL* |release|.

PyCPL 1.0.4 (*2026-06-10*):
   This is a maintenance release fixing a number of issues which have been reported.
   See the *PyCPL* ChangeLog for details. This release *requires* CPL 7.4 or newer!

PyCPL 1.0.3 (*2025-05-21*):
   This is a maintenance release fixing a number of issues which have been reported.
   See the *PyCPL* ChangeLog for details.

.. _pycpl-quick_installation:

Installation
------------

Pre-built packages of *PyCPL* and *PyEsoRex* are available for Fedora Linux and MacPorts from the *ESO repositories*.
See :ref:`userguide.installation.installation-from-rpm` or :ref:`userguide.installation.installation-from-macports` for
the respective installation instructions.

For other platforms *PyCPL* and *PyEsoRex* can be installed from source. Refer to
:ref:`userguide.installation.installation-from-sources` for software prerequisites and detailed instructions
on installing the source packages. Go to :ref:`pycpl-quick_download` for getting the source packages.


.. _pycpl-quick_download:

Downloads
---------

The latest *PyCPL* and *PyEsoRex* source packages are available here: 

- `PyCPL <https://ftp.eso.org/pub/dfs/pipelines/libraries/pycpl/pycpl-1.0.4.tar.gz>`__ :bdg-link-secondary-line:`SHA-256 <https://ftp.eso.org/pub/dfs/pipelines/libraries/pycpl/pycpl-1.0.4.sha256>`
- `PyEsoRex <https://ftp.eso.org/pub/dfs/pipelines/libraries/pyesorex/pyesorex-1.0.4.tar.gz>`__ :bdg-link-secondary-line:`SHA-256 <https://ftp.eso.org/pub/dfs/pipelines/libraries/pyesorex/pyesorex-1.0.4.sha256>`

Software prerequisites and detailed instructions on installing the source packages can be found in
:ref:`userguide.installation.installation-from-sources`.


.. _pycpl-known_issues:

Known Issues
------------
For any known issues please refer to the Section :ref:`userguide.known-issues`
of the user guide.


.. _pycpl-getting_support:

Getting Support
---------------

.. _ESO Operations Helpdesk: https://support.eso.org
.. _ESO JIRA: https://jira.eso.org

To report bugs and documentation issues, and to get support for *PyCPL* and *PyEsoRex* in
general, please create a ticket at the `ESO Operations Helpdesk`_.

Bug reports should contain the following information:

- PyCPL version
- PyEsoRex version (if applicable)
- Python version
- Operating system and version
- Type of installation (system-wide, user, python virtual environment, local build, RPM, MacPorts, etc.)
- If possible, the description how the issue can be reproduced.

Users who have access to the `ESO JIRA`_ ticket system (ESO internal and instrument consortia) are
encouraged to create tickets for bug reports or feature requests, selecting

- :menuselection:`Project --> PIPE`
- :menuselection:`Component --> CPL`

and the appropriate *Issue type* (Bug, Doc Bug, New Feature, or Improvement)
in the dialog.

Feature Requests and Contributions
----------------------------------

.. _CPL team: cplhelp@eso.org

Contributions and suggestions improving **PyCPL** and **PyEsoRex** are always welcome!

To submit feature requests, suggest improvments, or contribute to the project, please
send an email to the `CPL team`_ starting the *subject* with **PyCPL:** and **PyEsoRex:**,
respectively.

.. _pycpl-faqs:

Frequently Asked Questions
--------------------------

:Q: Can *PyCPL* Python recipes be included in instrument pipeline packages?
:A: Yes!

.. toctree::
   :maxdepth: 2
   :hidden:

   userguide
   reference

.. toctree::
   :hidden:

   genindex
