exclude children from description

CHANGELOG.md

@@ -1,4 +1,7 @@
 # envolved Changelog
+## 1.2.1
+### Fixed
+* The children of envvars that are excluded from the description are now also excluded.
 ## 1.2.0
 ### Added
 * new argument `strip_items` for `CollectionParser`.

docs/envvar.rst

@@ -28,7 +28,7 @@ EnvVars
             pos_args: collections.base.Sequence[envvar.EnvVar | InferEnvVar] = ..., \
             description: str | collections.abc.Sequence[str] | None = None,\
             validators: collections.abc.Iterable[collections.abc.Callable[[T], T]] = (), \
-            on_partial: T | missing | as_default | discard = missing) -> envvar.SchemaEnvVar[T]:
+            on_partial: T | missing | as_default | discard = missing) -> envvar.SchemaEnvVar[T]
     :noindex:
 
     Creates an EnvVar that reads from multiple environment variables.
@@ -217,7 +217,7 @@ EnvVars
 
             The EnvVar's :attr:`default` must not be :data:`missing` if this option is used.
 
-        * If set to :data:`missing`, an :exc:`~exceptions.MissingEnvError` will be raised, even if the EnvVar's
+        * If set to :data:`missing`, a :exc:`~exceptions.MissingEnvError` will be raised, even if the EnvVar's
           :attr:`~EnvVar.default` is set.
         * If set to a value, that value will be returned.
 

envolved/_version.py

@@ -1 +1 @@
-__version__ = "1.2.0"
+__version__ = "1.2.1"

envolved/describe/__init__.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
+from itertools import chain
 from typing import Any, Iterable, List, Mapping, Set, TypeVar, Union
 
 from envolved.describe.flat import FlatEnvVarsDescription
 from envolved.describe.nested import NestedEnvVarsDescription, RootNestedDescription
-from envolved.envvar import EnvVar, InferEnvVar, top_level_env_vars
+from envolved.envvar import EnvVar, InferEnvVar, all_env_vars
 
 
 def describe_env_vars(**kwargs: Any) -> List[str]:
@@ -19,12 +20,20 @@ def __init__(self, env_vars: Iterable[EnvVar] | None = None) -> None:
         children: Set[EnvVar] = set()
 
         if env_vars is None:
-            env_vars = top_level_env_vars
+            env_vars = all_env_vars
+            to_exclude = roots_to_exclude_from_description | set(
+                chain.from_iterable(r._get_descendants() for r in roots_to_exclude_from_description)
+            )
+        else:
+            to_exclude = set()
+
         for env_var in env_vars:
             self.env_var_roots.add(env_var)
             children.update(env_var._get_descendants())
         # remove any children we found along the way
         self.env_var_roots -= children
+        # remove any children we were asked to exclude
+        self.env_var_roots -= to_exclude
 
     def flat(self) -> FlatEnvVarsDescription:
         return FlatEnvVarsDescription.from_envvars(self.env_var_roots)
@@ -38,21 +47,20 @@ def nested(self) -> NestedEnvVarsDescription:
     bound=Union[EnvVar, InferEnvVar, Iterable[Union[EnvVar, InferEnvVar]], Mapping[Any, Union[EnvVar, InferEnvVar]]],
 )
 
+roots_to_exclude_from_description: Set[EnvVar] = set()
 
-def exclude_from_description(to_exclude: T) -> T:
-    global top_level_env_vars  # noqa: PLW0603
 
+def exclude_from_description(to_exclude: T) -> T:
     if isinstance(to_exclude, EnvVar):
-        evs = frozenset((to_exclude,))
-    elif isinstance(to_exclude, InferEnvVar):
-        evs = frozenset()
+        roots_to_exclude_from_description.add(to_exclude)
     elif isinstance(to_exclude, Mapping):
-        evs = frozenset(to_exclude.values())
+        exclude_from_description(to_exclude.values())
     elif isinstance(to_exclude, Iterable):
-        evs = frozenset(to_exclude)
+        for v in to_exclude:
+            exclude_from_description(v)
+    elif isinstance(to_exclude, InferEnvVar):
+        pass
     else:
         raise TypeError(f"cannot exclude unrecognized type {type(to_exclude)!r}")
 
-    top_level_env_vars -= evs
-
     return to_exclude

envolved/envvar.py

@@ -438,13 +438,13 @@ def env_var(  # type: ignore[misc]
     return register_env_var(ev)
 
 
-top_level_env_vars: MutableSet[EnvVar] = WeakSet()
+all_env_vars: MutableSet[EnvVar] = WeakSet()
 
 EV = TypeVar("EV", bound=EnvVar)
 
 
 def register_env_var(ev: EV) -> EV:
-    top_level_env_vars.add(ev)
+    all_env_vars.add(ev)
     return ev
 
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "envolved"
-version = "1.2.0"
+version = "1.2.1"
 description = ""
 authors = ["ben avrahami <[email protected]>"]
 license = "MIT"

tests/unittests/test_describe.py

@@ -20,7 +20,14 @@ def test_describe():
     }
     exclude_from_description(point_args)
 
-    p = env_var("p_", type=SimpleNamespace, args=point_args)  # noqa: F841
+    _p = exclude_from_description(env_var("_p_", type=SimpleNamespace, args=point_args))
+
+    p = env_var("p_", type=SimpleNamespace, args=point_args)
+
+    _w_p = exclude_from_description(p.with_prefix("_w_"))
+
+    j_p = _p.with_prefix("j")
+    j_p.description = "j point"
 
     q = env_var(  # noqa: F841
         "q_",
@@ -51,6 +58,9 @@ def test_describe():
     assert describe_env_vars() == [
         "A: full description of A",
         "B",
+        "j point:",
+        " J_P_X: x coordinate",
+        " J_P_Y: y coordinate",
         " P_X: x coordinate",
         " P_Y: y coordinate",
         "point Q next line:",