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):

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

Example (Windows Command Prompt):

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

Example (Windows 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.

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:

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:

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 2. 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:

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.