envstack 0.9.0__tar.gz → 0.9.2__tar.gz

{envstack-0.9.0/lib/envstack.egg-info → envstack-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: envstack
-Version: 0.9.0
+Version: 0.9.2
 Summary: Stacked environment variable management system
 Home-page: http://github.com/rsgalloway/envstack
 Author: Ryan Galloway
@@ -36,23 +36,6 @@ Environment variable management system.
 [Python API](#python-api) |
 [Running Commands](#running-commands)
 
-
-| Feature | Description |
-|---------|-------------|
-| Namespaced environments | Environments in envstack are namespaced, allowing you to organize and manage variables based on different contexts or projects. Each environment stack can have its own set of variables, providing a clean separation and avoiding conflicts between different environments. |
-| Environment stacks | Allows you to manage environment variables using .env files called environment stacks. These stacks provide a hierarchical and contextual approach to managing variables. |
-| Encryption support | Secure encryption, including AES-GCM, Fernet, and Base64. This allows you to securely encrypt and decrypt sensitive environment variables. |
-| Hierarchical structure | Stacks can be combined and have a defined order of priority. Variables defined in higher scope stacks flow from higher scope to lower scope, left to right. |
-| Variable expansion modifiers | Supports bash-like variable expansion modifiers, allowing you to set default values for variables and override them in the environment or by higher scope stacks. |
-| Platform-specific variables | Stacks can have platform-specific variables and values. This allows you to define different values for variables based on the platform. |
-| Variable references | Variables can reference other variables, allowing for more flexibility and dynamic value assignment. |
-| Multi-line values | Supports variables with multi-line values. |
-| Includes | Stack files can include other stacks, making it easy to reuse and combine different stacks. |
-| Python API | Provides a Python API that allows you to initialize and work with environment stacks programmatically. Easily initialize pre-defined environments with Python scripts, tools, and wrappers. |
-| Running commands | Allows you to run command line executables inside an environment stack, providing a convenient way to execute commands with a pre-defined environment. |
-| Wrappers | Supports wrappers, which are command line executable scripts that automatically run a given command in the environment stack. This allows for easy customization and management of environments. |
-| Shell integration | Provides instructions for sourcing the environment stack in your current shell, allowing you to set and clear the environment easily. |
-
 ## Installation
 
 The easiest way to install:
@@ -94,7 +77,6 @@ $ curl -o default.env https://raw.githubusercontent.com/rsgalloway/envstack/mast
 Alternatively, set `${ENVPATH}` to the directory containing your environment
 stack files:
 
-#### bash
 ```bash
 $ export ENVPATH=/path/to/env/files
 ```
@@ -102,7 +84,6 @@ $ export ENVPATH=/path/to/env/files
 Define as many paths as you want, and envstack will search for stack files in
 order from left to right, for example:
 
-#### bash
 ```bash
 $ export ENVPATH=/mnt/pipe/dev/env:/mnt/pipe/prod/env
 ```
@@ -233,50 +214,34 @@ $ envstack -s HELLO=world -o hello.env
 You can convert existing `.env` files to envstack by piping them into envstack:
 
 ```bash
-$ cat .env | envstack --set -o dev.env
+$ cat .env | envstack --set -o out.env
 ```
 
-## Creating Stacks
+## Creating Environments
 
 Several example or starter stacks are available in the [env folder of the
 envstack repo](https://github.com/rsgalloway/envstack/tree/master/env).
 
-To create a new environment stack, create an envstack file and declare some
-variables.
+To create a new environment file, use `--set` to declare some variables:
 
 ```bash
-$ envstack foobar -o foobar.env
-```
-
-Add the `${FOO}` and `${BAR}` env vars to the foobar.env environment stack file:
-
-```yaml
-#!/usr/bin/env envstack
-all: &all
-  FOO: bar
-  BAR: ${FOO}
-darwin:
-  <<: *all
-linux:
-  <<: *all
-windows:
-  <<: *all
+$ envstack -s FOO=bar BAR=\${FOO} -o out.env
 ```
 
-Or using Python:
+Using Python:
 
 ```python
 >>> env = Env({"FOO": "bar", "BAR": "${FOO}"})
->>> env.write("foobar.env")
+>>> env.write("out.env")
 ```
 
-Get the resolved environment for the `foobar` stack:
+Get the resolved values back:
 
 ```bash
-$ ./foobar.env -r
+$ ./out.env -r
 BAR=bar
 FOO=bar
-STACK=foobar
+STACK=out
 ```
 
 #### More Details
@@ -354,7 +319,7 @@ nodes look for keys in the following order, favoring AES-GCM over Fernet:
 | Fernet | ${ENVSTACK_FERNET_KEY} |
 
 If no encryption keys are found in the environment, envstack will default to
-using Base64 encryption:
+using Base64 encoding:
 
 ```bash
 $ envstack --encrypt
@@ -381,7 +346,7 @@ $ source <(envstack --keygen --export)
 Once the keys are in the environment, you can encrypt the env stack:
 
 ```bash
-$ envstack --encrypt -o encrypted.env
+$ envstack -o encrypted.env --encrypt
 ```
 
 Encrypted variables will resolve as long as the key is in the environment:
@@ -393,17 +358,17 @@ HELLO=world
 
 #### Storing Keys
 
-Keys can be stored in other environment stacks, e.g. a `keys.env` file. To
-generate keys and store them in a `keys.env` env stack file:
+Keys can be stored in other environment stacks, e.g. a `keys.env` file
+(keys are automatically base64 encoded):
 
 ```bash
 $ envstack --keygen -o keys.env
 ```
 
-Then use the `keys.env` env stack to encrypt any other env stack:
+Then use `keys.env` to encrypt any other environment files:
 
 ```bash
-$ envstack keys -- envstack --encrypt -o encrypted.env
+$ ./keys.env -- envstack -eo encrypted.env
 ```
 
 To decrypt, add `keys` to the env stack:
@@ -413,7 +378,14 @@ $ envstack keys encrypted -r HELLO
 HELLO=world
 ```
 
-Or add the `keys` env stack to `include` to automatically decrypt:
+Or run the command inside the `keys` environment like this:
+
+```bash
+$ ./keys.env -- envsatck encrypted -r HELLO
+HELLO=world
+```
+
+Or include `keys` in environments to automatically decrypt:
 
 ```yaml
 include: [keys]

{envstack-0.9.0 → envstack-0.9.2}/README.md

@@ -12,23 +12,6 @@ Environment variable management system.
 [Python API](#python-api) |
 [Running Commands](#running-commands)
 
-
-| Feature | Description |
-|---------|-------------|
-| Namespaced environments | Environments in envstack are namespaced, allowing you to organize and manage variables based on different contexts or projects. Each environment stack can have its own set of variables, providing a clean separation and avoiding conflicts between different environments. |
-| Environment stacks | Allows you to manage environment variables using .env files called environment stacks. These stacks provide a hierarchical and contextual approach to managing variables. |
-| Encryption support | Secure encryption, including AES-GCM, Fernet, and Base64. This allows you to securely encrypt and decrypt sensitive environment variables. |
-| Hierarchical structure | Stacks can be combined and have a defined order of priority. Variables defined in higher scope stacks flow from higher scope to lower scope, left to right. |
-| Variable expansion modifiers | Supports bash-like variable expansion modifiers, allowing you to set default values for variables and override them in the environment or by higher scope stacks. |
-| Platform-specific variables | Stacks can have platform-specific variables and values. This allows you to define different values for variables based on the platform. |
-| Variable references | Variables can reference other variables, allowing for more flexibility and dynamic value assignment. |
-| Multi-line values | Supports variables with multi-line values. |
-| Includes | Stack files can include other stacks, making it easy to reuse and combine different stacks. |
-| Python API | Provides a Python API that allows you to initialize and work with environment stacks programmatically. Easily initialize pre-defined environments with Python scripts, tools, and wrappers. |
-| Running commands | Allows you to run command line executables inside an environment stack, providing a convenient way to execute commands with a pre-defined environment. |
-| Wrappers | Supports wrappers, which are command line executable scripts that automatically run a given command in the environment stack. This allows for easy customization and management of environments. |
-| Shell integration | Provides instructions for sourcing the environment stack in your current shell, allowing you to set and clear the environment easily. |
-
 ## Installation
 
 The easiest way to install:
@@ -70,7 +53,6 @@ $ curl -o default.env https://raw.githubusercontent.com/rsgalloway/envstack/mast
 Alternatively, set `${ENVPATH}` to the directory containing your environment
 stack files:
 
-#### bash
 ```bash
 $ export ENVPATH=/path/to/env/files
 ```
@@ -78,7 +60,6 @@ $ export ENVPATH=/path/to/env/files
 Define as many paths as you want, and envstack will search for stack files in
 order from left to right, for example:
 
-#### bash
 ```bash
 $ export ENVPATH=/mnt/pipe/dev/env:/mnt/pipe/prod/env
 ```
@@ -209,50 +190,34 @@ $ envstack -s HELLO=world -o hello.env
 You can convert existing `.env` files to envstack by piping them into envstack:
 
 ```bash
-$ cat .env | envstack --set -o dev.env
+$ cat .env | envstack --set -o out.env
 ```
 
-## Creating Stacks
+## Creating Environments
 
 Several example or starter stacks are available in the [env folder of the
 envstack repo](https://github.com/rsgalloway/envstack/tree/master/env).
 
-To create a new environment stack, create an envstack file and declare some
-variables.
+To create a new environment file, use `--set` to declare some variables:
 
 ```bash
-$ envstack foobar -o foobar.env
-```
-
-Add the `${FOO}` and `${BAR}` env vars to the foobar.env environment stack file:
-
-```yaml
-#!/usr/bin/env envstack
-all: &all
-  FOO: bar
-  BAR: ${FOO}
-darwin:
-  <<: *all
-linux:
-  <<: *all
-windows:
-  <<: *all
+$ envstack -s FOO=bar BAR=\${FOO} -o out.env
 ```
 
-Or using Python:
+Using Python:
 
 ```python
 >>> env = Env({"FOO": "bar", "BAR": "${FOO}"})
->>> env.write("foobar.env")
+>>> env.write("out.env")
 ```
 
-Get the resolved environment for the `foobar` stack:
+Get the resolved values back:
 
 ```bash
-$ ./foobar.env -r
+$ ./out.env -r
 BAR=bar
 FOO=bar
-STACK=foobar
+STACK=out
 ```
 
 #### More Details
@@ -330,7 +295,7 @@ nodes look for keys in the following order, favoring AES-GCM over Fernet:
 | Fernet | ${ENVSTACK_FERNET_KEY} |
 
 If no encryption keys are found in the environment, envstack will default to
-using Base64 encryption:
+using Base64 encoding:
 
 ```bash
 $ envstack --encrypt
@@ -357,7 +322,7 @@ $ source <(envstack --keygen --export)
 Once the keys are in the environment, you can encrypt the env stack:
 
 ```bash
-$ envstack --encrypt -o encrypted.env
+$ envstack -o encrypted.env --encrypt
 ```
 
 Encrypted variables will resolve as long as the key is in the environment:
@@ -369,17 +334,17 @@ HELLO=world
 
 #### Storing Keys
 
-Keys can be stored in other environment stacks, e.g. a `keys.env` file. To
-generate keys and store them in a `keys.env` env stack file:
+Keys can be stored in other environment stacks, e.g. a `keys.env` file
+(keys are automatically base64 encoded):
 
 ```bash
 $ envstack --keygen -o keys.env
 ```
 
-Then use the `keys.env` env stack to encrypt any other env stack:
+Then use `keys.env` to encrypt any other environment files:
 
 ```bash
-$ envstack keys -- envstack --encrypt -o encrypted.env
+$ ./keys.env -- envstack -eo encrypted.env
 ```
 
 To decrypt, add `keys` to the env stack:
@@ -389,7 +354,14 @@ $ envstack keys encrypted -r HELLO
 HELLO=world
 ```
 
-Or add the `keys` env stack to `include` to automatically decrypt:
+Or run the command inside the `keys` environment like this:
+
+```bash
+$ ./keys.env -- envsatck encrypted -r HELLO
+HELLO=world
+```
+
+Or include `keys` in environments to automatically decrypt:
 
 ```yaml
 include: [keys]

{envstack-0.9.0 → envstack-0.9.2}/dist.json

@@ -9,11 +9,11 @@
             "source": "bin/*",
             "destination": "{DEPLOY_ROOT}/bin/%1"
         },
-        "envstack_completion": {
+        "bash_completion": {
             "source": "bin/envstack_completion.sh",
             "destination": "/etc/bash_completion.d/envstack"
         },
-        "lib-envstack": {
+        "lib": {
             "source": "lib/envstack",
             "destination": "{DEPLOY_ROOT}/lib/python/envstack"
         }

{envstack-0.9.0 → envstack-0.9.2}/lib/envstack/__init__.py

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

{envstack-0.9.0 → envstack-0.9.2}/lib/envstack/cli.py

@@ -147,12 +147,19 @@ def parse_args():
         action="version",
         version=f"envstack {__version__}",
     )
-    parser.add_argument(
+    group = parser.add_mutually_exclusive_group(required=False)
+    group.add_argument(
         "namespace",
         metavar="STACK",
         nargs="*",
         default=[config.DEFAULT_NAMESPACE],
-        help="the environment stacks to use (default '%s')" % config.DEFAULT_NAMESPACE,
+        help="the environment stacks to use",
+    )
+    group.add_argument(
+        "-b",
+        "--bare",
+        action="store_true",
+        help="create a bare environment",
     )
     encrypt_group = parser.add_argument_group("encryption options")
     encrypt_group.add_argument(
@@ -175,10 +182,11 @@ def parse_args():
         help="save the environment to an env file",
     )
     bake_group.add_argument(
+        "-d",
         "--depth",
         type=int,
         default=0,
-        help="depth of environment stack to bake",
+        help="depth of environment stack to bake (default: 0 = flatten)",
     )
     parser.add_argument_group(bake_group)
     export_group = parser.add_argument_group("export options")
@@ -205,8 +213,8 @@ def parse_args():
         "--set",
         nargs="*",
         action=StoreOnce,
-        metavar="VAR=VALUE",
-        help="convert KEY=VALUE pairs to envstack environment variables",
+        metavar="KEY=VALUE",
+        help="overlay KEY=VALUE pairs to envstack environments",
     )
     parser.add_argument(
         "--scope",
@@ -234,6 +242,12 @@ def parse_args():
         action="store_true",
         help="list the env stack file sources",
     )
+    export_group.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="print the value of an environment variable only (no key)",
+    )
 
     args = parser.parse_args(args_before_dash)
 
@@ -275,9 +289,24 @@ def main():
                 for key, value in data.items():
                     print(f"{key}={value}")
 
-        elif args.set is not None:
+        elif args.clear:
+            from envstack.env import clear
+
+            print(clear(args.namespace, shell=config.SHELL))
+
+        elif args.export and args.resolve is None and args.set is None:
+            print(export(args.namespace, shell=config.SHELL, encrypt=args.encrypt))
+
+        elif args.set is not None and args.resolve is None:
             force_stdin = args.set == [] or args.set == ["-"]
             using_pipe = args.set == [] and not sys.stdin.isatty()
+
+            # load the environment if not in bare mode
+            if args.bare:
+                env = Env()
+            else:
+                env = load_environ(args.namespace, platform=args.platform)
+
             # interactive mode
             if force_stdin and sys.stdin.isatty():
                 print(
@@ -302,53 +331,101 @@ def main():
             else:
                 data = _parse_keyvals(args.set)
 
+            # encrypt the new data only
             if args.encrypt:
-                data = encrypt_environ(data, encrypt=(not args.out))
+                data = encrypt_environ(data)
+
+            # update the environment with the new data
+            env.update(data)
+
             if args.export:
-                print(export_env_to_shell(data))
+                print(export_env_to_shell(env))
             elif args.out:
-                Env(data).write(args.out)
+                env.write(args.out, depth=args.depth)
             else:
-                for key, value in data.items():
-                    print(f"{key}={value}")
-
-        elif args.out:
+                for key, val in env.items():
+                    if args.quiet:
+                        if len(env) > 1:
+                            print("error: --quiet requires exactly one KEY")
+                            return 2
+                        else:
+                            print(val)
+                    else:
+                        print(f"{key}={val}")
+
+        elif args.out and args.resolve is None:
             bake_environ(
                 args.namespace,
                 filename=args.out,
-                depth=args.depth or 0,
+                depth=args.depth,
                 encrypt=args.encrypt,
             )
 
         elif args.resolve is not None:
+            if args.depth:
+                print("error: --depth is not valid with --resolve")
+                return 2
             resolved = resolve_environ(
                 load_environ(args.namespace, platform=args.platform)
             )
-            keys = args.resolve or resolved.keys()
-            for key in sorted(str(k) for k in keys):
-                val = resolved.get(key)
-                print(f"{key}={val}")
+            if args.set:
+                resolved.update(_parse_keyvals(args.set))
+            if args.encrypt:
+                resolved = encrypt_environ(resolved)
+            if args.out:
+                if len(args.resolve) == 0:
+                    resolved.write(args.out, depth=0)
+                else:
+                    keys = args.resolve or resolved.keys()
+                    if args.set:
+                        keys = set(keys).union(_parse_keyvals(args.set).keys())
+                    env = Env({key: resolved[key] for key in keys})
+                    env.write(args.out, depth=0)
+            elif args.export:
+                if len(args.resolve) == 0:
+                    print(export_env_to_shell(resolved, shell=config.SHELL))
+                else:
+                    keys = args.resolve or resolved.keys()
+                    if args.set:
+                        keys = set(keys).union(_parse_keyvals(args.set).keys())
+                    env = Env({key: resolved[key] for key in keys})
+                    print(export_env_to_shell(env, shell=config.SHELL))
+            else:
+                keys = args.resolve or resolved.keys()
+                if args.set:
+                    keys = set(keys).union(_parse_keyvals(args.set).keys())
+                for key in sorted(str(k) for k in keys):
+                    val = resolved.get(key)
+                    if key in resolved:
+                        if args.quiet:
+                            if len(keys) > 1:
+                                print("error: --quiet requires exactly one KEY")
+                                return 2
+                            else:
+                                print(val)
+                        else:
+                            print(f"{key}={val}")
 
         elif args.trace is not None:
             if len(args.trace) == 0:
                 args.trace = load_environ(args.namespace).keys()
             for trace in args.trace:
                 path = trace_var(*args.namespace, var=trace)
-                print("{0}: {1}".format(trace, path))
+                if path:
+                    if args.quiet:
+                        if len(args.trace) > 1:
+                            print("error: --quiet requires exactly one KEY")
+                            return 2
+                        else:
+                            print(path)
+                    else:
+                        print("{0}={1}".format(trace, path))
 
         elif args.sources:
             env = load_environ(args.namespace, platform=args.platform)
             for source in env.sources:
                 print(source.path)
 
-        elif args.clear:
-            from envstack.env import clear
-
-            print(clear(args.namespace, config.SHELL))
-
-        elif args.export:
-            print(export(args.namespace, config.SHELL))
-
         else:
             env = load_environ(
                 args.namespace, platform=args.platform, encrypt=args.encrypt

{envstack-0.9.0 → envstack-0.9.2}/lib/envstack/encrypt.py

@@ -313,10 +313,12 @@ def generate_keys():
 
     :returns: Dictionary containing Fernet and AES-GCM keys.
     """
+    from envstack.node import Base64Node
+
     symmetric_key = AESGCMEncryptor.generate_key()
     fernet_key = FernetEncryptor.generate_key()
 
     return {
-        AESGCMEncryptor.KEY_VAR_NAME: symmetric_key,
-        FernetEncryptor.KEY_VAR_NAME: fernet_key,
+        AESGCMEncryptor.KEY_VAR_NAME: Base64Node(symmetric_key),
+        FernetEncryptor.KEY_VAR_NAME: Base64Node(fernet_key),
     }

{envstack-0.9.0 → envstack-0.9.2}/lib/envstack/env.py

@@ -114,7 +114,7 @@ class Source(object):
         """Returns the char length of the path"""
         return len(self.path)
 
-    def load(self, platform=config.PLATFORM):
+    def load(self, platform: str = config.PLATFORM):
         """Reads .env from .path, and returns an Env class object"""
         if self.path and not self.data:
             self.data = load_file(self.path)
@@ -305,17 +305,12 @@ class Env(dict):
             >>> env.bake("baked.env")
 
         :param filename: path to save the baked environment.
-        :param depth: depth of source files to incldue (default: all).
-        :param encrypt: encrypt the values.
+        :param depth: depth of source files to include (optional).
+        :param encrypt: encrypt the values (optional).
         :returns: baked environment.
         """
-        # get the sources for the given environment
         sources = self.sources
-
-        # look for encryption keys in the environment
-        os.environ.update(get_keys_from_env(self))
-
-        # create a baked source
+        os.environ.update(get_keys_from_env(self))  # for encryption
         baked = Source(filename)
 
         def get_node_class(value):
@@ -327,32 +322,63 @@ class Env(dict):
                     return EncryptedNode
             return value.__class__
 
-        # merge the sources into the outfile
+        # track included files and seen keys
+        includes = []
+        seen_keys = set()
+
+        for source in sources[:depth]:
+            for key, value in source.data.items():
+                if isinstance(value, dict):
+                    for k, v in value.items():
+                        if k in self:
+                            v = self[k]
+                        node_class = get_node_class(v)
+                        seen_keys.add(k)
+                else:
+                    seen_keys.add(key)
+
+        current_depth = 0
         for source in sources[-depth:]:
             for key, value in source.data.items():
+                if key == "include" and current_depth <= depth:
+                    includes = value
+                    continue
                 if isinstance(value, dict):
                     for k, v in value.items():
+                        if k in self and key == "all":  # override only in "all"
+                            v = self[k]
                         node_class = get_node_class(v)
                         baked.data.setdefault(key, {})[k] = node_class(v)
+                        seen_keys.add(k)
                 else:
-                    node_class = get_node_class(value)
-                    baked.data[key] = node_class(value)
+                    baked.data[key] = get_node_class(value)(value)
+                    seen_keys.add(key)
+                current_depth += 1
+
+        # add/override with values from the current environment
+        for key, value in self.items():
+            if key == "STACK" or key in seen_keys:
+                continue
+            baked.data["all"][key] = get_node_class(value)(value)
 
         # clear includes if environment stack is fully baked
-        if depth <= 0:
+        if depth <= 0 or depth >= len(sources):
             baked.data["include"] = []
-
-        # write the baked environment to the file
-        if filename:
-            baked.write()
+        else:
+            baked.data["include"] = includes
 
         # create the baked environment from the baked source
         baked_env = Env()
         baked_env.load_source(baked)
+        if filename:
+            try:
+                baked.write()
+            except Exception as err:
+                raise WriteError(f"Failed to write {filename}", err)
 
         return baked_env
 
-    def write(self, filename: str = None):
+    def write(self, filename: str, depth: int = 0, encrypt: bool = False):
         """Writes the environment to an env file.
 
             >>> env = Env({"FOO": "${BAR}", "BAR": "bar"})
@@ -364,11 +390,13 @@ class Env(dict):
             >>> env.write("encrypted.env")
 
         :param filename: path to save the baked environment.
+        :param depth: depth of source files to include (optional).
+        :param encrypt: encrypt the values (optional).
         :returns: Source object.
         """
         # the environment was loaded from one or more sources
         if self.sources:
-            baked = self.bake(filename)
+            baked = self.bake(filename, depth=depth, encrypt=encrypt)
             return baked.sources[0]
 
         # the environment was created from scratch
@@ -631,6 +659,7 @@ def export(
     name: str = config.DEFAULT_NAMESPACE,
     shell: str = config.SHELL,
     scope: str = None,
+    encrypt: bool = False,
 ):
     """Returns shell commands that can be sourced to set environment stack
     environment variables.
@@ -638,12 +667,13 @@ def export(
     Supported shells: bash, sh, tcsh, cmd, pwsh (see config.detect_shell()).
 
     :param name: stack namespace.
-    :param shell: name of shell (default: current shell).
-    :param scope: environment scope (default: cwd).
+    :param shell: name of shell (optional).
+    :param scope: environment scope (optional).
+    :param encrypt: encrypt the values (optional).
     :returns: shell commands as string.
     """
-    resolved_env = resolve_environ(load_environ(name, scope=scope))
-    return export_env_to_shell(resolved_env, shell)
+    env = load_environ(name, scope=scope, encrypt=encrypt)
+    return export_env_to_shell(env, shell)
 
 
 def save():
@@ -744,8 +774,8 @@ def bake_environ(
         $ envstack [STACK] -o <filename>
 
     :param name: stack namespace.
-    :param scope: environment scope (default: cwd).
-    :param depth: depth of source files to incldue (default: all).
+    :param scope: environment scope (optional).
+    :param depth: depth of source files to include (optional).
     :param filename: path to save the baked environment.
     :param encrypt: encrypt the values.
     :returns: baked environment.
@@ -791,6 +821,7 @@ def encrypt_environ(
             node = node_class(v)
             if encrypt:
                 node.value = node.encryptor(env=resolved_env).encrypt(str(v))
+                node.original_value = node.value
             encrypted_env[k] = node
         else:
             encrypted_env[k] = v

{envstack-0.9.0 → envstack-0.9.2}/lib/envstack/exceptions.py

@@ -74,3 +74,9 @@ class TemplateNotFound(Exception):
     """Custom exception class for missing Templates."""
 
     pass
+
+
+class WriteError(Exception):
+    """Custom exception class for errors during export operations."""
+
+    pass

{envstack-0.9.0 → envstack-0.9.2/lib/envstack.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: envstack
-Version: 0.9.0
+Version: 0.9.2
 Summary: Stacked environment variable management system
 Home-page: http://github.com/rsgalloway/envstack
 Author: Ryan Galloway
@@ -36,23 +36,6 @@ Environment variable management system.
 [Python API](#python-api) |
 [Running Commands](#running-commands)
 
-
-| Feature | Description |
-|---------|-------------|
-| Namespaced environments | Environments in envstack are namespaced, allowing you to organize and manage variables based on different contexts or projects. Each environment stack can have its own set of variables, providing a clean separation and avoiding conflicts between different environments. |
-| Environment stacks | Allows you to manage environment variables using .env files called environment stacks. These stacks provide a hierarchical and contextual approach to managing variables. |
-| Encryption support | Secure encryption, including AES-GCM, Fernet, and Base64. This allows you to securely encrypt and decrypt sensitive environment variables. |
-| Hierarchical structure | Stacks can be combined and have a defined order of priority. Variables defined in higher scope stacks flow from higher scope to lower scope, left to right. |
-| Variable expansion modifiers | Supports bash-like variable expansion modifiers, allowing you to set default values for variables and override them in the environment or by higher scope stacks. |
-| Platform-specific variables | Stacks can have platform-specific variables and values. This allows you to define different values for variables based on the platform. |
-| Variable references | Variables can reference other variables, allowing for more flexibility and dynamic value assignment. |
-| Multi-line values | Supports variables with multi-line values. |
-| Includes | Stack files can include other stacks, making it easy to reuse and combine different stacks. |
-| Python API | Provides a Python API that allows you to initialize and work with environment stacks programmatically. Easily initialize pre-defined environments with Python scripts, tools, and wrappers. |
-| Running commands | Allows you to run command line executables inside an environment stack, providing a convenient way to execute commands with a pre-defined environment. |
-| Wrappers | Supports wrappers, which are command line executable scripts that automatically run a given command in the environment stack. This allows for easy customization and management of environments. |
-| Shell integration | Provides instructions for sourcing the environment stack in your current shell, allowing you to set and clear the environment easily. |
-
 ## Installation
 
 The easiest way to install:
@@ -94,7 +77,6 @@ $ curl -o default.env https://raw.githubusercontent.com/rsgalloway/envstack/mast
 Alternatively, set `${ENVPATH}` to the directory containing your environment
 stack files:
 
-#### bash
 ```bash
 $ export ENVPATH=/path/to/env/files
 ```
@@ -102,7 +84,6 @@ $ export ENVPATH=/path/to/env/files
 Define as many paths as you want, and envstack will search for stack files in
 order from left to right, for example:
 
-#### bash
 ```bash
 $ export ENVPATH=/mnt/pipe/dev/env:/mnt/pipe/prod/env
 ```
@@ -233,50 +214,34 @@ $ envstack -s HELLO=world -o hello.env
 You can convert existing `.env` files to envstack by piping them into envstack:
 
 ```bash
-$ cat .env | envstack --set -o dev.env
+$ cat .env | envstack --set -o out.env
 ```
 
-## Creating Stacks
+## Creating Environments
 
 Several example or starter stacks are available in the [env folder of the
 envstack repo](https://github.com/rsgalloway/envstack/tree/master/env).
 
-To create a new environment stack, create an envstack file and declare some
-variables.
+To create a new environment file, use `--set` to declare some variables:
 
 ```bash
-$ envstack foobar -o foobar.env
-```
-
-Add the `${FOO}` and `${BAR}` env vars to the foobar.env environment stack file:
-
-```yaml
-#!/usr/bin/env envstack
-all: &all
-  FOO: bar
-  BAR: ${FOO}
-darwin:
-  <<: *all
-linux:
-  <<: *all
-windows:
-  <<: *all
+$ envstack -s FOO=bar BAR=\${FOO} -o out.env
 ```
 
-Or using Python:
+Using Python:
 
 ```python
 >>> env = Env({"FOO": "bar", "BAR": "${FOO}"})
->>> env.write("foobar.env")
+>>> env.write("out.env")
 ```
 
-Get the resolved environment for the `foobar` stack:
+Get the resolved values back:
 
 ```bash
-$ ./foobar.env -r
+$ ./out.env -r
 BAR=bar
 FOO=bar
-STACK=foobar
+STACK=out
 ```
 
 #### More Details
@@ -354,7 +319,7 @@ nodes look for keys in the following order, favoring AES-GCM over Fernet:
 | Fernet | ${ENVSTACK_FERNET_KEY} |
 
 If no encryption keys are found in the environment, envstack will default to
-using Base64 encryption:
+using Base64 encoding:
 
 ```bash
 $ envstack --encrypt
@@ -381,7 +346,7 @@ $ source <(envstack --keygen --export)
 Once the keys are in the environment, you can encrypt the env stack:
 
 ```bash
-$ envstack --encrypt -o encrypted.env
+$ envstack -o encrypted.env --encrypt
 ```
 
 Encrypted variables will resolve as long as the key is in the environment:
@@ -393,17 +358,17 @@ HELLO=world
 
 #### Storing Keys
 
-Keys can be stored in other environment stacks, e.g. a `keys.env` file. To
-generate keys and store them in a `keys.env` env stack file:
+Keys can be stored in other environment stacks, e.g. a `keys.env` file
+(keys are automatically base64 encoded):
 
 ```bash
 $ envstack --keygen -o keys.env
 ```
 
-Then use the `keys.env` env stack to encrypt any other env stack:
+Then use `keys.env` to encrypt any other environment files:
 
 ```bash
-$ envstack keys -- envstack --encrypt -o encrypted.env
+$ ./keys.env -- envstack -eo encrypted.env
 ```
 
 To decrypt, add `keys` to the env stack:
@@ -413,7 +378,14 @@ $ envstack keys encrypted -r HELLO
 HELLO=world
 ```
 
-Or add the `keys` env stack to `include` to automatically decrypt:
+Or run the command inside the `keys` environment like this:
+
+```bash
+$ ./keys.env -- envsatck encrypted -r HELLO
+HELLO=world
+```
+
+Or include `keys` in environments to automatically decrypt:
 
 ```yaml
 include: [keys]

{envstack-0.9.0 → envstack-0.9.2}/setup.py

@@ -40,7 +40,7 @@ with open(os.path.join(here, "README.md")) as f:
 
 setup(
     name="envstack",
-    version="0.9.0",
+    version="0.9.2",
     description="Stacked environment variable management system",
     long_description=long_description,
     long_description_content_type="text/markdown",

{envstack-0.9.0 → envstack-0.9.2}/tests/test_cmds.py

@@ -52,7 +52,10 @@ def make_command(envstack_bin: str, filename: str, *args: str):
     Build a cross-platform shell command that runs envstack (with args)
     and then prints the output file.
     """
-    envstack_cmd = f'{envstack_bin} {" ".join(args)} -o "{filename}"'
+
+    envstack_cmd = f'{envstack_bin} {" ".join(args)}'
+    if filename:
+        envstack_cmd += f' -o "{filename}"'
 
     if os.name == "nt" or platform.system().lower().startswith("win"):
         return f'{envstack_cmd} & type "{filename}"'
@@ -131,14 +134,14 @@ STACK=distman
 
     def test_hello(self):
         expected_output = (
-            """DEPLOY_ROOT=${ROOT}/${ENV}
-ENV=prod
-ENVPATH=${DEPLOY_ROOT}/env:${ENVPATH}
+            """DEPLOY_ROOT=${ROOT}/dev
+ENV=dev
+ENVPATH=${ROOT}/dev/env:${ROOT}/prod/env:${ENVPATH}
 HELLO=${HELLO:=world}
 LOG_LEVEL=${LOG_LEVEL:=INFO}
-PATH=${DEPLOY_ROOT}/bin:${PATH}
+PATH=${ROOT}/dev/bin:${ROOT}/prod/bin:${PATH}
 PYEXE=/usr/bin/python
-PYTHONPATH=${DEPLOY_ROOT}/lib/python:${PYTHONPATH}
+PYTHONPATH=${ROOT}/dev/lib/python:${ROOT}/prod/lib/python:${PYTHONPATH}
 ROOT=%s
 STACK=hello
 """
@@ -212,33 +215,36 @@ STACK=ZGVmYXVsdA==
         """Test that the AESGCM encryption works, and resolves vars since the
         encrypted values change every time."""
         os.environ[AESGCMEncryptor.KEY_VAR_NAME] = AESGCMEncryptor.generate_key()
-        expected_output = f"""DEPLOY_ROOT={self.root}/prod
-ENV=prod
-ROOT={self.root}
-"""
-        command = "%s --encrypt -r ENV ROOT DEPLOY_ROOT" % self.envstack_bin
+        expected_output = f"""{self.root}/prod\n"""
+        command = "%s -e -- echo {DEPLOY_ROOT}" % self.envstack_bin
         output = subprocess.check_output(
             command, shell=True, env=os.environ, universal_newlines=True
         )
         self.assertEqual(output, expected_output)
 
     def test_default_resolve(self):
-        expected_output = f"""DEPLOY_ROOT={self.root}/prod
-ENV=prod
-ROOT={self.root}
-"""
-        command = "%s --encrypt -r ENV ROOT DEPLOY_ROOT" % self.envstack_bin
+        """Get and encrypt default stack values, and test they are resolved in a subprocess."""
+        expected_output = f"""{self.root}/prod\n"""
+        command = "%s --encrypt -- echo {DEPLOY_ROOT}" % self.envstack_bin
         output = subprocess.check_output(command, shell=True, universal_newlines=True)
         self.assertEqual(output, expected_output)
 
     def test_default_command_echo(self):
-        expected_output = f"""{self.root}/prod
-"""
+        """Tests that the default stack works with encrypted values."""
+        expected_output = f"""{self.root}/prod\n"""
         command = "%s --encrypt -- echo {DEPLOY_ROOT}" % self.envstack_bin
         output = subprocess.check_output(command, shell=True, universal_newlines=True)
         self.assertEqual(output, expected_output)
 
+    def test_hello_command_echo(self):
+        """Tests that resolved and encrypted values resolve in subprocesses."""
+        expected_output = f"""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)
+
     def test_dev(self):
+        """Tests encrypting values in the dev stack."""
         expected_output = """DEPLOY_ROOT=JHtST09UfS9kZXY=
 ENV=ZGV2
 ENVPATH=JHtST09UfS9kZXYvZW52OiR7Uk9PVH0vcHJvZC9lbnY6JHtFTlZQQVRIfQ==
@@ -253,18 +259,9 @@ STACK=ZGV2
         output = subprocess.check_output(command, shell=True, universal_newlines=True)
         self.assertEqual(output, expected_output)
 
-    def test_dev_resolve(self):
-        expected_output = f"""DEPLOY_ROOT={self.root}/dev
-ENV=dev
-ROOT={self.root}
-"""
-        command = "%s dev --encrypt -r ENV ROOT DEPLOY_ROOT" % self.envstack_bin
-        output = subprocess.check_output(command, shell=True, universal_newlines=True)
-        self.assertEqual(output, expected_output)
-
-    def test_dev_command_echo(self):
-        expected_output = f"""{self.root}/dev
-"""
+    def test_dev_command(self):
+        """Tests that encrypted values resolve in subprocess in the dev stack."""
+        expected_output = f"""{self.root}/dev\n"""
         command = "%s dev --encrypt -- echo {DEPLOY_ROOT}" % self.envstack_bin
         output = subprocess.check_output(command, shell=True, universal_newlines=True)
         self.assertEqual(output, expected_output)
@@ -421,26 +418,22 @@ windows:
 
     def test_dev(self):
         """Tests baking the dev stack."""
-        command = make_command(self.envstack_bin, self.filename, "dev")
+        command = make_command(self.envstack_bin, self.filename, "dev", "-d 1")
         expected_output = """#!/usr/bin/env envstack
-include: []
+include: [default]
 all: &all
   DEPLOY_ROOT: ${ROOT}/dev
   ENV: dev
   ENVPATH: ${ROOT}/dev/env:${ROOT}/prod/env:${ENVPATH}
-  HELLO: ${HELLO:=world}
   LOG_LEVEL: DEBUG
   PATH: ${ROOT}/dev/bin:${ROOT}/prod/bin:${PATH}
   PYTHONPATH: ${ROOT}/dev/lib/python:${ROOT}/prod/lib/python:${PYTHONPATH}
 darwin:
   <<: *all
-  ROOT: /Volumes/pipe
 linux:
   <<: *all
-  ROOT: /mnt/pipe
 windows:
   <<: *all
-  ROOT: X:/pipe
 """
         output = subprocess.check_output(
             command,
@@ -650,7 +643,7 @@ class TestSet(unittest.TestCase):
 
     def test_hello_world(self):
         """Tests setting HELLO to world."""
-        command = "%s --set HELLO:world" % self.envstack_bin
+        command = "%s --set HELLO=world --bare" % self.envstack_bin
         expected_output = "HELLO=world\n"
         output = subprocess.check_output(
             command,
@@ -661,7 +654,7 @@ class TestSet(unittest.TestCase):
 
     def test_hello_world_encrypted(self):
         """Tests setting HELLO to world encrypted."""
-        command = "%s --set HELLO:world --encrypt" % self.envstack_bin
+        command = "%s --set HELLO:world --encrypt --bare" % self.envstack_bin
         expected_output = "HELLO=d29ybGQ=\n"
         output = subprocess.check_output(
             command,
@@ -672,7 +665,7 @@ class TestSet(unittest.TestCase):
 
     def test_foo_bar(self):
         """Tests setting FOO and BAR."""
-        command = r"%s -s FOO:foo BAR:\${FOO}" % self.envstack_bin
+        command = r"%s -s FOO:foo BAR:\${FOO} --bare" % self.envstack_bin
         expected_output = "FOO=foo\nBAR=${FOO}\n"
         output = subprocess.check_output(
             command,
@@ -683,7 +676,7 @@ class TestSet(unittest.TestCase):
 
     def test_foo_bar_encrypted(self):
         """Tests setting FOO and BAR encrypted."""
-        command = r"%s -s FOO:foo BAR:\${FOO} --encrypt" % self.envstack_bin
+        command = r"%s -s FOO:foo BAR:\${FOO} --encrypt --bare" % self.envstack_bin
         expected_output = "FOO=Zm9v\nBAR=JHtGT099\n"
         output = subprocess.check_output(
             command,
@@ -695,7 +688,12 @@ class TestSet(unittest.TestCase):
     def test_foo_bar_bake(self):
         """Tests setting FOO and BAR and bake it out to a file."""
         command = make_command(
-            self.envstack_bin, self.filename, "--set", "FOO:foo", "BAR:\${FOO}"
+            self.envstack_bin,
+            self.filename,
+            "--set",
+            "FOO:foo",
+            "BAR:\${FOO}",  # not a typo, need to escape $ for shell
+            "--bare",
         )
         expected_output = """#!/usr/bin/env envstack
 include: []
@@ -723,8 +721,9 @@ windows:
             self.filename,
             "--set",
             "FOO:foo",
-            "BAR:\${FOO}",
+            "BAR:\${FOO}",  # not a typo, need to escape $ for shell
             "--encrypt",
+            "--bare",
         )
         expected_output = """#!/usr/bin/env envstack
 include: []
@@ -893,9 +892,10 @@ class TestIssues(unittest.TestCase):
         hello_env_file = os.path.join(self.root, "dev", "env", "hello.env")
         update_env_file(hello_env_file, "PYEXE", "/usr/bin/foobar")
 
-        # test "default" should only include prod sources
+        # 'envstack hello' should only include prod sources
         command = "%s hello --sources" % self.envstack_bin
         expected_output = f"""{self.root}/prod/env/default.env
+{self.root}/prod/env/dev.env
 {self.root}/prod/env/hello.env
 """
         output = subprocess.check_output(
@@ -903,7 +903,7 @@ class TestIssues(unittest.TestCase):
         )
         self.assertEqual(output, expected_output)
 
-        # test "dev" should include prod and dev sources
+        # 'envstack dev hello' should include prod and dev sources
         command = "%s dev hello --sources" % self.envstack_bin
         expected_output = f"""{self.root}/prod/env/default.env
 {self.root}/prod/env/dev.env

{envstack-0.9.0 → envstack-0.9.2}/tests/test_env.py

@@ -186,7 +186,7 @@ class TestEnv(unittest.TestCase):
 
         env1 = load_environ("thing")
         self.filename = "test_bake_out.env"
-        env1.write(self.filename)
+        env1.write(self.filename, depth=0)
         env2 = load_environ(self.filename)
         for k, v in env1.items():
             if k == "STACK":
@@ -809,7 +809,7 @@ class TestEncryptEnviron(unittest.TestCase):
             if key == "STACK":  # skip the stack name
                 continue
             encrypted_value = encrypted[key]
-            self.assertTrue(isinstance(encrypted_value, EncryptedNode))
+            self.assertTrue(isinstance(encrypted_value, EncryptedNode), f"type is {type(encrypted_value)}")
             self.assertEqual(encrypted_value.original_value, None)
             # self.assertNotEqual(encrypted_value.original_value, value)  # from_yaml only
             self.assertEqual(encrypted_value.value, value)
@@ -955,6 +955,7 @@ class TestIssues(unittest.TestCase):
 
         expected_paths = [
             os.path.join(self.root, "prod", "env", "default.env"),
+            os.path.join(self.root, "prod", "env", "dev.env"),
             os.path.join(self.root, "prod", "env", "hello.env"),
         ]
         self.assertEqual(paths, expected_paths)