envstack 0.4.2__tar.gz → 0.5.0__tar.gz

{envstack-0.4.2 → envstack-0.5.0}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.1
 Name: envstack
-Version: 0.4.2
+Version: 0.5.0
 Summary: Stacked environment variable management system.
 Home-page: http://github.com/rsgalloway/envstack
 Author: Ryan Galloway
 Author-email: ryan@rsgalloway.com
 Description-Content-Type: text/markdown
 Requires-Dist: PyYAML>=5.1.2
-Requires-Dist: siteconf>=0.1.7
 
 envstack
 ========
@@ -16,11 +15,9 @@ Stacked environment variable management system. The lightweight, easy to use
 "rez" alternative for production pipelines.
 
 Environment variables are declared in namespaced .env files using yaml syntax.
-The default stack is `stack` and variables are declared in `stack.env`
-files. You can create any new stack by creating new `.env` files, e.g. creating
-a new `test` stack just create `test.env` files.
-
-> **Note:** envstack works best combined with [siteconf](https://github.com/rsgalloway/siteconf).
+The default stack declares env variables in `stack.env` files. You can create any
+new stack by creating new `.env` files, e.g. to create a new `thing` stack just
+create `thing.env` files in any given context.
 
 ## Installation
 
@@ -30,47 +27,66 @@ The easiest way to install:
 $ pip install envstack
 ```
 
-## Quickstart
+Alternatively,
+
+```bash
+$ git clone https://github.com/rsgalloway/envstack
+$ cd envstack
+$ python setup.py install
+```
 
-Copy the default stack file
-[`stack.env`](https://github.com/rsgalloway/envstack/blob/master/stack.env)
-to your current working directory, the root of your project or $DEFAULT_ENV_DIR if defined (defaults: /etc/envstack on posix platforms and C:/ProgramData/envstack on Windows).
+The install process will automatically attempt to install the default `stack.env` file to the
+default env file directory defined `$DEFAULT_ENV_DIR`. **Note:** The [siteconf](https://github.com/rsgalloway/siteconf) sitecustomize.py module may override `$DEFAULT_ENV_DIR`.
 
+If installing from source, you can use [distman](https://github.com/rsgalloway/distman) to
+install envstack and the default `stack.env` file using the provided `dist.json` file:
 
-```bach
-$ cp stack.env $DEFAULT_ENV_DIR
+```bash
+$ distman
 ```
 
+## Quickstart
+
 The `stack` namespace is the default environment stack. Running the `envstack` command
-should show you the resolved environment for your platform:
+should show you the default environment stack:
 
 ```bash
 $ envstack
-ENV 'prod'
-HELLO 'world'
-FOO 'bar'
-PYVERSION 3.11
-LIB 'lib/python3.11'
-LOG_LEVEL 20
-ROOT '/mnt/tools/lib/python3.11'
+ENV=prod
+HELLO=world
+LOG_LEVEL=INFO
+DEFAULT_ENV_DIR=${DEPLOY_ROOT}/env
+DEPLOY_ROOT=${ROOT}/${ENV}
+ROOT=${HOME}/.local/envstack
 ```
 
-Modify the environment stack by updating `stack.env` or by creating new contextual
-`stack.env` files up and down the project hierarchy.
+Modify the environment stack by editing `stack.env` or by creating new contextual
+`stack.env` files up on the filesystem.
 
 You can execute any command inside the default stacked environment like this:
 
 ```bash
-$ envstack -- <command>
+$ envstack -- [COMMAND]
 ```
 
-For example:
+For example, use the `echo` command to see the resolved value of `$HELLO` (note: we
+have to escape it first to it's not pre-expanded in the shell):
+
+```bash 
+$ envstack -- echo \$HELLO
+world
+```
+
+Any command can be run in an envstack environment by preceeding the command
+with `--`:
 
 ```bash
 $ envstack -- python -c "import os; print(os.environ['HELLO'])"
 world
 ```
 
+## Creating Stacks
+
 To create a new environment stack, create a new namespaced .env file.
 For example `thing.env` (the stack namespace is "thing"):
 
@@ -86,16 +102,6 @@ $ envstack thing
 FOO 'bar'
 ```
 
-Environment stacks are hierarchical, so values for `$FOO` defined in .env files lower
-in the filesystem (lower in scope) override those defined higher up (higher in scope):
-
-```
-/show/thing.env
-/show/seq/thing.env
-/show/seq/shot/thing.env
-/show/seq/shot/task/thing.env
-```
-
 Variables can reference other variables defined elsewhere (but cannot be circular):
 
 ```yaml
@@ -117,71 +123,76 @@ Environment files can include other namespaced environments (all stacks inherit
 include: ['other']
 ```
 
-## Usage
+## Context
 
-To see the default resolved environment for any given scope (directory):
+Environment stacks are hierarchical, so values for `$FOO` defined in .env files lower
+in the filesystem (lower in scope) override those defined higher up (higher in scope):
 
-```bash
-$ envstack
+```
+${DEFAULT_ENV_DIR}
+/stack.env
+/show/stack.env
+/show/seq/stack.env
+/show/seq/shot/stack.env
+/show/seq/shot/task/stack.env
 ```
 
-To see the resolved environment for a given namespace.
+If you are working in the task directory, those envstack $VARs will override the
+$VARs defined in the shot, seq, show and root directories.
+
+
+## Usage
+
+To see the default environment for any given stack:
 
 ```bash
-$ envstack <stack> [OPTIONS]
+$ envstack [STACK]
 ```
 
-To resolve a `$VAR` declaration for a given environment stack:
+To resolve one or more environment vars for a given stack:
 
 ```bash
-$ envstack <stack> -r <VAR>
+$ envstack [STACK] -r [VAR [VAR ...]]
 ```
 
-To trace where a `$VAR` declaration is being set:
+To trace where one or more environment vars is being set:
 
 ```bash
-$ envstack <stack> -t <VAR>
+$ envstack [STACK] -t [VAR [VAR ...]]
 ```
 
-To see an environment stack on another platform:
+To get the list of source files for a given stack:
 
 ```bash
-$ envstack <stack> -p <platform>
+$ envstack [STACK] --sources
 ```
 
 ## Python API
 
-By default, `envstack.getenv` uses the resolved default env stack `stack` and can be
-a drop-in replacement for `os.getenv` 
-
-```python
->>> import envstack
->>> envstack.getenv("HELLO")
-'world'
-```
-
-To use a different stack, use the `init` function:
+To init the environment stack, use the `init` function:
 
 ```python
 >>> envstack.init("thing")
->>> envstack.getenv("FOO")
+>>> os.getenv("FOO")
 'bar'
 ```
 
-The `init` function also updates the current environment for code that is not using envstack:
+Alternatively, `envstack.getenv` uses the default environment stack `stack` and can be
+a drop-in replacement for `os.getenv` 
 
 ```python
->>> os.getenv("FOO")
-'bar'
+>>> import envstack
+>>> envstack.getenv("HELLO")
+'world'
 ```
 
 ## Running Commands
 
-To run any command line executable inside of an environment stack, where `<command>`
+To run any command line executable inside of an environment stack, where `[COMMAND]`
 is the command to run:
 
 ```bash
-$ envstack <stack> -- <command>
+$ envstack [STACK] -- [COMMAND]
 ```
 
 For example, running python in the default stack (reading from the default `stack.env` file):

{envstack-0.4.2 → envstack-0.5.0}/README.md

@@ -5,11 +5,9 @@ Stacked environment variable management system. The lightweight, easy to use
 "rez" alternative for production pipelines.
 
 Environment variables are declared in namespaced .env files using yaml syntax.
-The default stack is `stack` and variables are declared in `stack.env`
-files. You can create any new stack by creating new `.env` files, e.g. creating
-a new `test` stack just create `test.env` files.
-
-> **Note:** envstack works best combined with [siteconf](https://github.com/rsgalloway/siteconf).
+The default stack declares env variables in `stack.env` files. You can create any
+new stack by creating new `.env` files, e.g. to create a new `thing` stack just
+create `thing.env` files in any given context.
 
 ## Installation
 
@@ -19,47 +17,66 @@ The easiest way to install:
 $ pip install envstack
 ```
 
-## Quickstart
+Alternatively,
+
+```bash
+$ git clone https://github.com/rsgalloway/envstack
+$ cd envstack
+$ python setup.py install
+```
 
-Copy the default stack file
-[`stack.env`](https://github.com/rsgalloway/envstack/blob/master/stack.env)
-to your current working directory, the root of your project or $DEFAULT_ENV_DIR if defined (defaults: /etc/envstack on posix platforms and C:/ProgramData/envstack on Windows).
+The install process will automatically attempt to install the default `stack.env` file to the
+default env file directory defined `$DEFAULT_ENV_DIR`. **Note:** The [siteconf](https://github.com/rsgalloway/siteconf) sitecustomize.py module may override `$DEFAULT_ENV_DIR`.
 
+If installing from source, you can use [distman](https://github.com/rsgalloway/distman) to
+install envstack and the default `stack.env` file using the provided `dist.json` file:
 
-```bach
-$ cp stack.env $DEFAULT_ENV_DIR
+```bash
+$ distman
 ```
 
+## Quickstart
+
 The `stack` namespace is the default environment stack. Running the `envstack` command
-should show you the resolved environment for your platform:
+should show you the default environment stack:
 
 ```bash
 $ envstack
-ENV 'prod'
-HELLO 'world'
-FOO 'bar'
-PYVERSION 3.11
-LIB 'lib/python3.11'
-LOG_LEVEL 20
-ROOT '/mnt/tools/lib/python3.11'
+ENV=prod
+HELLO=world
+LOG_LEVEL=INFO
+DEFAULT_ENV_DIR=${DEPLOY_ROOT}/env
+DEPLOY_ROOT=${ROOT}/${ENV}
+ROOT=${HOME}/.local/envstack
 ```
 
-Modify the environment stack by updating `stack.env` or by creating new contextual
-`stack.env` files up and down the project hierarchy.
+Modify the environment stack by editing `stack.env` or by creating new contextual
+`stack.env` files up on the filesystem.
 
 You can execute any command inside the default stacked environment like this:
 
 ```bash
-$ envstack -- <command>
+$ envstack -- [COMMAND]
 ```
 
-For example:
+For example, use the `echo` command to see the resolved value of `$HELLO` (note: we
+have to escape it first to it's not pre-expanded in the shell):
+
+```bash 
+$ envstack -- echo \$HELLO
+world
+```
+
+Any command can be run in an envstack environment by preceeding the command
+with `--`:
 
 ```bash
 $ envstack -- python -c "import os; print(os.environ['HELLO'])"
 world
 ```
 
+## Creating Stacks
+
 To create a new environment stack, create a new namespaced .env file.
 For example `thing.env` (the stack namespace is "thing"):
 
@@ -75,16 +92,6 @@ $ envstack thing
 FOO 'bar'
 ```
 
-Environment stacks are hierarchical, so values for `$FOO` defined in .env files lower
-in the filesystem (lower in scope) override those defined higher up (higher in scope):
-
-```
-/show/thing.env
-/show/seq/thing.env
-/show/seq/shot/thing.env
-/show/seq/shot/task/thing.env
-```
-
 Variables can reference other variables defined elsewhere (but cannot be circular):
 
 ```yaml
@@ -106,71 +113,76 @@ Environment files can include other namespaced environments (all stacks inherit
 include: ['other']
 ```
 
-## Usage
+## Context
 
-To see the default resolved environment for any given scope (directory):
+Environment stacks are hierarchical, so values for `$FOO` defined in .env files lower
+in the filesystem (lower in scope) override those defined higher up (higher in scope):
 
-```bash
-$ envstack
+```
+${DEFAULT_ENV_DIR}
+/stack.env
+/show/stack.env
+/show/seq/stack.env
+/show/seq/shot/stack.env
+/show/seq/shot/task/stack.env
 ```
 
-To see the resolved environment for a given namespace.
+If you are working in the task directory, those envstack $VARs will override the
+$VARs defined in the shot, seq, show and root directories.
+
+
+## Usage
+
+To see the default environment for any given stack:
 
 ```bash
-$ envstack <stack> [OPTIONS]
+$ envstack [STACK]
 ```
 
-To resolve a `$VAR` declaration for a given environment stack:
+To resolve one or more environment vars for a given stack:
 
 ```bash
-$ envstack <stack> -r <VAR>
+$ envstack [STACK] -r [VAR [VAR ...]]
 ```
 
-To trace where a `$VAR` declaration is being set:
+To trace where one or more environment vars is being set:
 
 ```bash
-$ envstack <stack> -t <VAR>
+$ envstack [STACK] -t [VAR [VAR ...]]
 ```
 
-To see an environment stack on another platform:
+To get the list of source files for a given stack:
 
 ```bash
-$ envstack <stack> -p <platform>
+$ envstack [STACK] --sources
 ```
 
 ## Python API
 
-By default, `envstack.getenv` uses the resolved default env stack `stack` and can be
-a drop-in replacement for `os.getenv` 
-
-```python
->>> import envstack
->>> envstack.getenv("HELLO")
-'world'
-```
-
-To use a different stack, use the `init` function:
+To init the environment stack, use the `init` function:
 
 ```python
 >>> envstack.init("thing")
->>> envstack.getenv("FOO")
+>>> os.getenv("FOO")
 'bar'
 ```
 
-The `init` function also updates the current environment for code that is not using envstack:
+Alternatively, `envstack.getenv` uses the default environment stack `stack` and can be
+a drop-in replacement for `os.getenv` 
 
 ```python
->>> os.getenv("FOO")
-'bar'
+>>> import envstack
+>>> envstack.getenv("HELLO")
+'world'
 ```
 
 ## Running Commands
 
-To run any command line executable inside of an environment stack, where `<command>`
+To run any command line executable inside of an environment stack, where `[COMMAND]`
 is the command to run:
 
 ```bash
-$ envstack <stack> -- <command>
+$ envstack [STACK] -- [COMMAND]
 ```
 
 For example, running python in the default stack (reading from the default `stack.env` file):

{envstack-0.4.2 → envstack-0.5.0}/lib/envstack/__init__.py

@@ -34,6 +34,7 @@ Stacked environment variable management system.
 """
 
 __prog__ = "envstack"
-__version__ = "0.4.2"
+__version__ = "0.5.0"
 
-from envstack.env import getenv, init
+from envstack.env import Env
+from envstack.env import getenv, init, load_file

{envstack-0.4.2 → envstack-0.5.0}/lib/envstack/cli.py

@@ -30,12 +30,10 @@
 #
 
 __doc__ = """
-Contains command line interface for envstack.
+Command line interface for envstack: stacked environment variable management.
 """
 
 import argparse
-import os
-import pprint
 import sys
 import traceback
 
@@ -85,24 +83,26 @@ def parse_args():
         "--platform",
         default=config.PLATFORM,
         metavar="PLATFORM",
-        help="specify the platform to resolve variables for",
+        help="platform to resolve variables for (linux, darwin, windows)",
     )
     parser.add_argument(
         "-r",
         "--resolve",
+        nargs="*",
         metavar="VAR",
-        help="resolve an environment variable",
-    )
-    parser.add_argument(
-        "--sources",
-        action="store_true",
-        help="list the sources for a stack",
+        help="resolve environment variables",
     )
     parser.add_argument(
         "-t",
         "--trace",
+        nargs="*",
         metavar="VAR",
-        help="trace where a variable is getting set",
+        help="trace where environment variables are being set",
+    )
+    parser.add_argument(
+        "--sources",
+        action="store_true",
+        help="list the sources for a stack",
     )
 
     args = parser.parse_args(args_before_dash)
@@ -115,15 +115,20 @@ def main():
     args, command = parse_args()
 
     try:
-        if args.resolve:
-            env = load_environ(
-                args.namespace, environ=os.environ, platform=args.platform
-            )
-            var = env.get(args.resolve)
-            print(pprint.pformat(expandvars(var, env, recursive=True)))
-        elif args.trace:
-            path = trace_var(args.namespace, args.trace)
-            print("{0}: {1}".format(args.trace, path))
+        if args.resolve is not None:
+            if len(args.resolve) == 0:
+                args.resolve = load_environ(args.namespace).keys()
+            env = load_environ(args.namespace, platform=args.platform)
+            for resolve in args.resolve:
+                var = env.get(resolve)
+                val = expandvars(var, env, recursive=True)
+                print(f"{resolve}={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, trace)
+                print("{0}: {1}".format(trace, path))
         elif args.sources:
             sources = build_sources(args.namespace)
             for source in sources:
@@ -135,7 +140,7 @@ def main():
         else:
             env = load_environ(args.namespace, platform=args.platform, includes=True)
             for k, v in env.items():
-                print(f"{k} {pprint.pformat(v)}")
+                print(f"{k}={v}")
 
     except KeyboardInterrupt:
         print("Stopping...")

{envstack-0.4.2 → envstack-0.5.0}/lib/envstack/config.py

@@ -59,20 +59,30 @@ def detect_shell():
 
 DEBUG = os.getenv("DEBUG")
 DEFAULT_NAMESPACE = os.getenv("DEFAULT_ENV_STACK", "stack")
-LOG_LEVEL = int(os.environ.get("LOG_LEVEL", 20))
+ENV = os.getenv("ENV", "prod")
+HOME = os.getenv("HOME")
+LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO")
 ON_POSIX = "posix" in sys.builtin_module_names
 PLATFORM = platform.system().lower()
 PYTHON_VERSION = sys.version_info[0]
 SHELL = detect_shell()
 USERNAME = os.getenv("USERNAME", os.getenv("USER"))
 
-# default location of the global env stacks
-# set in sitecustomize.py using siteconf>=0.1.7
+# set some default environment variables
+DEFAULT_ENV = {
+    "ENV": ENV,
+    "HOME": HOME,
+    "PLATFORM": PLATFORM,
+    "USER": USERNAME,
+}
+
+# default location of envstack files
+# NOTE: the siteconf sitecustomize.py module may override this
 DEFAULT_ENV_DIR = os.getenv(
     "DEFAULT_ENV_DIR",
     {
-        "darwin": "/etc/envstack",
-        "linux": "/etc/envstack",
-        "windows": "C:/ProgramData/envstack",
-    }.get(PLATFORM),
+        "darwin": "{HOME}/Library/Application Support/envstack",
+        "linux": "{HOME}/.local/envstack",
+        "windows": "C:\\ProgramData\\envstack",
+    }.get(PLATFORM).format(**DEFAULT_ENV),
 )

{envstack-0.4.2 → envstack-0.5.0}/lib/envstack/env.py

@@ -260,18 +260,22 @@ class Env(dict):
         """Returns raw, unexpanded value of key, or None."""
         return self.get(key, resolved=False).template
 
-    def items(self):
-        """Returns list of (key, value) pairs, as 2-tuples."""
-        return [(k, EnvVar(self[k]).value()) for k in self]
-
     def merge(self, env):
-        """Merges another environ into this one, i.e.
-        env[k] will replace self[k].
+        """Merges another environ `env` into this one.
 
         :param env: env to merge into this one
         """
-        for k, v in env.items():
-            self[k] = v
+        merged = env.copy()
+        for key, value in self.items():
+            if isinstance(value, str):
+                # replace ${KEY} vars with values from env
+                value = re.sub(
+                    r"\${(\w+)}",
+                    lambda match: env.get(match.group(1), match.group(0)),
+                    value,
+                )
+            merged[key] = value
+        return merged
 
     def set_namespace(self, name):
         """Stores the namespace for this environment.
@@ -538,7 +542,7 @@ def init(name=config.DEFAULT_NAMESPACE):
 def load_environ(
     name=config.DEFAULT_NAMESPACE,
     sources=None,
-    environ=None,
+    environ=os.environ,
     platform=config.PLATFORM,
     scope=None,
     includes=True,
@@ -577,7 +581,7 @@ def load_environ(
     for source in sources:
         env.update(source.load(platform=platform))
 
-    # load values from local environment
+    # merge values from given environment
     if environ:
         env.merge(environ)
 
@@ -650,7 +654,7 @@ def trace_var(name, var, scope=None):
     :returns: source path
     """
     if var in os.environ:
-        return "local environment (unset to clear)"
+        return "local environment"
     sources = build_sources(name, scope=scope)
     sources.reverse()
     for source in sources:
@@ -660,6 +664,7 @@ def trace_var(name, var, scope=None):
             return source.path
 
 
+# default stack environment
 environ = load_environ(environ=os.environ)
 
 

{envstack-0.4.2 → envstack-0.5.0}/lib/envstack/logger.py

@@ -33,7 +33,17 @@ import logging
 
 from envstack.config import LOG_LEVEL
 
-log = logging.Logger("envstack")
+
+class Logger(logging.Logger):
+    """Custom logger class."""
+
+    def setLevel(self, level):
+        if isinstance(level, str):
+            level = getattr(logging, level.upper(), logging.NOTSET)
+        super().setLevel(level)
+
+
+log = Logger("envstack")
 log.setLevel(LOG_LEVEL)
 log.addHandler(logging.NullHandler())