Repository: onicagroup/runway

Issue:
update`runway.cfngin.lookups.handlers.envvar` to use the standardized query syntax
Subtask of #1184 

Discussion:
codecov[bot]: # [Codecov](https://codecov.io/gh/onicagroup/runway/pull/1299?src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup) Report
> Merging [#1299](https://codecov.io/gh/onicagroup/runway/pull/1299?src=pr&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup) (f90cc67) into [master](https://codecov.io/gh/onicagroup/runway/commit/b6410625172157f3c229df7983fb9ef541a04caf?el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup) (b641062) will **increase** coverage by `0.00%`.
> The diff coverage is `100.00%`.

> :exclamation: Current head f90cc67 differs from pull request most recent head e4ca1d1. Consider uploading reports for the commit e4ca1d1 to get more accurate results

[![Impacted file tree graph](https://codecov.io/gh/onicagroup/runway/pull/1299/graphs/tree.svg?width=650&height=150&src=pr&token=Ku28I0RY80&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup)](https://codecov.io/gh/onicagroup/runway/pull/1299?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup)

```diff
@@           Coverage Diff           @@
##           master    #1299   +/-   ##
=======================================
  Coverage   90.09%   90.09%           
=======================================
  Files         247      247           
  Lines       15369    15375    +6     
=======================================
+ Hits        13846    13852    +6     
  Misses       1523     1523           
```


| [Impacted Files](https://codecov.io/gh/onicagroup/runway/pull/1299?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup) | Coverage Δ | |
|---|---|---|
| [runway/cfngin/lookups/handlers/envvar.py](https://codecov.io/gh/onicagroup/runway/pull/1299/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup#diff-cnVud2F5L2Nmbmdpbi9sb29rdXBzL2hhbmRsZXJzL2VudnZhci5weQ==) | `100.00% <100.00%> (ø)` | |
| [runway/cfngin/lookups/registry.py](https://codecov.io/gh/onicagroup/runway/pull/1299/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup#diff-cnVud2F5L2Nmbmdpbi9sb29rdXBzL3JlZ2lzdHJ5LnB5) | `100.00% <100.00%> (ø)` | |
| [runway/lookups/handlers/env.py](https://codecov.io/gh/onicagroup/runway/pull/1299/diff?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup#diff-cnVud2F5L2xvb2t1cHMvaGFuZGxlcnMvZW52LnB5) | `100.00% <100.00%> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/onicagroup/runway/pull/1299?src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/onicagroup/runway/pull/1299?src=pr&el=footer&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup). Last update [b641062...e4ca1d1](https://codecov.io/gh/onicagroup/runway/pull/1299?src=pr&el=lastupdated&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=onicagroup).


Patch:
diff --git a/docs/source/cfngin/lookups/cfn.rst b/docs/source/cfngin/lookups/cfn.rst
index ebfb369c..c2eea260 100644
--- a/docs/source/cfngin/lookups/cfn.rst
+++ b/docs/source/cfngin/lookups/cfn.rst
@@ -9,7 +9,7 @@ cfn
   This means that it must have been deployed using another Runway module, deployed from a config that is run before the one using it, deployed manually, or deployed in the same config using :attr:`~cfngin.stack.required`/:attr:`~cfngin.stack.required_by` to specify a dependency between the Stacks.
 
 
-:Query Syntax: ``<stack-name>.<output-name>``
+:Query Syntax: ``<stack-name>.<output-name>[::<arg>=<arg-val>, ...]``
 
 
 Retrieve a value from CloudFormation Stack Outputs.
diff --git a/docs/source/cfngin/lookups/env.rst b/docs/source/cfngin/lookups/env.rst
new file mode 100644
index 00000000..e27b229a
--- /dev/null
+++ b/docs/source/cfngin/lookups/env.rst
@@ -0,0 +1,42 @@
+.. _CFNgin env lookup:
+
+###
+env
+###
+
+:Query Syntax: ``<variable-name>[::<arg>=<arg-val>, ...]``
+
+
+Retrieve a value from an environment variable.
+
+The value is retrieved from a copy of the current environment variables that is saved to the context object.
+These environment variables are manipulated at runtime by Runway to fill in additional values such as ``DEPLOY_ENVIRONMENT`` and ``AWS_REGION`` to match the current execution.
+
+If the Lookup is unable to find an environment variable matching the provided query, the default value is returned or a :exc:`ValueError` is raised if a default value was not provided.
+
+
+.. here, versionadded refers to when it was added to the CFNgin registry
+.. versionadded:: 2.7.0
+
+
+
+*********
+Arguments
+*********
+
+This Lookup supports all :ref:`Common Lookup Arguments` but, the following have limited or no effect:
+
+- region
+
+
+
+*******
+Example
+*******
+
+.. code-block:: yaml
+
+  stacks:
+    - ...
+      variables:
+        Foo: ${env bar::default=foobar}
diff --git a/docs/source/cfngin/lookups/envvar.rst b/docs/source/cfngin/lookups/envvar.rst
index 25acc525..f52c7a8f 100644
--- a/docs/source/cfngin/lookups/envvar.rst
+++ b/docs/source/cfngin/lookups/envvar.rst
@@ -2,6 +2,10 @@
 envvar
 ######
 
+.. deprecated:: 2.7.0
+  Replaced by :ref:`CFNgin env lookup`
+
+
 :Query Syntax: ``<variable-name>``
 
 
diff --git a/docs/source/cfngin/lookups/hook_data.rst b/docs/source/cfngin/lookups/hook_data.rst
index 92ab1d14..234965a7 100644
--- a/docs/source/cfngin/lookups/hook_data.rst
+++ b/docs/source/cfngin/lookups/hook_data.rst
@@ -4,7 +4,7 @@
 hook_data
 #########
 
-:Query Syntax: ``<hook.data_key>``
+:Query Syntax: ``<hook.data_key>[::<arg>=<arg-val>, ...]``
 
 
 When using hooks, you can have the hook store results in the :attr:`CfnginContext.hook_data <runway.context.CfnginContext.hook_data>` dictionary on the context by setting :attr:`~cfngin.hook.data_key` in the :class:`~cfngin.hook` config.
diff --git a/docs/source/cfngin/lookups/ssm.rst b/docs/source/cfngin/lookups/ssm.rst
index f8c2190f..428c856a 100644
--- a/docs/source/cfngin/lookups/ssm.rst
+++ b/docs/source/cfngin/lookups/ssm.rst
@@ -2,7 +2,7 @@
 ssm
 ###
 
-:Query Syntax: ``<parameter>``
+:Query Syntax: ``<parameter>[::<arg>=<arg-val>, ...]``
 
 
 Retrieve a value from SSM Parameter Store.
@@ -24,7 +24,12 @@ Arguments
 
 This Lookup supports all :ref:`Common Lookup Arguments`.
 
-.. rubric:: Example
+
+
+*******
+Example
+*******
+
 .. code-block:: yaml
 
   stacks:
diff --git a/docs/source/lookups/cfn.rst b/docs/source/lookups/cfn.rst
index c7c5debe..99e09acd 100644
--- a/docs/source/lookups/cfn.rst
+++ b/docs/source/lookups/cfn.rst
@@ -10,7 +10,7 @@ cfn
   This means that the Stack must have been deployed by another module, run before the one using this Lookup, or it must have been created external to Runway.
 
 
-:Query Syntax: ``<stack-name>.<output-name>``
+:Query Syntax: ``<stack-name>.<output-name>[::<arg>=<arg-val>, ...]``
 
 
 Retrieve a value from CloudFormation Stack Outputs.
diff --git a/docs/source/lookups/env.rst b/docs/source/lookups/env.rst
index 71401f66..0f7869bf 100644
--- a/docs/source/lookups/env.rst
+++ b/docs/source/lookups/env.rst
@@ -5,7 +5,7 @@
 env
 ###
 
-:Query Syntax: ``<variable-name>``
+:Query Syntax: ``<variable-name>[::<arg>=<arg-val>, ...]``
 
 
 Retrieve a value from an environment variable.
diff --git a/docs/source/lookups/index.rst b/docs/source/lookups/index.rst
index 82695d9e..c0e13c74 100644
--- a/docs/source/lookups/index.rst
+++ b/docs/source/lookups/index.rst
@@ -7,7 +7,7 @@ Lookups
 Runway Lookups allow the use of variables within the Runway config file.
 These variables can then be passed along to :ref:`deployments <runway-deployment>`, :ref:`modules <runway-module>` and :ref:`tests <runway-test>`.
 
-The syntax for a lookup is ``${<lookup-name> <query>::<arg-key>=<arg-value>}``.
+The syntax for a lookup is ``${<lookup-name> <query>::<arg>=<arg-val>}``.
 
 +---------------------------+-------------------------------------------------+
 | Component                 | Description                                     |
@@ -31,7 +31,7 @@ The syntax for a lookup is ``${<lookup-name> <query>::<arg-key>=<arg-value>}``.
 | ``::``                    | The separator between a query and optional      |
 |                           | arguments.                                      |
 +---------------------------+-------------------------------------------------+
-| ``<arg-key>=<arg-value>`` || An argument passed to a lookup.                |
+| ``<arg>=<arg-val>``       || An argument passed to a lookup.                |
 |                           || Multiple arguments can be passed to a lookup   |
 |                           |  by separating them with a                      |
 |                           || comma (``,``).                                 |
diff --git a/docs/source/lookups/random.string.rst b/docs/source/lookups/random.string.rst
index 740f4cf0..5acdfcae 100644
--- a/docs/source/lookups/random.string.rst
+++ b/docs/source/lookups/random.string.rst
@@ -4,7 +4,7 @@
 random.string
 #############
 
-:Query Syntax: ``<desired-length>``
+:Query Syntax: ``<desired-length>[::<arg>=<arg-val>, ...]``
 
 
 Generate a random string of the given length.
diff --git a/docs/source/lookups/ssm.rst b/docs/source/lookups/ssm.rst
index c6dde03d..d9ae8af0 100644
--- a/docs/source/lookups/ssm.rst
+++ b/docs/source/lookups/ssm.rst
@@ -5,7 +5,7 @@
 ssm
 ###
 
-:Query Syntax: ``<parameter>``
+:Query Syntax: ``<parameter>[::<arg>=<arg-val>, ...]``
 
 
 Retrieve a value from SSM Parameter Store.
@@ -27,7 +27,12 @@ Arguments
 
 This Lookup supports all :ref:`Common Lookup Arguments`.
 
-.. rubric:: Example
+
+
+*******
+Example
+*******
+
 .. code-block:: yaml
 
   deployment:
diff --git a/docs/source/lookups/var.rst b/docs/source/lookups/var.rst
index 65c34c30..7afb2ae9 100644
--- a/docs/source/lookups/var.rst
+++ b/docs/source/lookups/var.rst
@@ -5,7 +5,7 @@
 var
 ###
 
-:Query Syntax: ``<variable-name>``
+:Query Syntax: ``<variable-name>[::<arg>=<arg-val>, ...]``
 
 
 Retrieve a variable from the variables file or definition.
diff --git a/runway/cfngin/lookups/handlers/envvar.py b/runway/cfngin/lookups/handlers/envvar.py
index 3cb9b704..f0be6f7e 100644
--- a/runway/cfngin/lookups/handlers/envvar.py
+++ b/runway/cfngin/lookups/handlers/envvar.py
@@ -1,5 +1,6 @@
 """Environment variable lookup."""
 # pyright: reportIncompatibleMethodOverride=none
+import logging
 import os
 from typing import Any
 
@@ -8,10 +9,13 @@ from typing_extensions import Final, Literal
 from ....lookups.handlers.base import LookupHandler
 from ...utils import read_value_from_path
 
+LOGGER = logging.getLogger(__name__)
+
 
 class EnvvarLookup(LookupHandler):
     """Environment variable lookup."""
 
+    DEPRECATION_MSG = "envvar Lookup has been deprecated; use the env lookup instead"
     TYPE_NAME: Final[Literal["envvar"]] = "envvar"
     """Name that the Lookup is registered as."""
 
@@ -42,6 +46,7 @@ class EnvvarLookup(LookupHandler):
                 conf_key: ENV_VALUE
 
         """
+        LOGGER.warning("${envvar %s}: %s: ${env %s}", value, cls.DEPRECATION_MSG, value)
         value = read_value_from_path(value)
 
         try:
diff --git a/runway/cfngin/lookups/registry.py b/runway/cfngin/lookups/registry.py
index fac21b0b..913c28f2 100644
--- a/runway/cfngin/lookups/registry.py
+++ b/runway/cfngin/lookups/registry.py
@@ -7,6 +7,7 @@ from typing import Dict, Type, Union, cast
 from ...lookups.handlers.base import LookupHandler
 from ...lookups.handlers.cfn import CfnLookup
 from ...lookups.handlers.ecr import EcrLookup
+from ...lookups.handlers.env import EnvLookup
 from ...lookups.handlers.random_string import RandomStringLookup
 from ...lookups.handlers.ssm import SsmLookup
 from ...utils import DOC_SITE, load_object_from_string
@@ -104,6 +105,7 @@ register_lookup_handler(CfnLookup.TYPE_NAME, CfnLookup)
 register_lookup_handler(DefaultLookup.TYPE_NAME, DefaultLookup)
 register_lookup_handler(DynamodbLookup.TYPE_NAME, DynamodbLookup)
 register_lookup_handler(EcrLookup.TYPE_NAME, EcrLookup)
+register_lookup_handler(EnvLookup.TYPE_NAME, EnvLookup)
 register_lookup_handler(EnvvarLookup.TYPE_NAME, EnvvarLookup)
 register_lookup_handler(FileLookup.TYPE_NAME, FileLookup)
 register_lookup_handler(HookDataLookup.TYPE_NAME, HookDataLookup)
diff --git a/runway/lookups/handlers/env.py b/runway/lookups/handlers/env.py
index 4f6b975f..4f2b6d7e 100644
--- a/runway/lookups/handlers/env.py
+++ b/runway/lookups/handlers/env.py
@@ -2,14 +2,14 @@
 # pyright: reportIncompatibleMethodOverride=none
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Union
 
 from typing_extensions import Final, Literal
 
 from .base import LookupHandler
 
 if TYPE_CHECKING:
-    from ...context import RunwayContext
+    from ...context import CfnginContext, RunwayContext
 
 
 class EnvLookup(LookupHandler):
@@ -20,7 +20,11 @@ class EnvLookup(LookupHandler):
 
     @classmethod
     def handle(  # pylint: disable=arguments-differ
-        cls, value: str, context: RunwayContext, *__args: Any, **__kwargs: Any
+        cls,
+        value: str,
+        context: Union[CfnginContext, RunwayContext],
+        *__args: Any,
+        **__kwargs: Any,
     ) -> Any:
         """Retrieve an environment variable.
 


Test patch:
diff --git a/tests/unit/cfngin/lookups/test_registry.py b/tests/unit/cfngin/lookups/test_registry.py
index accad245..64b45675 100644
--- a/tests/unit/cfngin/lookups/test_registry.py
+++ b/tests/unit/cfngin/lookups/test_registry.py
@@ -37,6 +37,7 @@ def test_autoloaded_lookup_handlers(mocker: MockerFixture) -> None:
         "default",
         "dynamodb",
         "ecr",
+        "env",
         "envvar",
         "file",
         "hook_data",