Using ``csst_common``
=====================

Some usages of the functions / classes in ``csst_common``. (To be updated)

``csst_common.data_manager.CsstMsDataManager``
----------------------------------------------

A class that helps developers to access simulation files.

.. code-block:: python

    from csst_common.data_manager import CsstMsDataManager
    # for full basic initialization
    dm_mbi = CsstMsDataManager(
        ver_sim="C5.2",                 # version of simulation, "C5.2" is the latest
        dir_l0="",                      # the L0/input directory
        dir_l1="",                      # the L1/output directory
        dir_pcref="",                   # position calibration reference (will be deprecated)
        path_aux="",                    # aux file paths (master bias, dark, flat)
        assert_all_detectors=False,     # if True, assert all detectors are available
        datatype="mbi",                 # "mbi" or "sls"
    )

.. code-block:: python

    # for a quick start ()
    dm_mbi = CsstMsDataManager.quickstart(
        ver_sim="C5.2",
        datatype="mbi",
        dir_l1=".",
        exposure_id=100                 # the 100th exposure
    )

.. code-block:: python

    # access L0 directory
    dm_mbi.dir_l0
    # access L1 directory
    dm_mbi.dir_l1
    # access dir_pcref
    dm_mbi.dir_pcref
    # access path_aux
    dm_mbi.path_aux
    # access ver_sim
    dm_mbi.ver_sim
    # access target detectors
    dm_mbi.target_detectors
    # access available detectors
    dm_mbi.available_detectors
    # define an L1 file (detector-specified)
    dm_mbi.l1_detector(detector=6)
    # define an L1 file (non-detector-specified)
    dm_mbi.l1_file("flipped_image.fits")

.. code-block:: python

    # to get bias
    dm_mbi.get_bias()
    # to get dark
    dm_mbi.get_dark()
    # to get flat
    dm_mbi.get_flat()


``csst_common.logger.get_logger()``
-----------------------------------

Get the default configured ``logging.Logger``.


.. code-block:: python
    :linenos:

    from csst_common.logger import get_logger
    logger = get_logger()

.. warning::
    Developers should NOT use ``print`` function extensively in code.
    Generally ``print`` can be replaced with ``logger.debug("msg")``.
    For important information, use ``logger.info("msg")``.
    For warnings, use ``logger.warning("msg")``.
    For errors, use ``logger.error("msg")``.
    Conf https://docs.python.org/3/library/logging.html for more information
    about the usage of ``logging.Logger``.


``csst_common.status.CsstStatus``
---------------------------------

Developers should use ``csst_common.status.CsstStatus`` to return the
status of their interfaces.

.. code-block:: python
    :linenos:

    from csst_common.status import CsstStatus
    # presently 3 kinds of status are available, they are
    CsstStatus.PERFECT
    CsstStatus.WARNING
    CsstStatus.ERROR


An example interface
--------------------

We recommend our developers to use the code structure used in the example interfaces,
e.g., ``process_single_image`` and ``process_multiple_images``.
The example code is shown below.

Source code
^^^^^^^^^^^

.. literalinclude:: example_interface.py
    :caption: ``example_interface.py``
    :emphasize-lines: 36-40,81-82,85-86,89-90,94-97,143-144,147,150-151,154-155
    :linenos:
    :language: python


Rendered ``docstring``
^^^^^^^^^^^^^^^^^^^^^^

.. automodule:: example_interface
    :members: