envstack 0.7.1__tar.gz → 0.7.2__tar.gz

{envstack-0.7.1/lib/envstack.egg-info → envstack-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: envstack
-Version: 0.7.1
+Version: 0.7.2
 Summary: Stacked environment variable management system
 Home-page: http://github.com/rsgalloway/envstack
 Author: Ryan Galloway
@@ -34,6 +34,7 @@ Environment variable management system.
 | 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. |
@@ -127,6 +128,43 @@ scope to lower scope, left to right):
 $ envstack [STACK [STACK ...]]
 ```
 
+#### Executing Scripts
+
+Environment stack files are also executable scripts that can be run directly:
+
+
+```bash
+$ ./env/test.env
+DEPLOY_ROOT=${ROOT}/${STACK}
+ENV=${STACK}
+ENVPATH=${DEPLOY_ROOT}/env:${ROOT}/prod/env
+HELLO=${HELLO:=world}
+LOG_LEVEL=DEBUG
+PATH=${DEPLOY_ROOT}/bin:${ROOT}/prod/bin:${PATH}
+PYTHONPATH=${DEPLOY_ROOT}/lib/python:${ROOT}/prod/lib/python:${PYTHONPATH}
+ROOT=/mnt/pipe
+STACK=test
+```
+
+Run commands inside a specific environment stack file:
+
+```bash
+$ ./env/test.env -- <command>
+```
+
+For example:
+
+```bash
+$ ./env/hello.env -- echo {HELLO}
+world
+```
+
+Export a specific environment stack file:
+
+```bash
+$ ./env/hello.env --export
+```
+
 ## Setting Values
 
 Envstack uses bash-like variable expansion modifiers. Setting `$VAR` to a fixed
@@ -180,40 +218,67 @@ goodbye
 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 blank environment stack, create a new namespaced .env file and
-declare some variables.
+To create a blank environment stack, create a new envstack file and declare some
+variables.
+
+Create a new stack file called "foobar.env" and make it executable (note: at
+least one VAR needs to be defined under all):
 
-For example `foo.env` (the stack name is "foo"):
+#### foobar.env
 
 ```yaml
+#!/usr/bin/env envstack
+
 all: &default
   FOO: bar
   BAR: ${FOO}
+darwin:
+  <<: *default
+linux:
+  <<: *default
+windows:
+  <<: *default
+```
+
+Make it executable
+
+```bash
+$ chmod +x ./foobar.env
 ```
 
-To see the resolved environment for the `foo` environment stack, run:
+To see the resolved environment for the `foobar` stack, run:
 
 ```bash
-$ envstack foo
+$ envstack foobar
 FOO=bar
 BAR=$FOO
 ```
 
+or execute it directly:
+
+```bash
+$ ./foobar.env
+```
+
 To see resolved values:
 
 ```bash
-$ envstack foo -r
+$ ./foobar.env -r
 FOO=bar
 BAR=bar
 ```
 
-Variables can be platform specific (but always inherit from `all`):
+#### More Details
+
+Variables can be platform specific:
 
 ```yaml
+darwin:
+  <<: *default
+  HELLO: olleh
 linux:
   <<: *default
   HELLO: world
-
 windows:
   <<: *default
   HELLO: goodbye
@@ -365,7 +430,7 @@ environment stack that sets a value for `${PYEXE}`:
 #### hello.env
 ```yaml
 all: &default
-  PYEXE: python
+  PYEXE: /usr/bin/python
 ```
 
 #### bin/hello
@@ -434,7 +499,7 @@ The following environment variables are used to help manage functionality:
 |------|-------------|
 | ENVPATH | Colon-separated paths to search for stack files |
 | IGNORE_MISSING | Ignore missing stack files when resolving environments |
-| STACK | Name of the current stack |
+| STACK | Name of the current environment stack |
 
 # Tests
 

{envstack-0.7.1 → envstack-0.7.2}/README.md

@@ -11,6 +11,7 @@ Environment variable management system.
 | 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. |
@@ -104,6 +105,43 @@ scope to lower scope, left to right):
 $ envstack [STACK [STACK ...]]
 ```
 
+#### Executing Scripts
+
+Environment stack files are also executable scripts that can be run directly:
+
+
+```bash
+$ ./env/test.env
+DEPLOY_ROOT=${ROOT}/${STACK}
+ENV=${STACK}
+ENVPATH=${DEPLOY_ROOT}/env:${ROOT}/prod/env
+HELLO=${HELLO:=world}
+LOG_LEVEL=DEBUG
+PATH=${DEPLOY_ROOT}/bin:${ROOT}/prod/bin:${PATH}
+PYTHONPATH=${DEPLOY_ROOT}/lib/python:${ROOT}/prod/lib/python:${PYTHONPATH}
+ROOT=/mnt/pipe
+STACK=test
+```
+
+Run commands inside a specific environment stack file:
+
+```bash
+$ ./env/test.env -- <command>
+```
+
+For example:
+
+```bash
+$ ./env/hello.env -- echo {HELLO}
+world
+```
+
+Export a specific environment stack file:
+
+```bash
+$ ./env/hello.env --export
+```
+
 ## Setting Values
 
 Envstack uses bash-like variable expansion modifiers. Setting `$VAR` to a fixed
@@ -157,40 +195,67 @@ goodbye
 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 blank environment stack, create a new namespaced .env file and
-declare some variables.
+To create a blank environment stack, create a new envstack file and declare some
+variables.
+
+Create a new stack file called "foobar.env" and make it executable (note: at
+least one VAR needs to be defined under all):
 
-For example `foo.env` (the stack name is "foo"):
+#### foobar.env
 
 ```yaml
+#!/usr/bin/env envstack
+
 all: &default
   FOO: bar
   BAR: ${FOO}
+darwin:
+  <<: *default
+linux:
+  <<: *default
+windows:
+  <<: *default
+```
+
+Make it executable
+
+```bash
+$ chmod +x ./foobar.env
 ```
 
-To see the resolved environment for the `foo` environment stack, run:
+To see the resolved environment for the `foobar` stack, run:
 
 ```bash
-$ envstack foo
+$ envstack foobar
 FOO=bar
 BAR=$FOO
 ```
 
+or execute it directly:
+
+```bash
+$ ./foobar.env
+```
+
 To see resolved values:
 
 ```bash
-$ envstack foo -r
+$ ./foobar.env -r
 FOO=bar
 BAR=bar
 ```
 
-Variables can be platform specific (but always inherit from `all`):
+#### More Details
+
+Variables can be platform specific:
 
 ```yaml
+darwin:
+  <<: *default
+  HELLO: olleh
 linux:
   <<: *default
   HELLO: world
-
 windows:
   <<: *default
   HELLO: goodbye
@@ -342,7 +407,7 @@ environment stack that sets a value for `${PYEXE}`:
 #### hello.env
 ```yaml
 all: &default
-  PYEXE: python
+  PYEXE: /usr/bin/python
 ```
 
 #### bin/hello
@@ -411,7 +476,7 @@ The following environment variables are used to help manage functionality:
 |------|-------------|
 | ENVPATH | Colon-separated paths to search for stack files |
 | IGNORE_MISSING | Ignore missing stack files when resolving environments |
-| STACK | Name of the current stack |
+| STACK | Name of the current environment stack |
 
 # Tests
 

{envstack-0.7.1 → envstack-0.7.2}/lib/envstack/__init__.py

@@ -34,6 +34,6 @@ Stacked environment variable management system.
 """
 
 __prog__ = "envstack"
-__version__ = "0.7.1"
+__version__ = "0.7.2"
 
 from envstack.env import clear, init, revert, save

{envstack-0.7.1 → envstack-0.7.2}/lib/envstack/cli.py

@@ -145,12 +145,11 @@ def main():
         if command:
             return run_command(command, args.namespace)
         elif args.resolve is not None:
-            if len(args.resolve) == 0:
-                args.resolve = load_environ(args.namespace).keys()
             resolved = resolve_environ(
                 load_environ(args.namespace, platform=args.platform)
             )
-            for key in sorted(args.resolve):
+            keys = args.resolve or resolved.keys()
+            for key in sorted(keys):
                 val = resolved.get(key)
                 print(f"{key}={val}")
         elif args.trace is not None:

{envstack-0.7.1 → envstack-0.7.2}/lib/envstack/env.py

@@ -106,7 +106,7 @@ class EnvVar(string.Template, str):
         try:
             val = EnvVar(self.safe_substitute(env))
         except RuntimeError as err:
-            if "maximum recursion depth exceeded" in str(err):
+            if "maximum recursion" in str(err):
                 raise CyclicalReference(self.template)
             else:
                 raise InvalidSyntax(err)
@@ -287,7 +287,9 @@ def get_sources(
     :raises TemplateNotFound: if a file is not found in ENVPATH or scope.
     :returns: list of Source objects.
     """
