Fix PostgreSQL cluster IPv6 parsing and lazy-default debug logging (#575)

joke2k · web-flow · commit 079a2f13cf5f · 2026-02-14T00:35:08.000Z
* Fix postgres cluster IPv6 parsing and lazy-default debug logging

* Fix pylint constant naming in env loader

* Fix CI build metadata rendering and dead docs link

* Increase coverage for parser and read_env edge paths

* Add 2026 copyright ownership notice in descending order

* ci(build): install build tool in workflow

* docs(linkcheck): set timeout to 60 seconds

* docs(backers): fix Open Collective sponsor image URL
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -34,7 +34,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install tox tox-gh-actions setuptools
+          pip install tox tox-gh-actions build
 
       - name: Check MANIFEST.in for completeness
         run: tox -e manifest
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/BACKERS.rst b/BACKERS.rst
@@ -23,7 +23,7 @@ Thank you to all our backers!
 .. |ocsponsor0| image:: https://opencollective.com/django-environ/sponsor/0/avatar.svg
     :target: https://opencollective.com/triplebyte
     :alt: Sponsor
-.. |ocsponsor1| image:: https://images.opencollective.com/static/images/become_sponsor.svg
+.. |ocsponsor1| image:: https://opencollective.com/static/images/become_sponsor.svg
     :target: https://opencollective.com/django-environ/contribute/sponsors-3474/checkout
     :alt: Become a Sponsor
 .. |ocbackerimage| image:: https://opencollective.com/django-environ/backers.svg?width=890
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is inspired by `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_
 and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 
+`v0.12.1`_ - 13-February-2026
+-----------------------------
+Fixed
++++++
+- Fixed PostgreSQL cluster URL parsing with bracketed IPv6 hosts in recent
+  Python versions, preventing failures in runtime URL parsing and related
+  regression tests
+  `#574 <https://github.com/joke2k/django-environ/issues/574>`_.
+- Fixed debug logging in ``Env.get_value()`` to avoid evaluating lazy default
+  objects when DEBUG logging is enabled
+  `#571 <https://github.com/joke2k/django-environ/issues/571>`_.
+
+
 `v0.12.0`_ - 8-November-2024
 -----------------------------
 Fixed
@@ -421,6 +434,7 @@ Added
 - Initial release.
 
 
+.. _v0.12.1: https://github.com/joke2k/django-environ/compare/v0.12.0...v0.12.1
 .. _v0.12.0: https://github.com/joke2k/django-environ/compare/v0.11.2...v0.12.0
 .. _v0.11.2: https://github.com/joke2k/django-environ/compare/v0.11.1...v0.11.2
 .. _v0.11.1: https://github.com/joke2k/django-environ/compare/v0.11.0...v0.11.1
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,3 +1,4 @@
+Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/README.rst b/README.rst
@@ -99,7 +99,7 @@ are loaded from a ``.env`` file and filled in ``os.environ`` with ``setdefault``
 method, to avoid to overwrite the real environ.
 A similar approach is used in
 `Two Scoops of Django <https://web.archive.org/web/20240121133956/https://www.feldroy.com/books/two-scoops-of-django-3-x>`_
-book and explained in `12factor-django <https://wellfire.co/learn/easier-12-factor-django>`_
+book and explained in `12factor-django <https://dev.to/ale_jacques/django-drf-12-factor-app-with-examples-36jg>`_
 article.
 
 
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
@@ -116,6 +117,7 @@ def find_version(meta_file):
     # Do not check links to compare tags.
     r"https://github.com/joke2k/django-environ/compare/.*",
 ]
+linkcheck_timeout = 60
 
 #
 # -- Options for nitpick -----------------------------------------------------
diff --git a/docs/docutils.conf b/docs/docutils.conf
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/environ/__init__.py b/environ/__init__.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/environ/compat.py b/environ/compat.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/environ/environ.py b/environ/environ.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
@@ -37,7 +38,7 @@
 )
 from .fileaware_mapping import FileAwareMapping
 
-Openable = (str, os.PathLike)
+OPENABLE = (str, os.PathLike)
 logger = logging.getLogger(__name__)
 
 
