.. _recipe_irfpyrc:

==============================
How to use configuration files
==============================

Introduction: when configuration files should be used?
======================================================
Configure files are used to make irfpy library portable.
For example, consider cases you want to access a local file,
for example, a data file.
The location of the data file may differ user by user, or even computer by computer.
Thus, the location is prohibited to be hard-coded into any library code.

Instead, configuration files are to be used.

Use cases
---------

- To set a path of the spacecraft data in a library code.
- To set a parameter used for programming.

Example
=======

For example in ``irfpy.aspera``, the data files are specified as a
top-level folder.  If the user setup the data files into
``/Data/venus/imadata-full/``  directory, the configuration file
looks as

::

        [vima]
        imamatbase = /Data/venus/imadata-full/

Another example in SWIM data (``irfpy.swim``), the configuration
file to access to the database is as follows.

::

        [swim]
        bmuobse = /Data/SWIM/bmu_orbit.v3.2/bmu_orbit/

The configuration file can be a single file, or multiple files.

The following file names will be evaluated in a priority order.

- ``./.irfpyrc``
- ``${HOME}/.irfpyrc``
- ``./irfpy.rc``
- ``${HOME}/irfpy.rc``
- ``./.pyanarc``
- ``${HOME}/.pyanarc``

.. note::

        Using .pyanarc is not recommented any more.
        It is left for compatibility only.

More on the format
==================

The format is like Windows' ini files.

::

        [section]
        entry1 = value1
        entry2 = value2

Specific section and entries depends on the each irfpy library.


How to use from your library code (for developer)
=================================================

Assume you have such a code:

.. code-block:: python

        import numpy as np
        def load_data():
                data = np.loadtxt('/irf/vex/vexdds/archive/XXYYZZ.dat')
                return data

This program tries to read the data from the file
:file:`/irf/vex/vexdds/archive/XXYYZZ.dat`,
and return its contents as a numpy array.
However, if you change your computer, the file location may change.

1. Prepare the configureation file.  :file:`~/.irfpyrc`.
You should prepare the file in all the computer.

::

        [vexdds]
        data_location = /irf/vex/vexdds/archive/XXYYZZ.dat

You can define the section and entry arbitrarily.
(But of course it is recommended to define them coherently.)

2. Change your program.  Use :class:`irfpy.util.irfpyrc.Rc` class.

.. code-block:: python

        import numpy as np
        from irfpy.util.irfpyrc import Rc

        def load_data():
                rc = Rc()
                datafile = rc.get('vexdds', 'data_location')
                data = np.loadtxt(datafile)
                return data


The only class you need to use is :class:`irfpy.util.irfpyrc.Rc`.