.. _configuration:

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

WindKit requires your name, email, and institution to ensure that exported files have proper attribution and follow FAIR data practices.

The configuration system uses Pydantic-Settings to load settings in a specific order of precedence, ensuring that more explicit settings override less explicit ones:

1.  **Environment Variables**: Highest precedence.
2.  **TOML Configuration File**: User-specific settings file.
3.  **User Prompt**: Interactive input if no other settings are found.

This ensures that your most recent or most explicit settings are always used.

.. note::
   Upon the first import of the ``windkit`` package, the configuration system will automatically attempt to load your settings. If no existing configuration is found through environment variables or a TOML file, you will be prompted to enter the necessary information interactively. This "fail-fast" approach ensures you are set up before performing extensive work.

Quick Start
-----------

**For most users, the simplest approach is to let WindKit prompt you:**

1. Import WindKit in your Python session
2. Enter your information when prompted
3. Your settings will be automatically saved for future use

**For advanced users or automation, use environment variables or create a TOML configuration file.**

Configuration Methods
=====================

Setting up your configuration is straightforward using one of the following methods:

1. Using Environment Variables
------------------------------

You can define your settings using environment variables, which will take precedence over any settings found in a TOML configuration file. This is particularly useful for automated scripts, CI/CD pipelines, or when you want to quickly override a setting without modifying a file.

``windkit`` expects environment variables to be prefixed with ``WINDKIT_``. The following variables are recognized:

* ``WINDKIT_NAME``: Your full name.
* ``WINDKIT_EMAIL``: Your email address.
* ``WINDKIT_INSTITUTION``: Your institution or company name.

**Example (Linux/macOS):**

.. code-block:: bash

    export WINDKIT_NAME="John Doe"
    export WINDKIT_EMAIL="john.doe@example.com"
    export WINDKIT_INSTITUTION="Example University"

**Example (Windows Command Prompt):**

.. code-block:: bat

    set WINDKIT_NAME="Jane Doe"
    set WINDKIT_EMAIL="jane.doe@example.com"
    set WINDKIT_INSTITUTION="Research Labs Inc."

**Example (Windows PowerShell):**

.. code-block:: powershell

    $env:WINDKIT_NAME="Alice Smith"
    $env:WINDKIT_EMAIL="alice.smith@example.com"
    $env:WINDKIT_INSTITUTION="Global Wind Energy"

After setting these variables, ``windkit`` will automatically detect and use them upon import.

.. _using_a_toml_configuration_file:

2. Using a TOML Configuration File
-----------------------------------

For persistent configuration across sessions or reboots, you can create a TOML (Tom's Obvious, Minimal Language) configuration file.

The default location for this file is system-dependent but follows standard user configuration directories:

* **Linux**: ``~/.config/windkit/windkit_config.toml``
* **macOS**: ``~/Library/Application Support/windkit/windkit_config.toml``
* **Windows**: ``C:\\Users\\<username>\\AppData\\Roaming\\windkit\\windkit_config.toml``

You can manually create or edit this file. The content should be a simple key-value pair structure, like so:

.. code-block:: toml

    name = "Your Full Name"
    email = "your.email@example.com"
    institution = "Your Company or Institution"

Once this file is in place, ``windkit`` will automatically load these settings unless overridden by environment variables.

.. note::
   If you are migrating from an older version of ``windkit`` that used an INI configuration file (e.g., ``windkit_config.ini``), the system will automatically detect and convert your settings to the new TOML format upon the first import. The old INI file will then be deleted. If a TOML file already exists, the INI file will be safely renamed (e.g., ``windkit_config_migrated_YYYYMMDD_HHMMSS.ini``) to prevent data loss.

3. First-Time Setup via Prompt
-------------------------------

If you haven't set up any environment variables and no ``windkit_config.toml`` file is found, ``windkit`` will interactively prompt you for the necessary information when the package is first imported in a session.

You will see output similar to this in your console:

.. code-block:: text

    Configuration not found. Prompting user for information.
    Welcome! Please provide the following information:
    Your Name: [Enter your name]
    Your Email: [Enter your email]
    Your Institution: [Enter your institution]

After you provide the information, it will be saved to the default TOML configuration file (as described in :ref:`using_a_toml_configuration_file`). Subsequent imports will then load from this file, or from environment variables if they are set.

Accessing Your Configuration
----------------------------

Once ``windkit`` has loaded its configuration, you can access your settings through the globally available ``CONFIG`` object within the ``windkit.config`` module:

.. code-block:: python

    import windkit.config

    # Access individual settings
    print(f"User Name: {windkit.config.CONFIG.name}")
    print(f"User Email: {windkit.config.CONFIG.email}")
    print(f"User Institution: {windkit.config.CONFIG.institution}")

This configuration will then be used automatically by ``windkit``'s internal functions that require user identification.