GitLocker: The Coding Marketplace

Description:

pythondotenvyaml 0.17.1

python-dotenv

Python-dotenv reads key-value pairs from a .env file and can set them as environment
variables. It helps in the development of applications following the
12-factor principles.

Getting Started
Other Use Cases

Load configuration without altering the environment
Parse configuration as a stream
Load .env files in IPython

Command-line Interface
File format

Multiline values
Variable expansion

Related Projects
Acknowledgements

Getting Started
pip install python-dotenv

If your application takes its configuration from environment variables, like a 12-factor
application, launching it in development is not very practical because you have to set
those environment variables yourself.
To help you with that, you can add Python-dotenv to your application to make it load the
configuration from a .env file when it is present (e.g. in development) while remaining
configurable via the environment:
from dotenv import load_dotenv

load_dotenv() # take environment variables from .env.

# Code of your application, which uses environment variables (e.g. from `os.environ` or
# `os.getenv`) as if they came from the actual environment.

By default, load_dotenv doesn't override existing environment variables.
To configure the development environment, add a .env in the root directory of your
project:
.
├── .env
└── foo.py

The syntax of .env files supported by python-dotenv is similar to that of Bash:
# Development settings
DOMAIN=example.org
ADMIN_EMAIL=admin@${DOMAIN}
ROOT_URL=${DOMAIN}/app

If you use variables in values, ensure they are surrounded with { and }, like
${DOMAIN}, as bare variables such as $DOMAIN are not expanded.
You will probably want to add .env to your .gitignore, especially if it contains
secrets like a password.
See the section "File format" below for more information about what you can write in a
.env file.
Other Use Cases
Load configuration without altering the environment
The function dotenv_values works more or less the same way as load_dotenv, except it
doesn't touch the environment, it just returns a dict with the values parsed from the
.env file.
from dotenv import dotenv_values

config = dotenv_values(".env") # config = {"USER": "foo", "EMAIL": "foo@example.org"}

This notably enables advanced configuration management:
import os
from dotenv import dotenv_values

config = {
**dotenv_values(".env.shared"), # load shared development variables
**dotenv_values(".env.secret"), # load sensitive variables
**os.environ, # override loaded values with environment variables
}

Parse configuration as a stream
load_dotenv and dotenv_values accept streams via their stream
argument. It is thus possible to load the variables from sources other than the
filesystem (e.g. the network).
from io import StringIO

from dotenv import load_dotenv

config = StringIO("USER=foo\nEMAIL=foo@example.org")
load_dotenv(stream=config)

Load .env files in IPython
You can use dotenv in IPython. By default, it will use find_dotenv to search for a
.env file:
%load_ext dotenv
%dotenv

You can also specify a path:
%dotenv relative/or/absolute/path/to/.env

Optional flags:

-o to override existing variables.
-v for increased verbosity.

Command-line Interface
A CLI interface dotenv is also included, which helps you manipulate the .env file
without manually opening it.
$ pip install "python-dotenv[cli]"
$ dotenv set USER=foo
$ dotenv set EMAIL=foo@example.org
$ dotenv list
USER=foo
EMAIL=foo@example.org
$ dotenv run -- python foo.py

Run dotenv --help for more information about the options and subcommands.
File format
The format is not formally specified and still improves over time. That being said,
.env files should mostly look like Bash files.
Keys can be unquoted or single-quoted. Values can be unquoted, single- or double-quoted.
Spaces before and after keys, equal signs, and values are ignored. Values can be followed
by a comment. Lines can start with the export directive, which has no effect on their
interpretation.
Allowed escape sequences:

in single-quoted values: \\, \'
in double-quoted values: \\, \', \", \a, \b, \f, \n, \r, \t, \v

Multiline values
It is possible for single- or double-quoted values to span multiple lines. The following
examples are equivalent:
FOO="first line
second line"

FOO="first line\nsecond line"

Variable expansion
Python-dotenv can interpolate variables using POSIX variable expansion.
With load_dotenv(override=True) or dotenv_values(), the value of a variable is the
first of the values defined in the following list:

Value of that variable in the .env file.
Value of that variable in the environment.
Default value, if provided.
Empty string.

With load_dotenv(override=False), the value of a variable is the first of the values
defined in the following list:

Value of that variable in the environment.
Value of that variable in the .env file.
Default value, if provided.
Empty string.

Related Projects

Honcho - For managing
Procfile-based applications.
django-dotenv
django-environ
django-configuration
dump-env
environs
dynaconf

Acknowledgements
This project is currently maintained by Saurabh Kumar and
Bertrand Bonnefoy-Claudet and would not have been possible
without the support of these awesome
people.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this
project adheres to Semantic Versioning.
0.17.1 - 2021-04-29
Fixed