@@ -380,8 +381,8 @@ def get_value(self, var, cast=None, default=NOTSET, parse_default=False):
         """
 
         logger.debug(
-            "get '%s' casted as '%s' with default '%s'",
-            var, cast, default)
+            "get %r casted as %r with default type %s",
+            var, cast, type(default).__name__)
 
         var_name = f'{self.prefix}{var}'
         if var_name in self.scheme:
@@ -566,16 +567,25 @@ def db_url_config(cls, url, engine=None):
                 path += f':{url.port}'
 
         user_host = url.netloc.rsplit('@', 1)
-        if url.scheme in cls.POSTGRES_FAMILY and ',' in user_host[-1]:
+        db_netloc = unquote(user_host[-1])
+        if url.scheme in cls.POSTGRES_FAMILY and ',' in db_netloc:
             # Parsing postgres cluster dsn
-            hinfo = list(
-                itertools.zip_longest(
-                    *(
-                        host.rsplit(':', 1)
-                        for host in user_host[-1].split(',')
-                    )
-                )
-            )
+            host_parts = []
+            for host in db_netloc.split(','):
+                if host.startswith('['):
+                    end = host.find(']')
+                    if end != -1 and host[end + 1:end + 2] == ':':
+                        host_parts.append((host[:end + 1], host[end + 2:]))
+                    else:
+                        host_parts.append((host, ''))
+                else:
+                    hparts = host.rsplit(':', 1)
+                    if len(hparts) == 2 and hparts[1].isdigit():
+                        host_parts.append(tuple(hparts))
+                    else:
+                        host_parts.append((host, ''))
+
+            hinfo = list(itertools.zip_longest(*host_parts))
             hostname = ','.join(hinfo[0])
             port = ','.join(filter(None, hinfo[1])) if len(hinfo) == 2 else ''
         else:
@@ -922,10 +932,6 @@ def read_env(cls, env_file=None, overwrite=False, parse_comments=False,
         by the file content. ``overwrite=True`` will force an overwrite of
         existing environment variables.
 
-        Refs:
-
-        * https://wellfire.co/learn/easier-12-factor-django
-
         :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.
@@ -952,7 +958,7 @@ def read_env(cls, env_file=None, overwrite=False, parse_comments=False,
                 return
 
         try:
-            if isinstance(env_file, Openable):
+            if isinstance(env_file, OPENABLE):
                 # Python 3.5 support (wrap path with str).
                 with open(str(env_file), encoding=encoding) as f:
                     content = f.read()
diff --git a/environ/fileaware_mapping.py b/environ/fileaware_mapping.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/setup.py b/setup.py
@@ -2,6 +2,7 @@
 #
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/tests/__init__.py b/tests/__init__.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/tests/asserts.py b/tests/asserts.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/tests/fixtures.py b/tests/fixtures.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/tests/test_cache.py b/tests/test_cache.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
diff --git a/tests/test_channels.py b/tests/test_channels.py
@@ -1,12 +1,15 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # 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.
 
 from environ import Env
+import pytest
+from environ.compat import ImproperlyConfigured
 
 
 def test_channels_parsing():
@@ -23,3 +26,14 @@ def test_channels_parsing():
     result = Env.channels_url_config(url)
     assert result["BACKEND"] == "channels_redis.pubsub.RedisPubSubChannelLayer"
     assert result["CONFIG"]["hosts"][0] == "redis://user:password@localhost:6379/0"
+
+
+def test_channels_backend_override():
+    result = Env.channels_url_config("unsupported://", backend="custom.backend")
+    assert result["BACKEND"] == "custom.backend"
+
+
+def test_channels_invalid_schema():
+    with pytest.raises(ImproperlyConfigured) as exc:
+        Env.channels_url_config("unsupported://")
+    assert 'Invalid channels schema unsupported' == str(exc.value)
diff --git a/tests/test_db.py b/tests/test_db.py
@@ -1,5 +1,6 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>
 #
@@ -224,6 +225,37 @@ def test_postgres_complex_db_name_parsing():
     assert url['PORT'] == ''
 
 
+def test_postgres_cluster_with_ipv6_parsing():
+    """Parse postgres cluster URLs containing bracketed IPv6 hosts."""
+    env_url = (
+        'postgres://username:p@ss:12,wor:34d@'
+        'host1:111,22.55.44.88:222,[2001:db8::1234]:333/db'
+    )
+
+    url = Env.db_url_config(env_url)
+
+    assert url['ENGINE'] == DJANGO_POSTGRES
+    assert url['NAME'] == 'db'
+    assert url['HOST'] == 'host1,22.55.44.88,[2001:db8::1234]'
+    assert url['USER'] == 'username'
+    assert url['PASSWORD'] == 'p@ss:12,wor:34d'
+    assert url['PORT'] == '111,222,333'
+
+
+def test_postgres_cluster_with_ipv6_without_port_parsing():
+    """Keep bracketed IPv6 hosts in cluster URLs even when port is omitted."""
+    env_url = 'postgres://user:pass@host1:111,[2001:db8::1234],host3:333/db'
+
+    url = Env.db_url_config(env_url)
+
+    assert url['ENGINE'] == DJANGO_POSTGRES
+    assert url['NAME'] == 'db'
+    assert url['HOST'] == 'host1,[2001:db8::1234],host3'
+    assert url['USER'] == 'user'
+    assert url['PASSWORD'] == 'pass'
+    assert url['PORT'] == '111,333'
+
+
 @pytest.mark.parametrize(
     'scheme',
     ['postgres', 'postgresql', 'psql', 'pgsql', 'postgis'],
@@ -267,6 +299,19 @@ def test_memory_sqlite_url_warns_about_netloc(recwarn):
     assert url['NAME'] == ':memory:'
 
 
+def test_ldap_url_with_port():
+    """Keep LDAP host and include port in NAME when explicitly provided."""
+    env_url = 'ldap://cn=admin,dc=nodomain,dc=org:secret@example.com:1234'
+    url = Env.db_url_config(env_url)
+
+    assert url['ENGINE'] == 'ldapdb.backends.ldap'
+    assert url['NAME'] == 'ldap://example.com:1234'
+    assert url['HOST'] == 'example.com'
+    assert url['USER'] == 'cn=admin,dc=nodomain,dc=org'
+    assert url['PASSWORD'] == 'secret'
+    assert url['PORT'] == 1234
+
+
 def test_database_options_parsing():
     url = 'postgres://user:pass@host:1234/dbname?conn_max_age=600'
     url = Env.db_url_config(url)
@@ -285,3 +330,11 @@ def test_database_options_parsing():
     assert url['OPTIONS'] == {
         'init_command': 'SET storage_engine=INNODB',
     }
+
+
+def test_unknown_engine_warns_and_returns_empty_dict(recwarn):
+    result = Env.db_url_config('localhost')
+
+    assert result == {}
+    assert len(recwarn) == 1
+    assert recwarn.pop(UserWarning)
diff --git a/tests/test_email.py b/tests/test_email.py
@@ -1,12 +1,15 @@
 # This file is part of the django-environ.
 #
+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>
 # Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>
 # 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.
 
 from environ import Env
+from environ.compat import ImproperlyConfigured
+import pytest
 
 
 def test_smtp_parsing():
@@ -32,3 +35,21 @@ def test_custom_email_backend():
     url = Env.email_url_config(url, backend=backend)
 
     assert url['EMAIL_BACKEND'] == backend
+
+
+def test_smtp_ssl_and_options_parsing():
+    url = (
+        "smtp+ssl://user@domain.com:password@smtp.example.com:465"
+        "?EMAIL_USE_SSL=true&timeout=30"
+    )
+    url = Env.email_url_config(url)
+
+    assert url['EMAIL_BACKEND'] == 'django.core.mail.backends.smtp.EmailBackend'
+    assert url['EMAIL_USE_SSL'] == 'true'
+    assert url['OPTIONS'] == {'TIMEOUT': 30}
+
+
+def test_invalid_email_schema():
+    with pytest.raises(ImproperlyConfigured) as exc:
+        Env.email_url_config('smtp3://user:password@example.com:25')
+    assert 'Invalid email schema smtp3' == str(exc.value)
diff --git a/tests/test_env.py b/tests/test_env.py
diff --git a/tests/test_fileaware.py b/tests/test_fileaware.py
diff --git a/tests/test_path.py b/tests/test_path.py
diff --git a/tests/test_schema.py b/tests/test_schema.py
diff --git a/tests/test_search.py b/tests/test_search.py
diff --git a/tests/test_utils.py b/tests/test_utils.py
diff --git a/tox.ini b/tox.ini

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`# This file is part of the django-environ.`
`2`	`2`	`#`
	`3`	`+# Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>`
`3`	`4`	`# Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>`
`4`	`5`	`# Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>`
`5`	`6`	`#`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+Copyright (c) 2024-present, Daniele Faraglia <daniele.faraglia@gmail.com>`
`1`	`2`	`Copyright (c) 2021-2024, Serghei Iakovlev <oss@serghei.pl>`
`2`	`3`	`Copyright (c) 2013-2021, Daniele Faraglia <daniele.faraglia@gmail.com>`
`3`	`4`