-    clear_file_cache()
+
+    # TODO: smarter file caching (issue #26)
+    # clear_file_cache()
 
     # set default scope to the current working directory
     scope = Path(scope or os.getcwd()).resolve()
@@ -396,39 +398,53 @@ def clear(
     """
 
     env = load_environ(name, scope=scope)
+
+    # track the environment variables to export
     export_list = list()
-    restricted = ["PATH", "PS1", "PWD", "PROMPT"]
+
+    # restricted environment variables
+    restricted = [
+        "PATH",
+        "PYTHONPATH",
+        "ENVPATH",
+        "PS1",
+        "PWD",
+        "PROMPT",
+    ]
+
+    # get the name of the shell
+    shell_name = os.path.basename(shell)
 
     for key in env:
         if key not in os.environ:
             continue
         old_key = f"_ES_OLD_{key}"
         old_val = os.environ.get(old_key)
-        if shell in ["bash", "sh", "zsh"]:
+        if shell_name in ["bash", "sh", "zsh"]:
             if old_val:
                 export_list.append("export %s=%s" % (key, old_val))
                 export_list.append("unset %s" % (old_key))
             elif key not in restricted:
                 export_list.append(f"unset {key}")
-        elif shell == "tcsh":
+        elif shell_name == "tcsh":
             if old_val:
                 export_list.append(f"setenv {key} {old_val}")
                 export_list.append(f"unsetenv {old_key}")
             elif key not in restricted:
                 export_list.append(f"unsetenv {key}")
-        elif shell == "cmd":
+        elif shell_name == "cmd":
             if old_val:
                 export_list.append(f"set {key}={old_val}")
                 export_list.append(f"set {old_key}=")
             elif key not in restricted:
                 export_list.append(f"set {key}=")
-        elif shell == "pwsh":
+        elif shell_name == "pwsh":
             if old_val:
                 export_list.append(f"$env:{key}='{old_val}'")
                 export_list.append(f"Remove-Item Env:{old_key}")
             elif key not in restricted:
                 export_list.append(f"Remove-Item Env:{key}")
-        elif shell == "unknown":
+        elif shell_name == "unknown":
             raise Exception("unknown shell")
 
     export_list.sort()
@@ -460,29 +476,32 @@ def export(
     # track the environment variables to export
     export_list = list()
 
+    # get the name of the shell
+    shell_name = os.path.basename(shell)
+
     for key, val in resolved_env.items():
         old_key = f"_ES_OLD_{key}"
         old_val = os.environ.get(key)
         if key == "PATH" and not val:
             logger.log.warning("PATH is empty")
             continue
-        if shell in ["bash", "sh", "zsh"]:
+        if shell_name in ["bash", "sh", "zsh"]:
             export_list.append(f"export {key}={val}")
             if old_val:
                 export_list.append(f"export {old_key}={old_val}")
-        elif shell == "tcsh":
+        elif shell_name == "tcsh":
             export_list.append(f'setenv {key}:"{val}"')
             if old_val:
                 export_list.append(f'setenv {old_key}:"{old_val}"')
-        elif shell == "cmd":
+        elif shell_name == "cmd":
             export_list.append(f'set {key}="{val}"')
             if old_val:
                 export_list.append(f'set {old_key}="{old_val}"')
-        elif shell == "pwsh":
+        elif shell_name == "pwsh":
             export_list.append(f'$env:{key}="{val}"')
             if old_val:
                 export_list.append(f'$env:{old_key}="{old_val}"')
-        elif shell == "unknown":
+        elif shell_name == "unknown":
             raise Exception("unknown shell")
 
     export_list.sort()
@@ -652,24 +671,12 @@ def load_file(path: str):
     if path in load_file_cache:
         return load_file_cache[path]
 
-    data = {}
-
     if not os.path.exists(path):
-        return data
+        return {}
 
-    import yaml
-
-    with open(path) as stream:
-        try:
-            data.update(yaml.safe_load(stream))
-        except (TypeError, yaml.YAMLError) as exc:
-            logger.log.error(exc)
-            raise InvalidSource(path)
-        except yaml.parser.ParserError as err:
-            logger.log.error(err)
-            raise InvalidSource(path)
-
-    load_file_cache[path] = data
+    else:
+        data = util.validate_yaml(path)
+        load_file_cache[path] = data
 
     return data
 

{envstack-0.7.1 → envstack-0.7.2}/lib/envstack/util.py

@@ -160,15 +160,15 @@ def get_paths_from_var(
 def get_stack_name(name: str = config.DEFAULT_NAMESPACE):
     """
     Returns the stack name as a string. The stack name is always the last
-    element in the stack list.
+    element in the stack list or the basename of the envstack file.
 
     :param name: The input name, can be a string, tuple, or list.
     :return: The stack name as a string.
     """
+    if isinstance(name, (tuple, list)):
+        name = str(name[-1]) if name else config.DEFAULT_NAMESPACE
     if isinstance(name, str):
-        return name
-    elif isinstance(name, (tuple, list)):
-        return str(name[-1]) if name else ""
+        return os.path.splitext(os.path.basename(name))[0]
     else:
         raise ValueError("Invalid input type. Expected string, tuple, or list.")
 
@@ -344,3 +344,62 @@ def findenv(var_name):
             paths.add(path)
 
     return sorted(list(paths))
+
+
+def print_error(file_path: str, e: Exception):
+    """
+    Prints the problematic line and a few surrounding lines for context.
+
+    :param file_path: Path to the file.
+    :param e: The exception.
+    """
+    try:
+        with open(file_path, "r") as file:
+            lines = file.readlines()
+            if hasattr(e, "problem_mark") and e.problem_mark:
+                line_num = e.problem_mark.line - 1
+                # problematic line and a few surrounding lines for context
+                start = max(0, line_num - 1)
+                end = min(len(lines), line_num + 2)
+                for i in range(start, end):
+                    prefix = ">> " if i == line_num else "   "
+                    print(f"{prefix}{i + 1}: {lines[i].rstrip()}")
+    except Exception as ex:
+        print("read error:", ex)
+
+
+def validate_yaml(file_path: str):
+    """
+    Loads a YAML file and prints helpful error hints if invalid.
+
+    :param file_path: Path to the YAML file to validate.
+    """
+    import yaml
+
+    required_keys = {"all", "darwin", "linux", "windows"}
+
+    try:
+        with open(file_path, "r") as stream:
+            data = yaml.safe_load(stream.read())
+
+        if not isinstance(data, dict):
+            raise yaml.YAMLError("invalid data structure")
+
+        missing_keys = required_keys - data.keys()
+        if missing_keys:
+            raise yaml.YAMLError(f"missing keys: {', '.join(sorted(missing_keys))}")
+
+        return data
+
+    except yaml.YAMLError as e:
+        if hasattr(e, "problem_mark") and e.problem_mark:
+            mark = e.problem_mark
+            print(f'  File "{file_path}" line {mark.line}, column {mark.column}:')
+        print_error(file_path, e)
+        if hasattr(e, "problem") and e.problem:
+            print(f"SyntaxError: {e.problem}")
+        else:
+            print(f'  File "{file_path}":')
+            print(f"SyntaxError: {e}")
+
+    return {}

{envstack-0.7.1 → envstack-0.7.2/lib/envstack.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: envstack
-Version: 0.7.1
+Version: 0.7.2
 Summary: Stacked environment variable management system
 Home-page: http://github.com/rsgalloway/envstack
 Author: Ryan Galloway
@@ -34,6 +34,7 @@ Environment variable management system.
 | 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. |
@@ -127,6 +128,43 @@ scope to lower scope, left to right):
 $ envstack [STACK [STACK ...]]
 ```
 
+#### Executing Scripts
+
+Environment stack files are also executable scripts that can be run directly:
+
+
+```bash
+$ ./env/test.env
+DEPLOY_ROOT=${ROOT}/${STACK}
+ENV=${STACK}
+ENVPATH=${DEPLOY_ROOT}/env:${ROOT}/prod/env
+HELLO=${HELLO:=world}
+LOG_LEVEL=DEBUG
+PATH=${DEPLOY_ROOT}/bin:${ROOT}/prod/bin:${PATH}
+PYTHONPATH=${DEPLOY_ROOT}/lib/python:${ROOT}/prod/lib/python:${PYTHONPATH}
+ROOT=/mnt/pipe
+STACK=test
+```
+
+Run commands inside a specific environment stack file:
+
+```bash
+$ ./env/test.env -- <command>
+```
+
+For example:
+
+```bash
+$ ./env/hello.env -- echo {HELLO}
+world
+```
+
+Export a specific environment stack file:
+
+```bash
+$ ./env/hello.env --export
+```
+
 ## Setting Values
 
 Envstack uses bash-like variable expansion modifiers. Setting `$VAR` to a fixed
@@ -180,40 +218,67 @@ goodbye
 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 blank environment stack, create a new namespaced .env file and
-declare some variables.
+To create a blank environment stack, create a new envstack file and declare some
+variables.
+
+Create a new stack file called "foobar.env" and make it executable (note: at
+least one VAR needs to be defined under all):
 
-For example `foo.env` (the stack name is "foo"):
+#### foobar.env
 
 ```yaml
+#!/usr/bin/env envstack
+
 all: &default
   FOO: bar
   BAR: ${FOO}
+darwin:
+  <<: *default
+linux:
+  <<: *default
+windows:
+  <<: *default
+```
+
+Make it executable
+
+```bash
+$ chmod +x ./foobar.env
 ```
 
-To see the resolved environment for the `foo` environment stack, run:
+To see the resolved environment for the `foobar` stack, run:
 
 ```bash
-$ envstack foo
+$ envstack foobar
 FOO=bar
 BAR=$FOO
 ```
 
+or execute it directly:
+
+```bash
+$ ./foobar.env
+```
+
 To see resolved values:
 
 ```bash
-$ envstack foo -r
+$ ./foobar.env -r
 FOO=bar
 BAR=bar
 ```
 
-Variables can be platform specific (but always inherit from `all`):
+#### More Details
+
+Variables can be platform specific:
 
 ```yaml
+darwin:
+  <<: *default
+  HELLO: olleh
 linux:
   <<: *default
   HELLO: world
-
 windows:
   <<: *default
   HELLO: goodbye
@@ -365,7 +430,7 @@ environment stack that sets a value for `${PYEXE}`:
 #### hello.env
 ```yaml
 all: &default
-  PYEXE: python
+  PYEXE: /usr/bin/python
 ```
 
 #### bin/hello
@@ -434,7 +499,7 @@ The following environment variables are used to help manage functionality:
 |------|-------------|
 | ENVPATH | Colon-separated paths to search for stack files |
 | IGNORE_MISSING | Ignore missing stack files when resolving environments |
-| STACK | Name of the current stack |
+| STACK | Name of the current environment stack |
 
 # Tests
 

{envstack-0.7.1 → envstack-0.7.2}/setup.py

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

{envstack-0.7.1 → envstack-0.7.2}/tests/test_cmds.py

@@ -123,7 +123,7 @@ LOG_LEVEL=${LOG_LEVEL:=INFO}
 NUMBER_LIST=[1, 2, 3]
 PATH=${DEPLOY_ROOT}/bin:${PATH}
 PYTHONPATH=${DEPLOY_ROOT}/lib/python:${PYTHONPATH}
-ROOT=/var/tmp/pipe
+ROOT=${HOME}/.local/pipe
 STACK=thing
 """
         command = "%s thing" % self.envstack_bin
@@ -208,8 +208,10 @@ STACK=foobar
         self.assertEqual(output, expected_output)
 
     def test_thing(self):
-        expected_output = """CHAR_LIST=['a', 'b', 'c', 'goodbye']
-DEPLOY_ROOT=/var/tmp/pipe/prod
+        home = os.getenv("HOME")
+        deploy_root = f"{home}/.local/pipe/prod"  # linux only for now
+        expected_output = f"""CHAR_LIST=['a', 'b', 'c', 'goodbye']
+DEPLOY_ROOT={deploy_root}
 HELLO=goodbye
 """
         command = "%s thing -r DEPLOY_ROOT HELLO CHAR_LIST" % self.envstack_bin

{envstack-0.7.1 → envstack-0.7.2}/tests/test_util.py

@@ -36,6 +36,7 @@ Contains unit tests for the util.py module.
 import os
 import unittest
 
+from envstack import config
 from envstack.exceptions import CyclicalReference
 from envstack.util import encode, evaluate_modifiers, get_stack_name, safe_eval
 
@@ -127,7 +128,7 @@ class TestUtils(unittest.TestCase):
     def test_get_stack_name_empty(self):
         name = []
         result = get_stack_name(name)
-        self.assertEqual(result, "")
+        self.assertEqual(result, config.DEFAULT_NAMESPACE)
 
     def test_get_stack_name_invalid_type(self):
         name = 123