Merge pull request #330 from joke2k/feature/update-documentation

Update documentation and minor improvements

CHANGELOG.rst

@@ -13,6 +13,10 @@ Added
   `#283 <https://github.com/joke2k/django-environ/pull/283>`_.
 - Added docker-style file variable support
   `#189 <https://github.com/joke2k/django-environ/issues/189>`_.
+- Added option to override existing variables with ``read_env``
+  `#103 <https://github.com/joke2k/django-environ/issues/103>`_,
+  `#249 <https://github.com/joke2k/django-environ/issues/249>`_.
+
 
 Fixed
 +++++

environ/environ.py

@@ -739,12 +739,22 @@ def read_env(cls, env_file=None, overwrite=False, **overrides):
         backtracking to find the dotenv in the same directory as the file that
         called read_env.
 
-        By default, won't overwrite any existing environment variables. You can
-        enable this behaviour by setting ``overwrite=True``.
+        Existing environment variables take precedent and are NOT overwritten
+        by the file content. ``overwrite=True`` will force an overwrite of
+        existing environment variables.
 
         Refs:
         - https://wellfire.co/learn/easier-12-factor-django
         - https://gist.github.com/bennylope/2999704
+
+        :param env_file: The path to the `.env` file your application should
+            use. If a path is not provided, `read_env` will attempt to import
+            the Django settings module from the Django project root.
+        :param overwrite: ``overwrite=True`` will force an overwrite of
+            existing environment variables.
+        :param **overrides: Any additional keyword arguments provided directly
+            to read_env will be added to the environment. If the key matches an
+            existing environment variable, the value will be overridden.
         """
         if env_file is None:
             frame = sys._getframe()
@@ -794,16 +804,21 @@ def _keep_escaped_format_characters(match):
                                  m3.group(1))
                 overrides[key] = str(val)
             else:
-                logger.warn('Invalid line: %s', line)
+                logger.warning('Invalid line: %s', line)
 
-        if overwrite:
-            def set_environ(key, value):
-                cls.ENVIRON[key] = value
-        else:
-            set_environ = cls.ENVIRON.setdefault
+        def set_environ(envval):
+            """Return lambda to set environ.
+
+             Use setdefault unless overwrite is specified.
+             """
+            if overwrite:
+                return lambda k, v: envval.update({k: str(v)})
+            return lambda k, v: envval.setdefault(k, str(v))
+
+        setenv = set_environ(cls.ENVIRON)
 
         for key, value in overrides.items():
-            set_environ(key, value)
+            setenv(key, value)
 
 
 class FileAwareEnv(Env):

tests/test_fileaware.py

@@ -1,3 +1,11 @@
+# This file is part of the django-environ.
+#
+# Copyright (c) 2021, Serghei Iakovlev <egrep@protonmail.ch>
+# Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
+#
+# For the full copyright and license information, please view
+# the LICENSE.txt file that was distributed with this source code.
+
 import os
 import tempfile
 from contextlib import contextmanager