Deprecate non-1.9 compatible configuration environment names (#1592)

* Deprecate non-1.9 compatible configuration environment names (in warnings and docs)

* add localmemory to spellcheck list.

* add lintage...

* Oops - environment name pattern doesn't quite match that applied in 1.9.

datacube/config.py

@@ -6,6 +6,8 @@
 User configuration.
 """
 
+import warnings
+import re
 import os
 from pathlib import Path
 import configparser
@@ -92,6 +94,11 @@ def __init__(self, config: configparser.ConfigParser,
         if env:
             if config.has_section(env):
                 self._env = env
+                if not re.fullmatch(r'^[a-z][a-z0-9]*$', self._env):
+                    warnings.warn(f"Configuration environment names like '{self._env}' are deprecated. "
+                                  "From datacube 1.9, environment names must start with a lowercase letter and "
+                                  "consist of only lowercase letters and digits.",
+                                  category=DeprecationWarning)
                 # All is good
                 return
             else:

docs/about/whats_new.rst

@@ -8,6 +8,8 @@ What's New
 v1.8.next
 =========
 
+- Add deprecation warning for config environment names that will not be supported in 1.9 (:pull:`1592`)
+- Update docker image to GDAL 3.9/Python 3.12/Ubuntu 24.04 (:pull:`1587`)
 - Update readthedocs stylesheet for dark theme (:pull:`1579`)
 
 v1.8.18 (27th March 2024)

docs/installation/database/setup.rst

@@ -48,7 +48,7 @@ Datacube looks for a configuration file in ~/.datacube.conf or in the location s
 
     # A blank host will use a local socket. Specify a hostname (such as localhost) to use TCP.
     db_hostname:
-    
+
     # Port is optional. The default port is 5432.
     # db_port:
 
@@ -66,13 +66,14 @@ Datacube looks for a configuration file in ~/.datacube.conf or in the location s
     # A "null" environment for working with no index.
     index_driver: null
 
-    [local_memory]
+    [localmemory]
     # A local non-persistent in-memory index.
     #   Compatible with the default index driver, but resides purely in memory with no persistent database.
     #   Note that each new invocation will receive a new, empty index.
     index_driver: memory
 
-Uncomment and fill in lines as required.
+Uncomment and fill in lines as required.   Environment names should start with a lower case letter and contain
+only lower case letters and numbers.  This will be strictly enforced from 1.9.0.
 
 Alternately, you can configure the ODC connection to Postgres using environment variables::
 
@@ -82,17 +83,13 @@ Alternately, you can configure the ODC connection to Postgres using environment
     DB_DATABASE
 
 To configure a database as a single connection url instead of individual environment variables::
-    
+
     export DATACUBE_DB_URL=postgresql://[username]:[password]@[hostname]:[port]/[database]
 
 Alternatively, for password-less access to a database on localhost::
 
     export DATACUBE_DB_URL=postgresql:///[database]
 
-Further information on database configuration can be found `here <https://github.com/opendatacube/datacube-core/wiki/ODC-EP-010---Replace-Configuration-Layer>`__.
-Although the enhancement proposal details incoming changes in v1.9 and beyond, it should largely be compatible with the current behaviour, barring a few
-obscure corner cases.
-
 The desired environment can be specified:
 
 1. in code, with the ``env`` argument to the ``datacube.Datacube`` constructor;

integration_tests/conftest.py

@@ -465,14 +465,14 @@ def local_config_pair(datacube_env_name_pair):
 def null_config():
     """Provides a :class:`LocalConfig` configured with null index driver
     """
-    return LocalConfig.find(CONFIG_FILE_PATHS, env="null_driver")
+    return LocalConfig.find(CONFIG_FILE_PATHS, env="nulldriver")
 
 
 @pytest.fixture
 def in_memory_config():
     """Provides a :class:`LocalConfig` configured with memory index driver
     """
-    return LocalConfig.find(CONFIG_FILE_PATHS, env="local_memory")
+    return LocalConfig.find(CONFIG_FILE_PATHS, env="localmemory")
 
 
 @pytest.fixture

integration_tests/integration.conf

@@ -8,11 +8,11 @@ db_hostname:
 db_database: pgisintegration
 index_driver: postgis
 
-[no_such_driver_env]
+[nosuchdriverenv]
 index_driver: no_such_driver
 
-[null_driver]
+[nulldriver]
 index_driver: null
 
-[local_memory]
+[localmemory]
 index_driver: memory

integration_tests/test_environments.py

@@ -19,15 +19,15 @@ def test_multiple_environment_config(tmpdir):
 [default]
 db_hostname: db.opendatacube.test
 
-[test_alt]
+[testalt]
 db_hostname: alt-db.opendatacube.test
     """)
 
     config_path = str(config_path)
 
     config = LocalConfig.find([config_path])
     assert config['db_hostname'] == 'db.opendatacube.test'
-    alt_config = LocalConfig.find([config_path], env='test_alt')
+    alt_config = LocalConfig.find([config_path], env='testalt')
     assert alt_config['db_hostname'] == 'alt-db.opendatacube.test'
 
     # Make sure the correct config is passed through the API
@@ -42,12 +42,12 @@ def test_multiple_environment_config(tmpdir):
     with Datacube(config=str(config_path), validate_connection=False) as dc:
         assert str(dc.index.url) == db_url
     # When specific environment is loaded
-    with Datacube(config=config_path, env='test_alt', validate_connection=False) as dc:
+    with Datacube(config=config_path, env='testalt', validate_connection=False) as dc:
         assert str(dc.index.url) == alt_db_url
 
     # An environment that isn't in any config files
     with pytest.raises(ValueError):
-        with Datacube(config=config_path, env='undefined-env', validate_connection=False) as dc:
+        with Datacube(config=config_path, env='undefinedenv', validate_connection=False) as dc:
             pass
 
 

wordlist.txt

@@ -261,6 +261,7 @@ libyaml
 linux
 literalinclude
 localhost
+localmemory
 lon
 lonlat
 lr