.. _installation:

===================
Installation
===================

This quick install guide outlines the basic steps needed to install twinLab on
your computer using various methods and interfaces

---------------
Requirements
---------------

Python 3.8 to <3.12 version installed and running for your current environment.

To check your python version you can type the following into your shell: 

.. code-block:: shell 

   python --version

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

1. **Open a terminal:**

2. **Create a directory:**

Create a folder/directory where you want to install twinLab. Then, set that folder/directory as your current one.

.. code-block:: shell

    mkdir my_project 
    cd my_project

3. **Install twinLab:** 

In your newly created directory, install twinLab (ideally in a virtual environment).

.. code-block:: shell

    pip install twinlab

.. note::
   We recommend managing your Python packages with Python virtual environments. See more `here <https://docs.python.org/3/tutorial/venv.html>`__


4. **Configure your API key:**

There are two options for configuring your API key. One involves setting a .env file on your computer which contains your API key:

.. tab-set:: 

   .. tab-item:: .env file

      Once this .env file has been set, this will enable your API key to be read from any script run in the subsequent directory tree.

      .. tab-set::

         .. tab-item:: Windows

            .. tab-set::

               .. tab-item:: Powershell

                  .. code-block:: powershell

                     echo "TWINLAB_API_KEY=<your_api_key>" > .env

               .. tab-item:: Command Line

                  .. code-block:: console

                     echo TWINLAB_API_KEY=<your_api_key> > .env

         .. tab-item:: Linux

            .. code-block:: bash

               echo "TWINLAB_API_KEY=<your_api_key>" > .env

         .. tab-item:: MacOS

            .. code-block:: bash

               echo "TWINLAB_API_KEY=<your_api_key>" > .env

   .. tab-item:: set_api_key()

      Setting this function will enable you not to have to store your API key on your computer's operating system.

      .. code-block:: python

         import twinlab as tl

         API_KEY = '<your_api_key>'

         tl.set_api_key(API_KEY)

      .. warning::
         While we offer the flexibility to utilize the `set_api_key()` functionality, this should be used with care not to publicly expose your API key when sharing files.


**Replace *<your_api_key>* with the API key you received with your twinLab license.** (For information on licensing, please contact us `here <https://www.digilab.co.uk/products/twinlab>`__

Be aware of any blank spaces in the words between the quotation marks. This can cause errors when using twinLab.

You can check that the `.env` file has been created successfully using the following:

.. code-block:: shell

    ls -a .env

You should see the .env file listed.