Fixed tests for build environments relying on PYTHONPATH (#318 by @befeleme).

0.17.0 - 2021-04-02
Changed

Make dotenv get <key> only show the value, not key=value (#313 by @bbc2).

Added

Add --override/--no-override option to dotenv run (#312 by @zueve and @bbc2).

0.16.0 - 2021-03-27
Changed

The default value of the encoding parameter for load_dotenv and dotenv_values is
now "utf-8" instead of None (#306 by @bbc2).
Fix resolution order in variable expansion with override=False (#287 by @bbc2).

0.15.0 - 2020-10-28
Added

Add --export option to set to make it prepend the binding with export (#270 by
@jadutter).

Changed

Make set command create the .env file in the current directory if no .env file was
found (#270 by @jadutter).

Fixed

Fix potentially empty expanded value for duplicate key (#260 by @bbc2).
Fix import error on Python 3.5.0 and 3.5.1 (#267 by @gongqingkui).
Fix parsing of unquoted values containing several adjacent space or tab characters
(#277 by @bbc2, review by @x-yuri).

0.14.0 - 2020-07-03
Changed

Privilege definition in file over the environment in variable expansion (#256 by
@elbehery95).

Fixed

Improve error message for when file isn't found (#245 by @snobu).
Use HTTPS URL in package meta data (#251 by @ekohl).

0.13.0 - 2020-04-16
Added

Add support for a Bash-like default value in variable expansion (#248 by @bbc2).

0.12.0 - 2020-02-28
Changed

Use current working directory to find .env when bundled by PyInstaller (#213 by
@gergelyk).

Fixed

Fix escaping of quoted values written by set_key (#236 by @bbc2).
Fix dotenv run crashing on environment variables without values (#237 by @yannham).
Remove warning when last line is empty (#238 by @bbc2).

0.11.0 - 2020-02-07
Added

Add interpolate argument to load_dotenv and dotenv_values to disable interpolation
(#232 by @ulyssessouza).

Changed

Use logging instead of warnings (#231 by @bbc2).

Fixed

Fix installation in non-UTF-8 environments (#225 by @altendky).
Fix PyPI classifiers (#228 by @bbc2).

0.10.5 - 2020-01-19
Fixed

Fix handling of malformed lines and lines without a value (#222 by @bbc2):

Don't print warning when key has no value.
Reject more malformed lines (e.g. "A: B", "a='b',c").

Fix handling of lines with just a comment (#224 by @bbc2).

0.10.4 - 2020-01-17
Added

Make typing optional (#179 by @techalchemy).
Print a warning on malformed line (#211 by @bbc2).
Support keys without a value (#220 by @ulyssessouza).

0.10.3

Improve interactive mode detection (@andrewsmith)(#183).
Refactor parser to fix parsing inconsistencies (@bbc2)(#170).

Interpret escapes as control characters only in double-quoted strings.
Interpret # as start of comment only if preceded by whitespace.

0.10.2

Add type hints and expose them to users (@qnighy)(#172)
load_dotenv and dotenv_values now accept an encoding parameter, defaults to None
(@theskumar)(@earlbread)([#161])
Fix str/unicode inconsistency in Python 2: values are always str now. (@bbc2)(#121)
Fix Unicode error in Python 2, introduced in 0.10.0. (@bbc2)(#176)

0.10.1

Fix parsing of variable without a value (@asyncee)(@bbc2)(#158)

0.10.0

Add support for UTF-8 in unquoted values (@bbc2)(#148)
Add support for trailing comments (@bbc2)(#148)
Add backslashes support in values (@bbc2)(#148)
Add support for newlines in values (@bbc2)(#148)
Force environment variables to str with Python2 on Windows (@greyli)
Drop Python 3.3 support (@greyli)
Fix stderr/-out/-in redirection (@venthur)

0.9.0

Add --version parameter to cli (@venthur)
Enable loading from current directory (@cjauvin)
Add 'dotenv run' command for calling arbitrary shell script with .env (@venthur)

0.8.1

Add tests for docs (@Flimm)
Make 'cli' support optional. Use pip install python-dotenv[cli]. (@theskumar)

0.8.0

set_key and unset_key only modified the affected file instead of
parsing and re-writing file, this causes comments and other file
entact as it is.
Add support for export prefix in the line.
Internal refractoring (@theskumar)
Allow load_dotenv and dotenv_values to work with StringIO()) (@alanjds)(@theskumar)(#78)

0.7.1

Remove hard dependency on iPython (@theskumar)

0.7.0

Add support to override system environment variable via .env.
(@milonimrod)
(#63)
Disable ".env not found" warning by default
(@maxkoryukov)
(#57)

0.6.5

Add support for special characters \.
(@pjona)
(#60)

0.6.4

Fix issue with single quotes (@Flimm)
(#52)

0.6.3

Handle unicode exception in setup.py
(#46)

0.6.2

Fix dotenv list command (@ticosax)
Add iPython Suport
(@tillahoffmann)

0.6.0

Drop support for Python 2.6
Handle escaped charaters and newlines in quoted values. (Thanks
@iameugenejo)
Remove any spaces around unquoted key/value. (Thanks
@paulochf)
Added POSIX variable expansion. (Thanks
@hugochinchilla)

0.5.1

Fix find_dotenv - it now start search from the file where this
function is called from.

0.5.0

Add find_dotenv method that will try to find a .env file.
(Thanks @isms)

0.4.0

cli: Added -q/--quote option to control the behaviour of quotes
around values in .env. (Thanks
@hugochinchilla).
Improved test coverage.