poetry-plugin-dotenv 2.1.6

poetry-plugin-dotenv - is the plugin that automatically loads environment variables from a dotenv file into the environment before poetry commands are run.

• Overview
  • Features
• Installation
• Usage and Configuration
  • Configuration via file
  • Configuration via environment variables
  • Lookup hierarchy
• Examples

Overview

poetry-plugin-dotenv - is the plugin that automatically loads environment variables from a dotenv file into the environment before poetry commands are run.

Features

• Doesn't require any dependencies
• Supports templates, interpolating variables using POSIX variable expansions
• Fully type safe
• Supports multiple configuration sources
• 100% test coverage and "A" grade for maintainability

Installation

poetry self add poetry-plugin-dotenv

Usage and Configuration

By default, the plugin will load the .env file from the current working directory or "higher directories".

To prevent poetry from loading the dotenv file, set the ignore option.

If your dotenv file is located in a different path or has a different name you may set the location.

ignore option can accept the next values:

• As True: y / yes / t / on / 1 / true
• As False: n / no / f / off / 0 / false

Configuration via file

The plugin is able to read project-specific default values for its options from a pyproject.toml file. By default, poetry-plugin-dotenv looks for pyproject.toml containing a [tool.poetry.plugins.dotenv] section.

Example pyproject.toml:

[tool.poetry.plugins.dotenv]
ignore = "false"
location = ".env.dev"

[!IMPORTANT] Due to the default poetry parser, options in the plugins sections should be always strings.

Configuration via environment variables

poetry-plugin-dotenv supports the following configuration options via environment variables.

• POETRY_PLUGIN_DOTENV_LOCATION
• POETRY_PLUGIN_DOTENV_IGNORE

[!IMPORTANT] Due to the nature of environment variables, options should be always strings.

Lookup hierarchy

A pyproject.toml can override default values. Options provided by the user via environment variables override both.

Examples

# .env
DB__HOST=localhost
DB__DBNAME=local_lakehouse
DB__USER=volodymyr
DB__PASSWORD=super_secret_password
DB__ENGINE=postgresql://${DB__USER}:${DB__PASSWORD}@${DB__HOST}/${DB__DBNAME}

# .env.dev
DB__HOST=dev.host
DB__DBNAME=dev_lakehouse
DB__USER=svc_team
DB__PASSWORD=super_secret_password
DB__ENGINE=postgresql://${DB__USER}:${DB__PASSWORD}@${DB__HOST}/${DB__DBNAME}

# pyroject.toml
[tool.poetry.plugins.dotenv]
location = ".env.dev"

# main.py
from __future__ import annotations

import os


if __name__ == "__main__":
    try:
        print(f"Host: {os.environ['DB__HOST']!r}")  # noqa: T201
        print(f"Name: {os.environ['DB__DBNAME']!r}")  # noqa: T201
        print(f"Username: {os.environ['DB__USER']!r}")  # noqa: T201
        print(f"Password: {os.environ['DB__PASSWORD']!r}")  # noqa: T201
        print(f"Engine: {os.environ['DB__ENGINE']!r}")  # noqa: T201

    except KeyError:
        print("Environment variables not set!")  # noqa: T201

poetry run -vvv python main.py
# Loading environment variables from '.env'.
# Host: 'localhost'
# Name: 'local_lakehouse'
# Username: 'volodymyr'
# Password: 'super_secret_password'
# Engine: 'postgresql://volodymyr:super_secret_password@localhost/local_lakehouse'

# set location section in pyproject.toml
poetry run -vvv python main.py
# Loading environment variables from '.env.dev'.
# Host: 'dev.host'
# Name: 'dev_lakehouse'
# Username: 'svc_team'
# Password: 'super_secret_password'
# Engine: 'postgresql://svc_team:[e-mail]/dev_lakehouse'

# set ignore = "true" in pyproject.toml
poetry run -vvv python main.py
# Not loading environment variables.
# Environment variables not set!

export POETRY_PLUGIN_DOTENV_LOCATION=.env.dev && poetry run -vvv python main.py
# Loading environment variables from '.env.dev'.
# Host: 'dev.host'
# Name: 'dev_lakehouse'
# Username: 'svc_team'
# Password: 'super_secret_password'
# Engine: 'postgresql://svc_team:[e-mail]/dev_lakehouse'

export POETRY_PLUGIN_DOTENV_IGNORE=true && poetry run -vvv python main.py
# Not loading environment variables.
# Environment variables not set!