.. _configuration:

=============
Configuration
=============

Introduction
============
``pyqalx`` has various configurable options. These allow you to adjust the operation of the system based on the specific task you're performing.

For the most part, these can be left as the default values. More detail on overriding defaults can
be found in :ref:`overriding_defaults` below.

Default values
==============

Global
------
These values are set on all configuration objects throughout the system.

.. automodule:: pyqalx.config.defaults
    :members:

.. _configuration_bots:

Bots
----
These values are set whenever :ref:`sessions` are configured in the context of a bot.
These configuration options should be added to your `~/.bots` config file

.. automodule:: pyqalx.config.defaults.bots
    :members:

.. _overriding_defaults:

Custom config and overriding defaults
=====================================

All :ref:`sessions` have a ``config`` attribute which returns an object that behaves exactly like a python ``dict``. There are four main ways to customise the configuration:

.ini files
----------

``pyqalx`` looks for a *.qalx* and a *.bots* file in the home directory of the user. These files follow
the `INI file format <https://en.wikipedia.org/wiki/INI_file>`_ and can be used to overwrite or add new configurations. This also supports multiple profiles, for example suppose you want **test** and **production** configs.

.. warning::
    values specified in ini files will always override all other methods unless you use ``skip_ini`` when initialising a session.

.. code:: ini

   [test]
   TOKEN = 632gd7yb9squd0q8sdhq0s8diqsd0nqsdq9sdj
   NODES = 20

   [production]
   TOKEN = 632gd7yb9squd0q8sdhq0s8diqsd0nqsdq9sdj
   NODES = 200000

These could then be used later:

.. code-block:: python

    from pyqalx import QalxSession
    qalx = QalxSession(profile_name="test")
    qalx.item.add({"node_count":qalx.config['NODES']})

When testing bots or processing functions and then once you are prepared to submit it to production simply change to

>>> qalx = QalxSession(profile_name="production")

Environment variables
---------------------

When a configuration is loaded it will look at all the system and user `environment variables <https://en.wikipedia.org/wiki/Environment_variable>`_ and will extract any that start with the name ``QALX_USER_`` or ``QALX_BOT_`` and save
them in the config with the leading identifier stripped. For example, with a bot like this:

.. code-block:: python

    from pyqalx import Bot
    bot = Bot("my bot")

    @bot.process
    def use_local_file(job):
        local_file = open(job.session.config['LOCAL_FILE_PATH'], 'r').read()
        remote_file = job.entity.get_item_data("REMOTE_FILE").read()

You could use the same code on multiple machines and just change the value of the ``QALX_BOT_LOCAL_FILE_PATH`` on each
machine to set the correct location.


Subclassing ``Config``
----------------------

This is the most *pythonic* way to introduce additional configurations and override the defaults. Any session can be
started with a custom config class:

.. code-block:: python

    from pyqalx import QalxSession
    from pyqalx.config import UserConfig

    my_config = {
        "N_THINGS": 50,
        "MSG_BLACKOUTSECONDS": 400
                }

    class MyUserConfig(UserConfig):

        @property
        def defaults(self):
            config = super(MyUserConfig, self).defaults
            config.update(my_config)
            return config

    qalx = QalxSession(config_class=MyUserConfig)
    thing_item = qalx.item.add({"how_many":10*qalx.config['N_THINGS']})