Add ability to pass prefix

Add 'prefix' keyword argument to 'environ.to_config()',
'environ.generate_help()' and related class methods.

Author: Denis Savran

CHANGELOG.md

@@ -18,6 +18,10 @@ Whenever there is a need to break compatibility, it is announced here in the cha
 
 ## [Unreleased](https://github.com/hynek/environ-config/compare/24.1.0...HEAD)
 
+### Changed
+
+- Add `prefix` keyword argument to `environ.to_config()`, `environ.generate_help()` and related class methods.
+  [#89](https://github.com/hynek/environ-config/pull/89)
 
 ## [24.1.0](https://github.com/hynek/environ-config/compare/23.2.0...24.1.0) - 2024-08-08
 

src/environ/_environ_config.py

@@ -118,11 +118,19 @@ def config(
     """
 
     def wrap(cls):
-        def from_environ_fnc(cls, environ=os.environ):
-            return __to_config(cls, environ)
-
-        def generate_help_fnc(cls, **kwargs):
-            return __generate_help(cls, **kwargs)
+        def from_environ_fnc(
+            cls, environ=os.environ, *, prefix=PREFIX_NOT_SET
+        ):
+            return __to_config(cls, environ, prefix=prefix)
+
+        def generate_help_fnc(
+            cls,
+            formatter=None,
+            *,
+            prefix=PREFIX_NOT_SET,
+            **kwargs,
+        ):
+            return __generate_help(cls, formatter, prefix=prefix, **kwargs)
 
         cls._prefix = prefix
         if from_environ is not None:
@@ -168,7 +176,7 @@ def var(
 
         converter:
             A callable that is run with the found value and its return value is
-            used.  Please not that it is also run for default values.
+            used. Please note that it is also run for default values.
 
         validator:
             A callable that is run with the final value. See *attrs*'s `chapter
@@ -256,12 +264,14 @@ class Sub:
     )
 
 
-def _default_getter(environ, metadata, prefix, name):
+def _default_getter(environ, metadata, prefixes, name):
     """
     This default lookup implementation simply gets values from *environ*.
     """
     ce = metadata[CNF_KEY]
-    var = ce.name if ce.name is not None else "_".join((*prefix, name)).upper()
+    var = (
+        ce.name if ce.name is not None else "_".join((*prefixes, name)).upper()
+    )
     log.debug("looking for env var '%s'.", var)
     try:
         return environ[var]
@@ -328,24 +338,46 @@ def _to_config_recurse(config_cls, environ, prefixes, default=RAISE):
     return config_cls(**defaulted)
 
 
-def to_config(config_cls: type[T], environ: dict[str, str] = os.environ) -> T:
+def to_config(
+    config_cls: type[T],
+    environ: dict[str, str] = os.environ,
+    *,
+    prefix: str | Sentinel = PREFIX_NOT_SET,
+) -> T:
     """
     Load the configuration as declared by *config_cls* from *environ*.
 
     Args:
         config_cls: The configuration class to fill.
 
-        environ: Source of the configuration.  `os.environ` by default.
+        environ: Source of the configuration. `os.environ` by default.
+
+        prefix:
+            Prefix that is used for environment variables. May be used to
+            dynamically change a prefix or to instantiate a nested
+            configuration class without all of its parent configuration
+            classes.
 
     Returns:
         An instance of *config_cls*.
 
+    Examples:
+
+        .. code-block:: python
+
+            environ.to_config(ComponentConfig, prefix="APP_COMPONENT")
+
     This is equivalent to calling ``config_cls.from_environ()``.
+
+    .. versionadded:: 24.2.0 *prefix*
     """
     # The canonical app prefix might be falsey in which case we'll still set
     # the default prefix for this top level config object
-    app_prefix = tuple(p for p in (_get_prefix(config_cls),) if p)
-    return _to_config_recurse(config_cls, environ, app_prefix)
+    if prefix is PREFIX_NOT_SET:
+        prefix = _get_prefix(config_cls)
+
+    prefixes = (prefix,) if prefix else ()
+    return _to_config_recurse(config_cls, environ, prefixes)
 
 
 def _format_help_dicts(help_dicts, display_defaults=False):
@@ -457,7 +489,11 @@ def _generate_help_dicts(config_cls, _prefix=PREFIX_NOT_SET):
 
 
 def generate_help(
-    config_cls: type[T], formatter: Callable | None = None, **kwargs: Any
+    config_cls: type[T],
+    formatter: Callable | None = None,
+    *,
+    prefix: str | Sentinel = PREFIX_NOT_SET,
+    **kwargs: Any,
 ) -> str:
     """
     Autogenerate a help string for a config class.
@@ -472,16 +508,29 @@ def generate_help(
             When using the default formatter, passing `True` for
             *display_defaults* makes the default values part of the output.
 
+        prefix:
+            Prefix that is used for environment variables. May be used to
+            dynamically change a prefix or to generate a help string for a
+            nested configuration class without all of its parent configuration
+            classes.
+
     Returns:
         A help string that can be printed to the user.
 
+    Examples:
+
+        .. code-block:: python
+
+            environ.generate_help(ComponentConfig, prefix="APP_COMPONENT")
+
     This is equivalent to calling ``config_cls.generate_help()``.
 
     .. versionadded:: 19.1.0
+    .. versionadded:: 24.2.0 *prefix*
     """
     if formatter is None:
         formatter = _format_help_dicts
-    help_dicts = _generate_help_dicts(config_cls)
+    help_dicts = _generate_help_dicts(config_cls, prefix)
 
     return formatter(help_dicts, **kwargs)
 

tests/test_class_generate_help.py

@@ -76,3 +76,15 @@ def test_generated_helps_equals_display_defaults(display_defaults):
     assert environ.generate_help(
         ConfigRenamed, display_defaults=display_defaults
     ) == ConfigRenamed.gen_help(display_defaults=display_defaults)
+
+
+def test_generate_help_with_prefix():
+    """
+    Class methods generate help using a passed prefix.
+    """
+    assert environ.generate_help(
+        AppConfig, prefix="FOO"
+    ) == AppConfig.generate_help(prefix="FOO")
+    assert environ.generate_help(
+        ConfigRenamed, prefix="BAR"
+    ) == ConfigRenamed.gen_help(prefix="BAR")

tests/test_class_to_config.py

@@ -99,3 +99,30 @@ class FactoryConfig:
 
     assert cfg.x == []
     assert cfg.y == "baz"
+
+
+def test_from_environ_with_prefix():
+    """
+    Class methods create a config using a passed prefix.
+    """
+    foo_environ = {
+        "APP_HOST": "nope",
+        "APP_PORT": "0",
+        "FOO_HOST": "foo",
+        "FOO_PORT": "1",
+    }
+
+    assert environ.to_config(
+        AppConfig, foo_environ, prefix="FOO"
+    ) == AppConfig.from_environ(foo_environ, prefix="FOO")
+
+    bar_environ = {
+        "APP_HOST": "nope",
+        "APP_PORT": "0",
+        "BAR_HOST": "bar",
+        "BAR_PORT": "2",
+    }
+
+    assert environ.to_config(
+        ConfigRenamed, bar_environ, prefix="BAR"
+    ) == ConfigRenamed.from_env(bar_environ, prefix="BAR")

tests/test_environ_config.py

@@ -106,6 +106,25 @@ def test_nested(self):
 
         assert Nested(x="foo", sub=Nested.Sub(y="bar")) == cfg
 
+    def test_nested_with_prefix(self):
+        """
+        A config is created using a passed prefix.
+        """
+        env = {"XYZ_X": "nope", "TMP_X": "foo", "TMP_SUB_Y": "bar"}
+        cfg = environ.to_config(Nested, env, prefix="TMP")
+
+        assert Nested(x="foo", sub=Nested.Sub(y="bar")) == cfg
+
+    def test_nested_with_prefix_only_child_config(self):
+        """
+        A config is created only for a child config class using a passed
+        prefix.
+        """
+        env = {"XYZ_X": "nope", "XYZ_SUB_Y": "bar"}
+        cfg = environ.to_config(Nested.Sub, env, prefix="XYZ_SUB")
+
+        assert Nested.Sub(y="bar") == cfg
+
     def test_missing(self):
         """
         If a var is missing, a human-readable MissingEnvValueError is raised.
@@ -235,11 +254,11 @@ class Cfg:
 
         assert Cfg("e", 42) == cfg
 
-    def test_generate_help_str(self):
+    def test_generate_help(self):
         """
         A help string is generated for a config class.
 
-        Presence of defaults are indicated but they are not shown.
+        Presence of defaults is indicated, but they are not shown.
         """
         help_str = environ.generate_help(Parent)
         assert (
@@ -260,7 +279,7 @@ def test_generate_help_str(self):
 FOO_CHILD_VAR14 (Required)"""
         )
 
-    def test_generate_help_str_with_defaults(self):
+    def test_generate_help_with_defaults(self):
         """
         A help string is generated for a config class.
 
@@ -286,7 +305,49 @@ def test_generate_help_str_with_defaults(self):
 FOO_CHILD_VAR14 (Required)"""
         )
 
-    def test_generate_help_str_when_prefix_is_empty(self):
+    def test_generate_help_with_prefix(self):
+        """
+        A help string is generated for a config class using a passed
+        prefix.
+        """
+        help_str = environ.generate_help(Parent, prefix="BAR")
+        assert (
+            help_str
+            == """BAR_VAR1 (Required): var1, no default
+BAR_VAR2 (Optional): var2, has default
+BAR_VAR3 (Required): var3, bool_var, no default
+BAR_VAR4 (Optional): var4, bool_var, has default
+DOG (Optional): var5, named, has default
+CAT (Required): var6, named, no default
+BAR_CHILD_VAR7 (Required): var7, no default
+BAR_CHILD_VAR8 (Optional): var8, has default
+BAR_CHILD_VAR9 (Required): var9, bool_var, no default
+BAR_CHILD_VAR10 (Optional): var10, bool_var, has default
+DOG2 (Optional): var11, named, has default
+CAT2 (Required): var12, named, no default
+BAR_CHILD_VAR13 (Optional)
+BAR_CHILD_VAR14 (Required)"""
+        )
+
+    def test_generate_help_with_prefix_only_child_config(self):
+        """
+        A help string is generated only for a child config class using a
+        passed prefix.
+        """
+        help_str = environ.generate_help(Parent.Child, prefix="FOO_CHILD")
+        assert (
+            help_str
+            == """FOO_CHILD_VAR7 (Required): var7, no default
+FOO_CHILD_VAR8 (Optional): var8, has default
+FOO_CHILD_VAR9 (Required): var9, bool_var, no default
+FOO_CHILD_VAR10 (Optional): var10, bool_var, has default
+DOG2 (Optional): var11, named, has default
+CAT2 (Required): var12, named, no default
+FOO_CHILD_VAR13 (Optional)
+FOO_CHILD_VAR14 (Required)"""
+        )
+
+    def test_generate_help_no_prefix(self):
         """
         Environment variables' names don't start with an underscore
         """

tests/typing/api.py

@@ -54,7 +54,7 @@ class Sub:
     a_secret: str = aws_secrets.secret()
 
 
-h: str = environ.generate_help(Config)
+h: str = environ.generate_help(Config, prefix="APP")
 
 cfg = environ.to_config(Config, {"APP_X": "123"})