From 2b14ccb82182cbab267616cae2b16474715b5292 Mon Sep 17 00:00:00 2001
From: Bertrand Bonnefoy-Claudet <bertrand@bertrandbc.com>
Date: Sat, 26 Mar 2022 11:38:15 +0100
Subject: [PATCH] Improve documentation for variables without value

---
 README.md          | 14 ++++++++++++++
 src/dotenv/main.py | 18 ++++++++++++------
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 9b56b546..70de7e09 100644
--- a/README.md
+++ b/README.md
@@ -180,6 +180,20 @@ second line"
 FOO="first line\nsecond line"
 ```
 
+### Variable without a value
+
+A variable can have no value:
+
+```bash
+FOO
+```
+
+It results in `dotenv_values` associating that variable name with the value `None` (e.g.
+`{"FOO": None}`. `load_dotenv`, on the other hand, simply ignores such variables.
+
+This shouldn't be confused with `FOO=`, in which case the variable is associated with the
+empty string.
+
 ### Variable expansion
 
 Python-dotenv can interpolate variables using POSIX variable expansion.
diff --git a/src/dotenv/main.py b/src/dotenv/main.py
index 20ac61ba..75ea1bbf 100644
--- a/src/dotenv/main.py
+++ b/src/dotenv/main.py
@@ -351,14 +351,20 @@ def dotenv_values(
     """
     Parse a .env file and return its content as a dict.
 
-    - *dotenv_path*: absolute or relative path to .env file.
-    - *stream*: `StringIO` object with .env content, used if `dotenv_path` is `None`.
-    - *verbose*: whether to output a warning the .env file is missing. Defaults to
+    The returned dict will have `None` values for keys without values in the .env file.
+    For example, `foo=bar` results in `{"foo": "bar"}` whereas `foo` alone results in
+    `{"foo": None}`
+
+    Parameters:
+
+    - `dotenv_path`: absolute or relative path to the .env file.
+    - `stream`: `StringIO` object with .env content, used if `dotenv_path` is `None`.
+    - `verbose`: whether to output a warning if the .env file is missing. Defaults to
       `False`.
-      in `.env` file.  Defaults to `False`.
-    - *encoding*: encoding to be used to read the file.
+    - `encoding`: encoding to be used to read the file. Defaults to `"utf-8"`.
 
-    If both `dotenv_path` and `stream`, `find_dotenv()` is used to find the .env file.
+    If both `dotenv_path` and `stream` are `None`, `find_dotenv()` is used to find the
+    .env file.
     """
     if dotenv_path is None and stream is None:
         dotenv_path = find_dotenv()