<div align="center">
<img alt="logo" src="https://github.com/pivoshenko/poetry-plugin-dotenv/blob/main/docs/assets/logo.svg?raw=True" height=200>
</div>
<br>
<p align="center">
<a href="https://opensource.org/licenses/MIT">
<img alt="license" src="https://img.shields.io/pypi/l/poetry-plugin-dotenv?logo=opensourceinitiative">
</a>
<a href="https://python-poetry.org">
<img alt="poetry" src="https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json">
</a>
<a href="https://pypi.org/project/poetry-plugin-dotenv">
<img alt="python" src="https://img.shields.io/pypi/pyversions/poetry-plugin-dotenv?logo=python">
</a>
<a href="https://pypi.org/project/poetry-plugin-dotenv">
<img alt="pypi" src="https://img.shields.io/pypi/v/poetry-plugin-dotenv?logo=pypi">
</a>
<a href="https://github.com/pivoshenko/poetry-plugin-dotenv/releases">
<img alt="release" src="https://img.shields.io/github/v/release/pivoshenko/poetry-plugin-dotenv?logo=github">
</a>
</p>
<p align="center">
<a href="https://github.com/psf/black">
<img alt="black" src="https://img.shields.io/badge/code_style-black-black.svg?logo=windowsterminal">
</a>
<a href="https://github.com/PyCQA/isort">
<img alt="isort" src="https://img.shields.io/badge/imports-isort-black.svg?logo=windowsterminal">
</a>
<a href="https://beta.ruff.rs/docs/">
<img alt="ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json">
</a>
<a href="https://mypy.readthedocs.io/en/stable/index.html">
<img alt="mypy" src="https://img.shields.io/badge/mypy-checked-success.svg?logo=python">
</a>
<a href="https://github.com/semantic-release/semantic-release">
<img alt="semantic_release" src="https://img.shields.io/badge/semantic_release-angular-e10079?logo=semantic-release">
</a>
</p>
<p align="center">
<a href="https://github.com/dependabot">
<img alt="dependabot" src="https://img.shields.io/badge/dependabot-enable-success?logo=Dependabot">
</a>
<a href="https://github.com/pivoshenko/poetry-plugin-dotenv/actions/workflows/ci.yaml">
<img alt="CI" src="https://img.shields.io/github/actions/workflow/status/pivoshenko/poetry-plugin-dotenv/ci.yaml?label=CI&logo=github">
</a>
<a href="https://github.com/pivoshenko/poetry-plugin-dotenv/actions/workflows/cd.yaml">
<img alt="CD" src="https://img.shields.io/github/actions/workflow/status/pivoshenko/poetry-plugin-dotenv/cd.yaml?label=CD&logo=github">
</a>
<a href="https://github.com/pivoshenko/poetry-plugin-dotenv/blob/main/.pre-commit-config.yaml">
<img alt="hooks" src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit">
</a>
<a href="https://pypi.org/project/poetry-plugin-dotenv">
<img alt="wheel" src="https://img.shields.io/pypi/wheel/poetry-plugin-dotenv?logo=pypi">
</a>
</p>
<p align="center">
<a href="https://codecov.io/gh/pivoshenko/poetry-plugin-dotenv" >
<img alt="codecov" src="https://codecov.io/gh/pivoshenko/poetry-plugin-dotenv/graph/badge.svg?token=cqRQxVnDR6"/>
</a>
<a href="https://codeclimate.com/github/pivoshenko/poetry-plugin-dotenv/maintainability">
<img alt="codeclimate" src="https://img.shields.io/codeclimate/maintainability/pivoshenko/poetry-plugin-dotenv?logo=codeclimate">
</a>
<a href="https://pypi.org/project/poetry-plugin-dotenv">
<img alt="downloads" src="https://img.shields.io/pypi/dm/poetry-plugin-dotenv?logo=pypi">
</a>
<a href="https://github.com/pivoshenko/poetry-plugin-dotenv/">
<img alt="stars" src="https://img.shields.io/github/stars/pivoshenko/poetry-plugin-dotenv?style=flat&logo=github">
</a>
</p>
<p align="center">
<a href="https://stand-with-ukraine.pp.ua/">
<img alt="standwithukraine" src="https://img.shields.io/badge/Support-Ukraine-FFD500?style=flat&labelColor=005BBB">
</a>
<a href="https://stand-with-ukraine.pp.ua">
<img alt="standwithukraine" src="https://img.shields.io/badge/made_in-Ukraine-ffd700.svg?labelColor=0057b7">
</a>
</p>
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Usage and Configuration](#usage-and-configuration)
- [Configuration via file](#configuration-via-file)
- [Configuration via environment variables](#configuration-via-environment-variables)
- [Lookup hierarchy](#lookup-hierarchy)
- [Examples](#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
```bash
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`:
```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
<img alt="demo" src="https://github.com/pivoshenko/poetry-plugin-dotenv/blob/main/docs/assets/demo.gif?raw=True">
```dotenv
# .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}
```
```dotenv
# .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}
```
```toml
# pyroject.toml
[tool.poetry.plugins.dotenv]
location = ".env.dev"
```
```python
# 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
```
```shell
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:super_secret_password@dev.host/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:super_secret_password@dev.host/dev_lakehouse'
export POETRY_PLUGIN_DOTENV_IGNORE=true && poetry run -vvv python main.py
# Not loading environment variables.
# Environment variables not set!
```
Raw data
{
"_id": null,
"home_page": "https://github.com/pivoshenko/poetry-plugin-dotenv",
"name": "poetry-plugin-dotenv",
"maintainer": "Volodymyr Pivoshenko",
"docs_url": null,
"requires_python": "<4.0,>=3.8.1",
"maintainer_email": "volodymyr.pivoshenko@gmail.com",
"keywords": "python, pypi, poetry, plugin, plugins, poetry-plugin, poetry-plugins, env, dotenv, config, configuration, configuration-management, cross-platform, hacktoberfest",
"author": "Volodymyr Pivoshenko",
"author_email": "volodymyr.pivoshenko@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e1/a7/d438a14bb2172df9e8e9dc7983c916f4fd0590103e52f951d58be8213097/poetry_plugin_dotenv-2.1.6.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img alt=\"logo\" src=\"https://github.com/pivoshenko/poetry-plugin-dotenv/blob/main/docs/assets/logo.svg?raw=True\" height=200>\n</div>\n\n<br>\n\n<p align=\"center\">\n <a href=\"https://opensource.org/licenses/MIT\">\n <img alt=\"license\" src=\"https://img.shields.io/pypi/l/poetry-plugin-dotenv?logo=opensourceinitiative\">\n </a>\n <a href=\"https://python-poetry.org\">\n <img alt=\"poetry\" src=\"https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json\">\n </a>\n <a href=\"https://pypi.org/project/poetry-plugin-dotenv\">\n <img alt=\"python\" src=\"https://img.shields.io/pypi/pyversions/poetry-plugin-dotenv?logo=python\">\n </a>\n <a href=\"https://pypi.org/project/poetry-plugin-dotenv\">\n <img alt=\"pypi\" src=\"https://img.shields.io/pypi/v/poetry-plugin-dotenv?logo=pypi\">\n </a>\n <a href=\"https://github.com/pivoshenko/poetry-plugin-dotenv/releases\">\n <img alt=\"release\" src=\"https://img.shields.io/github/v/release/pivoshenko/poetry-plugin-dotenv?logo=github\">\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/psf/black\">\n <img alt=\"black\" src=\"https://img.shields.io/badge/code_style-black-black.svg?logo=windowsterminal\">\n </a>\n <a href=\"https://github.com/PyCQA/isort\">\n <img alt=\"isort\" src=\"https://img.shields.io/badge/imports-isort-black.svg?logo=windowsterminal\">\n </a>\n <a href=\"https://beta.ruff.rs/docs/\">\n <img alt=\"ruff\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\">\n </a>\n <a href=\"https://mypy.readthedocs.io/en/stable/index.html\">\n <img alt=\"mypy\" src=\"https://img.shields.io/badge/mypy-checked-success.svg?logo=python\">\n </a>\n <a href=\"https://github.com/semantic-release/semantic-release\">\n <img alt=\"semantic_release\" src=\"https://img.shields.io/badge/semantic_release-angular-e10079?logo=semantic-release\">\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/dependabot\">\n <img alt=\"dependabot\" src=\"https://img.shields.io/badge/dependabot-enable-success?logo=Dependabot\">\n </a>\n <a href=\"https://github.com/pivoshenko/poetry-plugin-dotenv/actions/workflows/ci.yaml\">\n <img alt=\"CI\" src=\"https://img.shields.io/github/actions/workflow/status/pivoshenko/poetry-plugin-dotenv/ci.yaml?label=CI&logo=github\">\n </a>\n <a href=\"https://github.com/pivoshenko/poetry-plugin-dotenv/actions/workflows/cd.yaml\">\n <img alt=\"CD\" src=\"https://img.shields.io/github/actions/workflow/status/pivoshenko/poetry-plugin-dotenv/cd.yaml?label=CD&logo=github\">\n </a>\n <a href=\"https://github.com/pivoshenko/poetry-plugin-dotenv/blob/main/.pre-commit-config.yaml\">\n <img alt=\"hooks\" src=\"https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit\">\n </a>\n <a href=\"https://pypi.org/project/poetry-plugin-dotenv\">\n <img alt=\"wheel\" src=\"https://img.shields.io/pypi/wheel/poetry-plugin-dotenv?logo=pypi\">\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"https://codecov.io/gh/pivoshenko/poetry-plugin-dotenv\" >\n <img alt=\"codecov\" src=\"https://codecov.io/gh/pivoshenko/poetry-plugin-dotenv/graph/badge.svg?token=cqRQxVnDR6\"/>\n </a>\n <a href=\"https://codeclimate.com/github/pivoshenko/poetry-plugin-dotenv/maintainability\">\n <img alt=\"codeclimate\" src=\"https://img.shields.io/codeclimate/maintainability/pivoshenko/poetry-plugin-dotenv?logo=codeclimate\">\n </a>\n <a href=\"https://pypi.org/project/poetry-plugin-dotenv\">\n <img alt=\"downloads\" src=\"https://img.shields.io/pypi/dm/poetry-plugin-dotenv?logo=pypi\">\n </a>\n <a href=\"https://github.com/pivoshenko/poetry-plugin-dotenv/\">\n <img alt=\"stars\" src=\"https://img.shields.io/github/stars/pivoshenko/poetry-plugin-dotenv?style=flat&logo=github\">\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"https://stand-with-ukraine.pp.ua/\">\n <img alt=\"standwithukraine\" src=\"https://img.shields.io/badge/Support-Ukraine-FFD500?style=flat&labelColor=005BBB\">\n </a>\n <a href=\"https://stand-with-ukraine.pp.ua\">\n <img alt=\"standwithukraine\" src=\"https://img.shields.io/badge/made_in-Ukraine-ffd700.svg?labelColor=0057b7\">\n </a>\n</p>\n\n- [Overview](#overview)\n - [Features](#features)\n- [Installation](#installation)\n- [Usage and Configuration](#usage-and-configuration)\n - [Configuration via file](#configuration-via-file)\n - [Configuration via environment variables](#configuration-via-environment-variables)\n - [Lookup hierarchy](#lookup-hierarchy)\n- [Examples](#examples)\n\n## Overview\n\n`poetry-plugin-dotenv` - is the plugin that automatically loads environment variables from a dotenv file into the environment before `poetry` commands are run.\n\n### Features\n\n- Doesn't require any dependencies\n- Supports templates, interpolating variables using POSIX variable expansions\n- Fully type safe\n- Supports multiple configuration sources\n- 100% test coverage and \"A\" grade for maintainability\n\n## Installation\n\n```bash\npoetry self add poetry-plugin-dotenv\n```\n\n## Usage and Configuration\n\nBy default, the plugin will load the `.env` file from the current working directory or \"higher directories\".\n\nTo prevent `poetry` from loading the dotenv file, set the `ignore` option.\n\nIf your dotenv file is located in a different path or has a different name you may set the `location`.\n\n`ignore` option can accept the next values:\n- As True: `y / yes / t / on / 1 / true`\n- As False: `n / no / f / off / 0 / false`\n\n### Configuration via file\n\nThe plugin is able to read project-specific default values for its options from a `pyproject.toml` file.\nBy default, `poetry-plugin-dotenv` looks for `pyproject.toml` containing a `[tool.poetry.plugins.dotenv]` section.\n\nExample `pyproject.toml`:\n\n```toml\n[tool.poetry.plugins.dotenv]\nignore = \"false\"\nlocation = \".env.dev\"\n```\n\n> [!IMPORTANT]\n> Due to the default `poetry` parser, options in the plugins sections should be always strings.\n\n### Configuration via environment variables\n\n`poetry-plugin-dotenv` supports the following configuration options via environment variables.\n\n- `POETRY_PLUGIN_DOTENV_LOCATION`\n- `POETRY_PLUGIN_DOTENV_IGNORE`\n\n> [!IMPORTANT]\n> Due to the nature of environment variables, options should be always strings.\n\n### Lookup hierarchy\n\nA `pyproject.toml` can override default values. Options provided by the user via environment variables override both.\n\n## Examples\n\n<img alt=\"demo\" src=\"https://github.com/pivoshenko/poetry-plugin-dotenv/blob/main/docs/assets/demo.gif?raw=True\">\n\n```dotenv\n# .env\nDB__HOST=localhost\nDB__DBNAME=local_lakehouse\nDB__USER=volodymyr\nDB__PASSWORD=super_secret_password\nDB__ENGINE=postgresql://${DB__USER}:${DB__PASSWORD}@${DB__HOST}/${DB__DBNAME}\n```\n\n```dotenv\n# .env.dev\nDB__HOST=dev.host\nDB__DBNAME=dev_lakehouse\nDB__USER=svc_team\nDB__PASSWORD=super_secret_password\nDB__ENGINE=postgresql://${DB__USER}:${DB__PASSWORD}@${DB__HOST}/${DB__DBNAME}\n```\n\n```toml\n# pyroject.toml\n[tool.poetry.plugins.dotenv]\nlocation = \".env.dev\"\n```\n\n```python\n# main.py\nfrom __future__ import annotations\n\nimport os\n\n\nif __name__ == \"__main__\":\n try:\n print(f\"Host: {os.environ['DB__HOST']!r}\") # noqa: T201\n print(f\"Name: {os.environ['DB__DBNAME']!r}\") # noqa: T201\n print(f\"Username: {os.environ['DB__USER']!r}\") # noqa: T201\n print(f\"Password: {os.environ['DB__PASSWORD']!r}\") # noqa: T201\n print(f\"Engine: {os.environ['DB__ENGINE']!r}\") # noqa: T201\n\n except KeyError:\n print(\"Environment variables not set!\") # noqa: T201\n```\n\n```shell\npoetry run -vvv python main.py\n# Loading environment variables from '.env'.\n# Host: 'localhost'\n# Name: 'local_lakehouse'\n# Username: 'volodymyr'\n# Password: 'super_secret_password'\n# Engine: 'postgresql://volodymyr:super_secret_password@localhost/local_lakehouse'\n\n# set location section in pyproject.toml\npoetry run -vvv python main.py\n# Loading environment variables from '.env.dev'.\n# Host: 'dev.host'\n# Name: 'dev_lakehouse'\n# Username: 'svc_team'\n# Password: 'super_secret_password'\n# Engine: 'postgresql://svc_team:super_secret_password@dev.host/dev_lakehouse'\n\n# set ignore = \"true\" in pyproject.toml\npoetry run -vvv python main.py\n# Not loading environment variables.\n# Environment variables not set!\n\nexport POETRY_PLUGIN_DOTENV_LOCATION=.env.dev && poetry run -vvv python main.py\n# Loading environment variables from '.env.dev'.\n# Host: 'dev.host'\n# Name: 'dev_lakehouse'\n# Username: 'svc_team'\n# Password: 'super_secret_password'\n# Engine: 'postgresql://svc_team:super_secret_password@dev.host/dev_lakehouse'\n\nexport POETRY_PLUGIN_DOTENV_IGNORE=true && poetry run -vvv python main.py\n# Not loading environment variables.\n# Environment variables not set!\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "poetry-plugin-dotenv - is the plugin that automatically loads environment variables from a dotenv file into the environment before poetry commands are run.",
"version": "2.1.6",
"project_urls": {
"Documentation": "https://github.com/pivoshenko/poetry-plugin-dotenv",
"Homepage": "https://github.com/pivoshenko/poetry-plugin-dotenv",
"Issues": "https://github.com/pivoshenko/poetry-plugin-dotenv/issues",
"Releases": "https://github.com/pivoshenko/poetry-plugin-dotenv/releases",
"Repository": "https://github.com/pivoshenko/poetry-plugin-dotenv",
"Say Thanks!": "https://www.buymeacoffee.com/pivoshenko"
},
"split_keywords": [
"python",
" pypi",
" poetry",
" plugin",
" plugins",
" poetry-plugin",
" poetry-plugins",
" env",
" dotenv",
" config",
" configuration",
" configuration-management",
" cross-platform",
" hacktoberfest"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7b7610f14cdd093a9ba26e358ae50582bf7e86cef6b4fba035f6db055cc6d288",
"md5": "7fa593478903f049a64595783b3eba36",
"sha256": "f37f5df24e53588da356c0c434c9a1fd8b8194cf72bac7f361d1534f5d798f2b"
},
"downloads": -1,
"filename": "poetry_plugin_dotenv-2.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7fa593478903f049a64595783b3eba36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8.1",
"size": 13381,
"upload_time": "2024-05-13T07:28:27",
"upload_time_iso_8601": "2024-05-13T07:28:27.131958Z",
"url": "https://files.pythonhosted.org/packages/7b/76/10f14cdd093a9ba26e358ae50582bf7e86cef6b4fba035f6db055cc6d288/poetry_plugin_dotenv-2.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e1a7d438a14bb2172df9e8e9dc7983c916f4fd0590103e52f951d58be8213097",
"md5": "beb2eea1111921216988822bfabf59d8",
"sha256": "a7a8d0c7587c3031751c5822062db9f8e6cf97d73c01acb24627b8d18adc9895"
},
"downloads": -1,
"filename": "poetry_plugin_dotenv-2.1.6.tar.gz",
"has_sig": false,
"md5_digest": "beb2eea1111921216988822bfabf59d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8.1",
"size": 13811,
"upload_time": "2024-05-13T07:28:28",
"upload_time_iso_8601": "2024-05-13T07:28:28.502184Z",
"url": "https://files.pythonhosted.org/packages/e1/a7/d438a14bb2172df9e8e9dc7983c916f4fd0590103e52f951d58be8213097/poetry_plugin_dotenv-2.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-13 07:28:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pivoshenko",
"github_project": "poetry-plugin-dotenv",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "poetry-plugin-dotenv"
}