envstack 1.0.3__tar.gz → 1.0.4__tar.gz

{envstack-1.0.3/lib/envstack.egg-info → envstack-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: envstack
-Version: 1.0.3
+Version: 1.0.4
 Summary: Environment variable composition layer for tools and processes.
 Author-email: Ryan Galloway <ryan@rsgalloway.com>
 License: BSD 3-Clause License
@@ -29,6 +29,16 @@ License-File: LICENSE
 Requires-Dist: PyYAML>=5.1.2
 Requires-Dist: cryptography<47,>=43.0.1; python_version < "3.9"
 Requires-Dist: cryptography>=43.0.1; python_version >= "3.9"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: flake8==7.1.1; extra == "dev"
+Requires-Dist: mccabe==0.7.0; extra == "dev"
+Requires-Dist: isort==5.13.2; extra == "dev"
+Requires-Dist: black==24.8.0; extra == "dev"
+
+<p align="center">
+  <img src="docs/assets/envstack.png" alt="envstack logo" width="560">
+</p>
 
 envstack
 ========

{envstack-1.0.3 → envstack-1.0.4}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="docs/assets/envstack.png" alt="envstack logo" width="560">
+</p>
+
 envstack
 ========
 

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack/__init__.py

@@ -34,7 +34,6 @@ Stacked environment variable management system.
 """
 
 __prog__ = "envstack"
-__version__ = "1.0.3"
+__version__ = "1.0.4"
 
-from envstack.env import clear, init, revert, save  # noqa: F401
-from envstack.env import load_environ, resolve_environ  # noqa: F401
+from envstack.env import clear, init, load_environ, resolve_environ, revert, save  # noqa: F401

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack/cli.py

@@ -42,11 +42,11 @@ from typing import List
 
 from envstack import __version__, config
 from envstack.env import (
-    bake_environ,
     Env,
+    bake_environ,
     encrypt_environ,
-    export_env_to_shell,
     export,
+    export_env_to_shell,
     load_environ,
     resolve_environ,
     trace_var,
@@ -394,9 +394,7 @@ def main():
             if args.depth:
                 print("error: --depth is not valid with --resolve")
                 return 2
-            resolved = resolve_environ(
-                load_environ(args.namespace, platform=args.platform)
-            )
+            resolved = resolve_environ(load_environ(args.namespace, platform=args.platform))
             if args.set:
                 resolved.update(_parse_keyvals(args.set))
             if args.encrypt:
@@ -456,9 +454,7 @@ def main():
                 print(source.path)
 
         elif args.unresolved:
-            env = load_environ(
-                args.namespace, platform=args.platform, encrypt=args.encrypt
-            )
+            env = load_environ(args.namespace, platform=args.platform, encrypt=args.encrypt)
             for k, v in sorted(env.items(), key=lambda x: str(x[0])):
                 print(f"{k}={v}")
 

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack/encrypt.py

@@ -53,6 +53,7 @@ padding = None
 Cipher = None
 algorithms = None
 modes = None
+default_backend = None
 try:
     # cryptography emits a Python 3.8 deprecation warning during import.
     with warnings.catch_warnings():
@@ -62,8 +63,9 @@ try:
             category=DeprecationWarning,
             module=r"cryptography(\..*)?$",
         )
-        from cryptography.fernet import Fernet, InvalidToken
         from cryptography.exceptions import InvalidTag
+        from cryptography.fernet import Fernet, InvalidToken
+        from cryptography.hazmat.backends import default_backend
         from cryptography.hazmat.primitives import padding
         from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
 
@@ -214,7 +216,7 @@ class AESGCMEncryptor(object):
         :return: Dictionary containing nonce, ciphertext, and tag.
         """
         nonce = os.urandom(12)  # GCM requires a 12-byte nonce
-        cipher = Cipher(algorithms.AES(self.key), modes.GCM(nonce))
+        cipher = Cipher(algorithms.AES(self.key), modes.GCM(nonce), backend=default_backend())
         encryptor = cipher.encryptor()
         padded_data = pad_data(secret)
         ciphertext = encryptor.update(padded_data) + encryptor.finalize()
@@ -235,7 +237,11 @@ class AESGCMEncryptor(object):
         nonce = b64decode(encrypted_data["nonce"])
         ciphertext = b64decode(encrypted_data["ciphertext"])
         tag = b64decode(encrypted_data["tag"])
-        cipher = Cipher(algorithms.AES(self.key), modes.GCM(nonce, tag))
+        cipher = Cipher(
+            algorithms.AES(self.key),
+            modes.GCM(nonce, tag),
+            backend=default_backend(),
+        )
         decryptor = cipher.decryptor()
         padded_data = decryptor.update(ciphertext) + decryptor.finalize()
         return unpad_data(padded_data)

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack/env.py

@@ -43,12 +43,7 @@ import yaml  # noqa
 
 from envstack import config, logger, path, util
 from envstack.exceptions import *  # noqa
-from envstack.node import (
-    BaseNode,
-    EncryptedNode,
-    custom_node_types,
-    get_keys_from_env,
-)
+from envstack.node import BaseNode, EncryptedNode, custom_node_types, get_keys_from_env
 
 # value delimiter pattern (splits values by os.pathsep)
 delimiter_pattern = re.compile("(?![^{]*})[;:]+")
@@ -468,9 +463,7 @@ def get_sources(
                 logger.log.warning(f"Error accessing {potential_file}")
                 continue
         if not found_files and not ignore_missing:
-            raise TemplateNotFound(  # noqa
-                f"{file_basename} not found in ENVPATH or scope."
-            )
+            raise TemplateNotFound(f"{file_basename} not found in ENVPATH or scope.")  # noqa
         return found_files
 
     def _load_file(file_basename):
@@ -787,9 +780,7 @@ def bake_environ(
     return load_environ(name, scope=scope).bake(filename, depth, encrypt)
 
 
-def encrypt_environ(
-    env: dict, node_class: BaseNode = EncryptedNode, encrypt: bool = True
-):
+def encrypt_environ(env: dict, node_class: BaseNode = EncryptedNode, encrypt: bool = True):
     """Encrypts all values in a given environment, returning a new environment.
     Looks for encryption keys in the environment.
 

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack/node.py

@@ -306,9 +306,7 @@ class CustomDumper(yaml.SafeDumper):
 
         # set basekey for the node
         if self.depth == 2:
-            assert isinstance(node, yaml.ScalarNode), (
-                "yaml node not a string: %s" % node
-            )
+            assert isinstance(node, yaml.ScalarNode), "yaml node not a string: %s" % node
             self.basekey = str(node.value)
             node.value = self.basekey
 

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack/path.py

@@ -189,9 +189,7 @@ class Path(str):
             from_env = _load_resolved_stack(stack, platform=self.platform, scope=scope)
             to_env = _load_resolved_stack(stack, platform=platform, scope=scope)
         except Exception as err:
-            raise InvalidPath(
-                f"Failed to load stack '{stack}' for platform conversion: {err}"
-            )
+            raise InvalidPath(f"Failed to load stack '{stack}' for platform conversion: {err}")
 
         from_root = from_env.get(root_var)
         to_root = to_env.get(root_var)
@@ -335,15 +333,11 @@ def extract_fields(
     try:
         p = Path(filepath, platform=platform)
         if isinstance(template, str):
-            template = get_template(
-                template, stack=stack, platform=platform, scope=p.scope()
-            )
+            template = get_template(template, stack=stack, platform=platform, scope=p.scope())
         return template.get_fields(filepath)
 
     except InvalidPath:  # noqa
-        logger.log.debug(
-            "path does not match template: {0} {1}".format(template, filepath)
-        )
+        logger.log.debug("path does not match template: {0} {1}".format(template, filepath))
         return {}
 
     except Exception as err:

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack/util.py

@@ -45,13 +45,7 @@ from collections import OrderedDict
 import yaml
 
 from envstack import config
-from envstack.node import (
-    AESGCMNode,
-    Base64Node,
-    EncryptedNode,
-    FernetNode,
-    CustomLoader,
-)
+from envstack.node import AESGCMNode, Base64Node, CustomLoader, EncryptedNode, FernetNode
 
 # default memoization cache timeout in seconds
 CACHE_TIMEOUT = 5
@@ -63,9 +57,7 @@ null = ""
 drive_letter_pattern = re.compile(r"(?P<sep>[:;])?(?P<drive>[A-Z]:[/\\])")
 
 # regular expression pattern for bash-like variable expansion
-variable_pattern = re.compile(
-    r"\$\{([a-zA-Z_][a-zA-Z0-9_]*)(?::([-=?])((?:\$\{[^}]+\}|[^}])*))?\}"
-)
+variable_pattern = re.compile(r"\$\{([a-zA-Z_][a-zA-Z0-9_]*)(?::([-=?])((?:\$\{[^}]+\}|[^}])*))?\}")
 
 # regular expression pattern for command substitution
 cmdsub_pattern = re.compile(r"^\s*\$\((?P<cmd>.*)\)\s*$", re.DOTALL)
@@ -172,9 +164,7 @@ def split_windows_paths(path_str: str):
             result += [
                 p
                 for part in modified.split("|")
-                for p in re.split(
-                    r"(?<![A-Z]):", part
-                )  # capture colons not in drive letters
+                for p in re.split(r"(?<![A-Z]):", part)  # capture colons not in drive letters
                 if p
             ]
         else:
@@ -271,9 +261,7 @@ def dict_diff(dict1: dict, dict2: dict):
     """
     added = {k: dict2[k] for k in dict2 if k not in dict1}
     removed = {k: dict1[k] for k in dict1 if k not in dict2}
-    changed = {
-        k: (dict1[k], dict2[k]) for k in dict1 if k in dict2 and dict1[k] != dict2[k]
-    }
+    changed = {k: (dict1[k], dict2[k]) for k in dict1 if k in dict2 and dict1[k] != dict2[k]}
     unchanged = {k: dict1[k] for k in dict1 if k in dict2 and dict1[k] == dict2[k]}
 
     return {
@@ -296,9 +284,7 @@ def encode(env: dict):
     return dict((c(k), c(v)) for k, v in env.items())
 
 
-def get_paths_from_var(
-    var: str = "PYTHONPATH", pathsep: str = os.pathsep, reverse: bool = True
-):
+def get_paths_from_var(var: str = "PYTHONPATH", pathsep: str = os.pathsep, reverse: bool = True):
     """Returns a list of paths from a given pathsep separated environment
     variable.
 
@@ -361,11 +347,7 @@ def evaluate_modifiers(
         resolving = set()
 
     def sanitize_value(value):
-        if (
-            isinstance(value, str)
-            and value.endswith("}")
-            and not value.startswith("${")
-        ):
+        if isinstance(value, str) and value.endswith("}") and not value.startswith("${"):
             # trim a dangling '}' when there's no matching '{'
             if value.count("{") == 0 and value.count("}") == 1:
                 return value.rstrip("}")
@@ -393,9 +375,7 @@ def evaluate_modifiers(
         argument = match.group(3)  # may be None
         parent_value = parent.get(var_name, "")
         override = os.getenv(var_name, parent_value)
-        current = str(
-            environ.get(var_name, parent_value or "")
-        )  # current value we have
+        current = str(environ.get(var_name, parent_value or ""))  # current value we have
         varstr = "${%s}" % var_name
 
         # cycle / self-reference guard
@@ -501,9 +481,7 @@ def evaluate_modifiers(
         elif isinstance(expression, list):
             result = [evaluate_modifiers(v, environ, parent) for v in expression]
         elif isinstance(expression, dict):
-            result = {
-                k: evaluate_modifiers(v, environ, parent) for k, v in expression.items()
-            }
+            result = {k: evaluate_modifiers(v, environ, parent) for k, v in expression.items()}
         else:
             result = expression
 
@@ -539,9 +517,7 @@ def evaluate_command(command: str):
     return command
 
 
-def load_sys_path(
-    var: str = "PYTHONPATH", pathsep: str = os.pathsep, reverse: bool = True
-):
+def load_sys_path(var: str = "PYTHONPATH", pathsep: str = os.pathsep, reverse: bool = True):
     """
     Add paths from the given environment variable to sys.path.
 

envstack-1.0.4/lib/envstack/wrapper.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#  - Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+#  - Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+#  - Neither the name of the software nor the names of its contributors
+#    may be used to endorse or promote products derived from this software
+#    without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+
+__doc__ = """
+Contains executable wrapper classes and functions.
+"""
+
+import os
+import re
+import shlex
+import subprocess
+import traceback
+
+from envstack import config, logger
+from envstack.env import load_environ, resolve_environ
+from envstack.util import encode, evaluate_modifiers
+
+
+def to_args(cmd: str):
+    """
+    Converts a command line string to an arg list to be passed to
+    subprocess.Popen that preserves args with quotes.
+
+    :param cmd: command line string.
+    """
+    return shlex.split(cmd)
+
+
+def shell_join(args):
+    """
+    Joins a list of arguments into a single quoted shell string.
+
+    :param args: list of arguments.
+    :returns: shell string.
+    """
+    argstr = ".".join(args)
+    if '"' in argstr or "'" in argstr:
+        try:
+            return shlex.join(args)
+        except AttributeError:
+            return " ".join(shlex.quote(arg) for arg in args)
+    else:
+        return " ".join(args)
+
+
+class Wrapper(object):
+    """Wrapper class for executables. Subprocessed with preconfigured environment.
+
+    Subclasses should override executable():
+
+        class ToolWrapper(Wrapper):
+            def __init__(self, namespace, args):
+                super(ToolWrapper, self).__init__(namespace, args)
+            def executable(self):
+                return '$TOOL_ROOT/bin/tool'
+
+    To launch 'tool', create an instance of the wrapper, and pass as the first
+    argument the namespace continaining config options, then call launch():
+
+        tool = ToolWrapper('tool', sys.argv[1:])
+        tool.launch()
+
+    The log attribute can be set to a custom logger:
+
+        tool.log = MyLogger()
+    """
+
+    shell: bool = False
+
+    def __init__(self, namespace, args=[]):
+        """Initializes the wrapper with the given namespace and args.
+
+        :param namespace: environment stack namespace.
+        :param args: command line arguments.
+        """
+        super(Wrapper, self).__init__()
+        self.args = args
+        self.name = namespace
+        self.shell = self.shell
+        self.log = logger.log
+        self.env = load_environ(namespace)
+
+    def executable(self):
+        """Returns the path to the executable."""
+        raise NotImplementedError
+
+    def launch(self):
+        """Launches the wrapped tool in a subprocess with env."""
+        env = self.get_subprocess_env()
+        command = self.get_subprocess_command(env)
+
+        try:
+            proc = subprocess.run(
+                command,
+                env=encode(env),
+                shell=self.shell,
+                check=False,
+            )
+            return proc.returncode
+        except Exception:
+            traceback.print_exc()
+            return 1
+
+    def get_subprocess_args(self, cmd):
+        """Returns the arguments to be passed to the subprocess."""
+        return self.args
+
+    def get_subprocess_command(self, env):
+        """Returns argv (preferred) or a command string if shell=True."""
+        cmd = evaluate_modifiers(self.executable(), env)
+        args = self.get_subprocess_args(cmd)
+
+        if self.shell:
+            return " ".join([cmd] + args)
+
+        return [cmd] + args
+
+    def get_subprocess_env(self):
+        """
+        Returns the environment that gets passed to the subprocess when launch()
+        is called on the wrapper.
+        """
+        env = os.environ.copy()
+        env.update(resolve_environ(self.env))
+        return env
+
+
+class CommandWrapper(Wrapper):
+    """Wrapper class for running wrapped commands from the command-line."""
+
+    def __init__(self, namespace=config.DEFAULT_NAMESPACE, args=[]):
+        """
+        Initializes the command wrapper with the given namespace and args, e.g.:
+
+            >>> cmd = CommandWrapper(stack, ['ls', '-al'])
+            >>> print(cmd.executable())
+            ls
+            >>> print(cmd.args)
+            ['-al']
+
+        :param namespace: environment stack name (default: 'default').
+        :param args: command and arguments as a list.
+        """
+        super(CommandWrapper, self).__init__(namespace, args)
+        self.cmd = list(args)
+
+    def executable(self):
+        """Returns the command to run."""
+        return self.cmd[0]
+
+    def get_subprocess_args(self, cmd):
+        return self.cmd[1:]
+
+
+class ShellWrapper(Wrapper):
+    """
+    Runs a *string expression* under the user's shell using -c.
+    Useful for wrapping shell expressions that need variable expansion:
+
+        >>> shell = ShellWrapper('default', 'echo {HOME}')
+    """
+
+    def __init__(self, namespace=config.DEFAULT_NAMESPACE, expr: str = ""):
+        super().__init__(namespace, args=[])
+        self.expr = expr
+
+    def get_interactive(self, env: dict = os.environ):
+        override = env.get("INTERACTIVE")
+        if override is not None:
+            return str(override).lower() in {"1", "true", "yes", "on"}
+        return False  # default safe
+
+    def get_subprocess_command(self, env: dict = os.environ):
+        interactive = self.get_interactive(env)
+        if interactive:
+            return [config.SHELL, "-i", "-c", self.expr]
+        return [config.SHELL, "-c", self.expr]
+
+    def executable(self):
+        """Returns the shell command to run the original command."""
+        return self.cmd
+
+
+class CmdWrapper(CommandWrapper):
+    """Wrapper class for running wrapped commands in Windows cmd.exe."""
+
+    def __init__(self, namespace=config.DEFAULT_NAMESPACE, args=[]):
+        super().__init__(namespace, args)
+
+        # Always run through cmd.exe explicitly
+        self.shell = False
+        self._cmd_exe = config.SHELL  # expected: "cmd" or "cmd.exe"
+
+        # Join the intended argv into one command-line string for /c
+        cmdline = shell_join(self.cmd)
+
+        # cmd.exe /c <command>
+        self._subprocess_argv = [self._cmd_exe, "/c", cmdline]
+
+    def executable(self):
+        return self._cmd_exe
+
+    def get_subprocess_args(self, cmd):
+        # Not used (we override get_subprocess_command)
+        return []
+
+    def get_subprocess_command(self, env):
+        return list(self._subprocess_argv)
+
+
+def capture_output(
+    command: str,
+    namespace: str = config.DEFAULT_NAMESPACE,
+    timeout: int = config.COMMAND_TIMEOUT,
+):
+    """
+    Runs a command (string or argv) with the given stack namespace and captures stdout/stderr.
+
+    Returns: (returncode, stdout, stderr)
+    """
+    import errno
+
+    shellname = os.path.basename(config.SHELL).lower()
+    argv = list(command) if isinstance(command, (list, tuple)) else to_args(command)
+
+    # build env exactly like Wrapper.launch()
+    env = os.environ.copy()
+    env.update(resolve_environ(load_environ(namespace)))
+
+    # prefer argv execution where possible
+    if shellname in ["bash", "sh", "zsh"]:
+        needs_shell = any(re.search(r"\{(\w+)\}", a) for a in argv)
+        if needs_shell:
+            expr_argv = [re.sub(r"\{(\w+)\}", r"${\1}", a) for a in argv]
+            expr = shell_join(expr_argv)
+            cmd = [config.SHELL, "-c", expr]
+        else:
+            cmd = argv
+
+    # for cmd always use original command string
+    elif shellname in ["cmd"]:
+        cmd = command
+
+    else:
+        cmd = argv
+
+    try:
+        proc = subprocess.run(
+            cmd,
+            env=encode(env),
+            shell=False,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        return proc.returncode, proc.stdout, proc.stderr
+    except FileNotFoundError as e:
+        # no process ran; synthesize a bash-like error and code
+        # 127 is the conventional "command not found" code in shells
+        missing = e.filename or (cmd[0] if isinstance(cmd, list) and cmd else str(command))
+        return 127, "", f"{missing}: command not found"
+    except OSError as e:
+        # Other OS-level execution errors (permission, exec format, etc.)
+        rc = 126 if getattr(e, "errno", None) in (errno.EACCES,) else 1
+        return rc, "", str(e)
+    except subprocess.TimeoutExpired:
+        return 124, "", f"Command timed out after {timeout} seconds"
+
+
+def run_command(command: str, namespace: str = config.DEFAULT_NAMESPACE):
+    """
+    Runs a given command with the given stack namespace.
+
+        >>> run_command(['ls', '-l'])
+
+    Or to run in a specific stack namespace:
+
+        >>> run_command(['ls', '-l'], 'my-stack')
+
+     - Automatically detects the shell to use.
+     - Converts {VAR} to $VAR for bash, sh, zsh, and %VAR% for cmd.
+
+    :param command: command to run as a list of arguments.
+    :param namespace: environment stack name (default: 'default').
+    :returns: command exit code
+    """
+    logger.setup_stream_handler()
+    shellname = os.path.basename(config.SHELL).lower()
+    argv = list(command) if isinstance(command, (list, tuple)) else to_args(command)
+
+    if shellname in ["bash", "sh", "zsh"]:
+        needs_shell = any(re.search(r"\{(\w+)\}", a) for a in argv)
+        if needs_shell:
+            expr_argv = [re.sub(r"\{(\w+)\}", r"${\1}", a) for a in argv]
+            expr = shell_join(expr_argv)
+            return ShellWrapper(namespace, expr).launch()
+
+        return CommandWrapper(namespace, argv).launch()
+
+    if shellname in ["cmd"]:
+        expr = [re.sub(r"\{(\w+)\}", r"%\1%", a) for a in argv]
+        return CmdWrapper(namespace, expr).launch()
+
+    return CommandWrapper(namespace, argv).launch()

{envstack-1.0.3 → envstack-1.0.4/lib/envstack.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: envstack
-Version: 1.0.3
+Version: 1.0.4
 Summary: Environment variable composition layer for tools and processes.
 Author-email: Ryan Galloway <ryan@rsgalloway.com>
 License: BSD 3-Clause License
@@ -29,6 +29,16 @@ License-File: LICENSE
 Requires-Dist: PyYAML>=5.1.2
 Requires-Dist: cryptography<47,>=43.0.1; python_version < "3.9"
 Requires-Dist: cryptography>=43.0.1; python_version >= "3.9"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: flake8==7.1.1; extra == "dev"
+Requires-Dist: mccabe==0.7.0; extra == "dev"
+Requires-Dist: isort==5.13.2; extra == "dev"
+Requires-Dist: black==24.8.0; extra == "dev"
+
+<p align="center">
+  <img src="docs/assets/envstack.png" alt="envstack logo" width="560">
+</p>
 
 envstack
 ========

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack.egg-info/SOURCES.txt

@@ -1,6 +1,5 @@
 LICENSE
 README.md
-dist.json
 pyproject.toml
 lib/envstack/__init__.py
 lib/envstack/cli.py
@@ -26,5 +25,6 @@ tests/test_encrypt.py
 tests/test_env.py
 tests/test_node.py
 tests/test_path.py
+tests/test_performance.py
 tests/test_util.py
 tests/test_wrapper.py

{envstack-1.0.3 → envstack-1.0.4}/lib/envstack.egg-info/requires.txt

@@ -5,3 +5,10 @@ cryptography<47,>=43.0.1
 
 [:python_version >= "3.9"]
 cryptography>=43.0.1
+
+[dev]
+pytest
+flake8==7.1.1
+mccabe==0.7.0
+isort==5.13.2
+black==24.8.0

{envstack-1.0.3 → envstack-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "envstack"
-version = "1.0.3"
+version = "1.0.4"
 description = "Environment variable composition layer for tools and processes."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.6"
@@ -56,8 +56,33 @@ Documentation = "https://github.com/rsgalloway/envstack/tree/master/docs"
 envstack = "envstack.cli:main"
 whichenv = "envstack.cli:whichenv"
 
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "flake8==7.1.1",
+  "mccabe==0.7.0",
+  "isort==5.13.2",
+  "black==24.8.0",
+]
+
 [tool.setuptools]
 zip-safe = false
 
 [tool.setuptools.packages.find]
 where = ["lib"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+skip_gitignore = true
+
+[tool.black]
+line-length = 100
+target-version = ["py38"]
+
+[tool.pytest.ini_options]
+markers = [
+  "integration: tests that run real subprocesses (slower / OS-dependent)",
+]
+testpaths = ["tests"]
+norecursedirs = ["tmp"]

{envstack-1.0.3 → envstack-1.0.4}/tests/test_cmds.py

@@ -35,18 +35,18 @@ Contains unit tests for running commands.
 
 import os
 import platform
-import pytest
 import shutil
 import subprocess
 import sys
 import tempfile
 import unittest
 
+import pytest
+from helpers import create_test_root, update_env_file
+
 import envstack
 from envstack.encrypt import AESGCMEncryptor, FernetEncryptor
 
-from test_env import create_test_root, update_env_file
-
 pytestmark = pytest.mark.skipif(
     sys.platform != "linux",
     reason="Linux-only shell integration tests (bash/ls/PS1, paths, env layout)",
@@ -99,9 +99,7 @@ STACK=default
 """
             % self.root
         )
-        output = subprocess.check_output(
-            self.envstack_bin, shell=True, universal_newlines=True
-        )
+        output = subprocess.check_output(self.envstack_bin, shell=True, universal_newlines=True)
         self.assertEqual(output, expected_output)
 
     def test_dev(self):
@@ -231,7 +229,7 @@ STACK=ZGVmYXVsdA==
 
     def test_hello_command_echo(self):
         """Tests that resolved and encrypted values resolve in subprocesses."""
-        expected_output = f"""goodbye\n"""
+        expected_output = "goodbye\n"
         command = "%s thing -r HELLO -e -- echo {HELLO}" % self.envstack_bin
         output = subprocess.check_output(command, shell=True, universal_newlines=True)
         self.assertEqual(output, expected_output)
@@ -310,8 +308,7 @@ ROOT={self.root}
 STACK=project
 """
         command = (
-            "ENV=blah ROOT=/var/tmp %s project -r DEPLOY_ROOT HELLO ROOT STACK"
-            % self.envstack_bin
+            "ENV=blah ROOT=/var/tmp %s project -r DEPLOY_ROOT HELLO ROOT STACK" % self.envstack_bin
         )
         output = subprocess.check_output(command, shell=True, universal_newlines=True)
         self.assertEqual(output, expected_output)
@@ -426,9 +423,7 @@ windows:
 
     def test_thing(self):
         """Tests baking the thing stack with depth of 1."""
-        command = make_command(
-            self.envstack_bin, self.filename, "thing", "--depth", "1"
-        )
+        command = make_command(self.envstack_bin, self.filename, "thing", "--depth", "1")
         expected_output = r"""#!/usr/bin/env envstack
 include: [default]
 all: &all

{envstack-1.0.3 → envstack-1.0.4}/tests/test_encrypt.py

@@ -34,13 +34,8 @@ Contains unit tests for the encrypt.py module.
 """
 
 import unittest
-from unittest.mock import patch
 
-from envstack.encrypt import (
-    AESGCMEncryptor,
-    Base64Encryptor,
-    FernetEncryptor,
-)
+from envstack.encrypt import AESGCMEncryptor, Base64Encryptor, FernetEncryptor
 
 
 class TestBase64Encryptor(unittest.TestCase):

{envstack-1.0.3 → envstack-1.0.4}/tests/test_env.py

@@ -37,46 +37,18 @@ import os
 import shutil
 import sys
 import unittest
-import tempfile
+
+from helpers import create_test_root, update_env_file
 
 import envstack
-from envstack.env import Env, EnvVar, Scope, Source
 from envstack.encrypt import AESGCMEncryptor, FernetEncryptor
+from envstack.env import Env, EnvVar, Scope, Source
 from envstack.util import dict_diff
 
 # path to the env directory
 envpath = os.path.join(os.path.dirname(__file__), "fixtures", "env")
 
 
-def create_test_root():
-    """Creates a temporary directory with the contents of the "env" folder."""
-
-    # create a temporary directory
-    root = tempfile.mkdtemp()
-
-    for env in ("prod", "dev"):
-        shutil.copytree(envpath, os.path.join(root, env, "env"))
-
-    return root
-
-
-def update_env_file(file_path: str, key: str, value: str):
-    """Updates a key in a YAML file with a new value."""
-    import yaml
-
-    # read the YAML file
-    with open(file_path, "r") as f:
-        data = yaml.safe_load(f)
-
-    for _, env_config in data.items():
-        if isinstance(env_config, dict) and key in env_config:
-            env_config[key] = value
-
-    # write the modified data back to the file
-    with open(file_path, "w") as f:
-        yaml.safe_dump(data, f, sort_keys=False)
-
-
 class TestEnvVar(unittest.TestCase):
     def test_init(self):
         v = EnvVar("$FOO:${BAR}")
@@ -382,7 +354,7 @@ class TestResolveEnviron(unittest.TestCase):
         os.environ["CUSTOM"] = "/var/tmp"
         env = {"FOO": "${CUSTOM}/foo"}
         resolved = resolve_environ(env)
-        self.assertEqual(resolved["FOO"], f"/var/tmp/foo")
+        self.assertEqual(resolved["FOO"], "/var/tmp/foo")
 
     def test_simple(self):
         """Tests resolving a simple environment."""
@@ -738,7 +710,7 @@ class TestEncryptEnviron(unittest.TestCase):
 
     def encrypt_environ(self, stack_name):
         """Tests load_environ with encryption (Base64 only)."""
-        from envstack.env import load_environ, encrypt_environ
+        from envstack.env import encrypt_environ, load_environ
         from envstack.node import EncryptedNode
 
         env = load_environ(stack_name)
@@ -817,8 +789,8 @@ class TestEncryptEnviron(unittest.TestCase):
 
     def resolve_encrypted_environ(self, stack_name):
         """Tests resolve_environ with encrypted environ."""
-        from envstack.env import encrypt_environ, load_environ, resolve_environ
         from envstack.encrypt import AESGCMEncryptor, FernetEncryptor
+        from envstack.env import encrypt_environ, load_environ, resolve_environ
 
         env = load_environ(stack_name)  # unresolved values
         resolved = resolve_environ(env)  # resolved values
@@ -839,18 +811,14 @@ class TestEncryptEnviron(unittest.TestCase):
                 continue
             encrypted_value = encrypted[key]  # encrypted value
             resolved_value = resolved[key]  # resolved value
-            encrypted_resolved_value = encrypted_resolved[
-                key
-            ]  # resolved encrypted value
+            encrypted_resolved_value = encrypted_resolved[key]  # resolved encrypted value
             self.assertNotEqual(encrypted_value, None)
             self.assertNotEqual(resolved_value, None)
             self.assertNotEqual(encrypted_resolved_value, None)
             self.assertNotEqual(encrypted_value, value)
             self.assertNotEqual(encrypted_value, resolved_value)
             # self.assertEqual(resolved_value, encrypted_resolved_value)
-            if isinstance(resolved_value, str) and isinstance(
-                encrypted_resolved_value, str
-            ):
+            if isinstance(resolved_value, str) and isinstance(encrypted_resolved_value, str):
                 self.assertTrue(
                     resolved_value.startswith(encrypted_resolved_value),
                     f"{encrypted_resolved_value} not prefix of {resolved_value}",
@@ -1040,7 +1008,7 @@ class TestIssues(unittest.TestCase):
 
         The STACK name and the test env file name should be the same.
         """
-        from envstack.env import load_environ, Env
+        from envstack.env import Env, load_environ
 
         # update default.env to point to test root
         default_env_file = os.path.join(self.root, "prod", "env", "default.env")
@@ -1102,7 +1070,7 @@ class TestIssues(unittest.TestCase):
             BAZ: ${BAZ}
             NUM: ${NUM:=0}
         """
-        from envstack.env import load_environ, resolve_environ, Source
+        from envstack.env import Source, load_environ, resolve_environ
 
         # create grandparent.env that sets a value for FOO
         grandparent = {

{envstack-1.0.3 → envstack-1.0.4}/tests/test_node.py

@@ -121,9 +121,7 @@ class TestEncryptedNode(unittest.TestCase):
         os.environ[AESGCMEncryptor.KEY_VAR_NAME] = key1
         value = "super_secret_password"
         encrypted = AESGCMEncryptor().encrypt(value)
-        node = EncryptedNode.from_yaml(
-            None, yaml.ScalarNode(EncryptedNode.yaml_tag, encrypted)
-        )
+        node = EncryptedNode.from_yaml(None, yaml.ScalarNode(EncryptedNode.yaml_tag, encrypted))
         key2 = AESGCMEncryptor.generate_key()
         os.environ[AESGCMEncryptor.KEY_VAR_NAME] = key2
         resolved = node.resolve()
@@ -142,9 +140,7 @@ class TestEncryptedNode(unittest.TestCase):
         os.environ[AESGCMEncryptor.KEY_VAR_NAME] = key
         value = "super_secret_password"
         encrypted = AESGCMEncryptor().encrypt(value)
-        node = EncryptedNode.from_yaml(
-            None, yaml.ScalarNode(EncryptedNode.yaml_tag, encrypted)
-        )
+        node = EncryptedNode.from_yaml(None, yaml.ScalarNode(EncryptedNode.yaml_tag, encrypted))
         self.assertEqual(node.value, encrypted)
         resolved = node.resolve()
         self.assertEqual(resolved, value)
@@ -275,12 +271,8 @@ class TestSecretsEnv(unittest.TestCase):
     def setUp(self):
         """set up the test environment"""
         self.root = tempfile.mkdtemp()
-        os.environ[AESGCMEncryptor.KEY_VAR_NAME] = (
-            "jHLNsFrhs9JsjuPkNhYX5ubwLpId2ZSxcFXAkHyMjOU="
-        )
-        os.environ[FernetEncryptor.KEY_VAR_NAME] = (
-            "v4-Ry7uKSOBEXMDv9x_crBBpi0eo2WCYNAIlSB1t4VE="
-        )
+        os.environ[AESGCMEncryptor.KEY_VAR_NAME] = "jHLNsFrhs9JsjuPkNhYX5ubwLpId2ZSxcFXAkHyMjOU="
+        os.environ[FernetEncryptor.KEY_VAR_NAME] = "v4-Ry7uKSOBEXMDv9x_crBBpi0eo2WCYNAIlSB1t4VE="
 
     def tearDown(self):
         """tear down the test environment"""

{envstack-1.0.3 → envstack-1.0.4}/tests/test_path.py

@@ -134,9 +134,7 @@ class TestMatchTemplate(unittest.TestCase):
             SEQDIR="${ROOT}/projects/{seq}",
         )
         with patch("envstack.path._load_resolved_stack", return_value=env):
-            t = match_template(
-                "${ROOT}/projects/aa", stack="fps", scope="/tmp", expand=False
-            )
+            t = match_template("${ROOT}/projects/aa", stack="fps", scope="/tmp", expand=False)
             self.assertIsNotNone(t)
             self.assertEqual(str(t), "${ROOT}/projects/{seq}")
 

envstack-1.0.4/tests/test_performance.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2024-2026, Ryan Galloway (ryan@rsgalloway.com)
+#
+
+"""Coarse performance regression tests for envstack."""
+
+import os
+import shutil
+import time
+import unittest
+
+from helpers import create_fixture_env_root
+
+from envstack import util
+from envstack.encrypt import AESGCMEncryptor, FernetEncryptor
+from envstack.env import encrypt_environ, load_environ, resolve_environ
+
+
+class PerformanceTests(unittest.TestCase):
+    """Coarse-grained performance guardrails for envstack hotspots."""
+
+    def setUp(self):
+        self.root = create_fixture_env_root()
+        self.old_env = os.environ.copy()
+        self.old_cache_timeout = util.CACHE_TIMEOUT
+
+        os.environ["ROOT"] = self.root
+        os.environ["ENVPATH"] = os.pathsep.join(
+            [
+                os.path.join(self.root, "prod", "env"),
+                os.path.join(self.root, "dev", "env"),
+            ]
+        )
+        os.environ[AESGCMEncryptor.KEY_VAR_NAME] = "jHLNsFrhs9JsjuPkNhYX5ubwLpId2ZSxcFXAkHyMjOU="
+        os.environ[FernetEncryptor.KEY_VAR_NAME] = "v4-Ry7uKSOBEXMDv9x_crBBpi0eo2WCYNAIlSB1t4VE="
+
+        # Keep memoized paths warm and stable across the repeated calls below.
+        util.CACHE_TIMEOUT = 60
+
+    def tearDown(self):
+        os.environ.clear()
+        os.environ.update(self.old_env)
+        util.CACHE_TIMEOUT = self.old_cache_timeout
+        shutil.rmtree(self.root)
+
+    def test_load_environ_repeated_dev_stack_stays_fast(self):
+        """Repeated stack loading should remain comfortably below startup-budget scale."""
+        start = time.perf_counter()
+        last = None
+        for _ in range(200):
+            last = load_environ("dev", scope=self.root)
+        elapsed = time.perf_counter() - start
+
+        self.assertIsNotNone(last)
+        self.assertEqual(last["ENV"], "dev")
+        self.assertEqual(last["STACK"], "dev")
+        self.assertLess(elapsed, 1.0)
+
+    def test_resolve_environ_large_modifier_graph_stays_fast(self):
+        """Large chained substitutions should not regress catastrophically."""
+        env = {"ROOT": self.root, "PATH": "/usr/bin", "ENVPATH": os.environ["ENVPATH"]}
+        for i in range(500):
+            env[f"VAR_{i}"] = "${ROOT}/show/pkg/%d:${PATH}" % i
+
+        start = time.perf_counter()
+        resolved = resolve_environ(env)
+        elapsed = time.perf_counter() - start
+
+        self.assertTrue(resolved["VAR_499"].startswith(self.root))
+        self.assertIn("/pkg/499", resolved["VAR_499"])
+        self.assertLess(elapsed, 1.0)
+
+    def test_encrypted_stack_load_and_resolve_stays_fast(self):
+        """Encrypted stack resolution should stay well within a coarse CI budget."""
+        start = time.perf_counter()
+        last = None
+        for _ in range(100):
+            last = resolve_environ(load_environ("secrets", scope=self.root, encrypt=True))
+        elapsed = time.perf_counter() - start
+
+        self.assertIsNotNone(last)
+        self.assertEqual(last["KEY"], "This is encrypted")
+        self.assertEqual(last["SECRET"], "my_super_secret_password")
+        self.assertLess(elapsed, 1.5)
+
+    def test_encrypt_environ_medium_payload_stays_fast(self):
+        """Bulk encryption of a moderate environment should remain snappy."""
+        env = load_environ("dev", scope=self.root)
+        for i in range(200):
+            env[f"EXTRA_{i}"] = "${DEPLOY_ROOT}/lib/%d:${PATH}" % i
+
+        start = time.perf_counter()
+        encrypted = encrypt_environ(env)
+        elapsed = time.perf_counter() - start
+
+        self.assertEqual(encrypted["ENV"].resolve(env=os.environ), "dev")
+        self.assertLess(elapsed, 1.0)
+
+
+if __name__ == "__main__":
+    unittest.main()

{envstack-1.0.3 → envstack-1.0.4}/tests/test_util.py

@@ -39,14 +39,14 @@ from unittest.mock import patch
 
 from envstack import config, util
 from envstack.util import (
-    null,
-    encode,
-    evaluate_command,
-    evaluate_modifiers,
     dedupe_list,
     dedupe_paths,
     detect_path,
+    encode,
+    evaluate_command,
+    evaluate_modifiers,
     get_stack_name,
+    null,
     partition_platform_data,
     safe_eval,
     split_paths,
@@ -443,6 +443,7 @@ darwin:
   '<<': '*all'
         """
         import tempfile
+
         from envstack.util import unquote_strings
 
         with tempfile.NamedTemporaryFile(mode="w", delete=False) as temp_file:
@@ -586,9 +587,7 @@ class TestDedupePaths(unittest.TestCase):
             "/some/other/path",
         ]
         result = dedupe_paths(":".join(paths))
-        expected_result = os.pathsep.join(
-            ["/usr/bin", "/usr/local/bin", "/some/other/path"]
-        )
+        expected_result = os.pathsep.join(["/usr/bin", "/usr/local/bin", "/some/other/path"])
         self.assertEqual(result, expected_result)
 
         paths = ["/usr/bin"]
@@ -624,9 +623,7 @@ class TestDedupePaths(unittest.TestCase):
         ]
         path = ":".join(paths)
         result = dedupe_paths(path, platform="windows")
-        self.assertEqual(
-            result, "C:\\Program Files\\Python;D:/path2;E:/path3;/usr/local/bin"
-        )
+        self.assertEqual(result, "C:\\Program Files\\Python;D:/path2;E:/path3;/usr/local/bin")
 
         # mixed paths
         path = "//tools/pipe/prod/env;//tools/pipe/prod/env;/home/user/envstack/env"
@@ -634,13 +631,9 @@ class TestDedupePaths(unittest.TestCase):
         self.assertEqual(result, "//tools/pipe/prod/env;/home/user/envstack/env")
 
         # mixed paths with duplicate
-        path = (
-            "C:\\Program Files\\Python;D:/path2;E:/path3;/usr/local/bin:/usr/local/bin"
-        )
+        path = "C:\\Program Files\\Python;D:/path2;E:/path3;/usr/local/bin:/usr/local/bin"
         result = dedupe_paths(path, platform="windows")
-        self.assertEqual(
-            result, "C:\\Program Files\\Python;D:/path2;E:/path3;/usr/local/bin"
-        )
+        self.assertEqual(result, "C:\\Program Files\\Python;D:/path2;E:/path3;/usr/local/bin")
 
 
 class TestSafeEval(unittest.TestCase):

{envstack-1.0.3 → envstack-1.0.4}/tests/test_wrapper.py

@@ -35,12 +35,12 @@ Contains unit tests for the wrapper.py module.
 
 import os
 import sys
-import pytest
 from types import SimpleNamespace
 
-import envstack.wrapper as wrapper_mod
-from envstack.wrapper import Wrapper, CommandWrapper, run_command, capture_output
+import pytest
 
+import envstack.wrapper as wrapper_mod
+from envstack.wrapper import CommandWrapper, Wrapper, capture_output, run_command
 
 IS_WINDOWS = sys.platform.startswith("win")
 
@@ -78,9 +78,7 @@ def test_wrapper_shell_true_allows_command_string(stub_env, capfd):
     rc = w.launch()
     out, err = capfd.readouterr()
     assert rc == 0
-    assert out.strip() == (
-        "C:\\tmp\\envstack-root" if IS_WINDOWS else "/tmp/envstack-root"
-    )
+    assert out.strip() == ("C:\\tmp\\envstack-root" if IS_WINDOWS else "/tmp/envstack-root")
 
 
 def test_commandwrapper_runs_argv_without_shell(stub_env, capfd):

envstack-1.0.3/dist.json

@@ -1,21 +0,0 @@
-{
-    "author": "ryan@rsg.io",
-    "targets": {
-        "env": {
-            "source": "env/*",
-            "destination": "{DEPLOY_ROOT}/env/%1"
-        },
-        "bin": {
-            "source": "bin/*",
-            "destination": "{DEPLOY_ROOT}/bin/%1"
-        },
-        "bash_completion": {
-            "source": "bin/envstack_completion.sh",
-            "destination": "/etc/bash_completion.d/envstack"
-        },
-        "lib": {
-            "source": "lib/envstack",
-            "destination": "{DEPLOY_ROOT}/lib/python/envstack"
-        }
-    }
-}