Feature/add choice parameter and raise an exception if fetched value is not within (#555)

* set new parameter in str to coerce value into a specific list of choices. Raise improperlyConfigured if the value is not within choices.

* Fix indentation after rebase in Env.str

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Document Env.str choices option

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Daniele Faraglia <joke2k@users.noreply.github.com>
Co-authored-by: joke2k <daniele.faraglia@gmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

docs/tips.rst

@@ -287,6 +287,29 @@ The following example demonstrates the above:
    print(env.str('ESCAPED_CERT', multiline=False))
    # ---BEGIN---\\n---END---
 
+Restrict string values with choices
+===================================
+
+You can restrict ``env.str()`` to an allowed list of values using
+``choices``. If the value is not in the provided list,
+``ImproperlyConfigured`` is raised.
+
+.. code-block:: python
+
+   import environ
+   from django.core.exceptions import ImproperlyConfigured
+
+   env = environ.Env()
+
+   # APP_ENV=prod
+   env.str("APP_ENV", choices=("dev", "prod", "staging"))  # "prod"
+
+   # APP_ENV=unknown
+   try:
+       env.str("APP_ENV", choices=("dev", "prod", "staging"))
+   except ImproperlyConfigured:
+       ...
+
 Proxy value
 ===========
 

environ/environ.py

@@ -237,13 +237,20 @@ def str(
             self,
             var,
             default: Union[str, NoValue] = NOTSET,
-            multiline=False) -> str:
+            multiline=False,
+            choices=NOTSET) -> str:
         """
         :rtype: str
         """
         value = self.get_value(var, cast=str, default=default)
         if multiline:
             return re.sub(r'(\\r)?\\n', r'\n', value)
+        if choices is not self.NOTSET:
+            # if choices is provided, check that the value is in choices
+            if value not in choices:
+                raise ImproperlyConfigured(
+                    f"Invalid value: {value} not in {choices}"
+                )
         return value
 
     def bytes(

tests/test_env.py

@@ -115,22 +115,31 @@ def test_contains(self):
         assert 'I_AM_NOT_A_VAR' not in self.env
 
     @pytest.mark.parametrize(
-        'var,val,multiline',
+        'var,val,multiline,choices',
         [
-            ('STR_VAR', 'bar', False),
-            ('MULTILINE_STR_VAR', 'foo\\nbar', False),
-            ('MULTILINE_STR_VAR', 'foo\nbar', True),
-            ('MULTILINE_QUOTED_STR_VAR', '---BEGIN---\\r\\n---END---', False),
-            ('MULTILINE_QUOTED_STR_VAR', '---BEGIN---\n---END---', True),
-            ('MULTILINE_ESCAPED_STR_VAR', '---BEGIN---\\\\n---END---', False),
-            ('MULTILINE_ESCAPED_STR_VAR', '---BEGIN---\\\n---END---', True),
+            ('STR_VAR', 'bar', False, Env.NOTSET),
+            ('STR_VAR', 'bar', False, ['foo', 'bar']),
+            ('STR_VAR', 'bar', False, ['pow', 'foo']),
+            ('MULTILINE_STR_VAR', 'foo\\nbar', False, Env.NOTSET),
+            ('MULTILINE_STR_VAR', 'foo\\nbar', False, ['foo\\nbar', '***']),
+            ('MULTILINE_STR_VAR', 'foo\\nbar', False, ['***', '***']),
+            ('MULTILINE_STR_VAR', 'foo\nbar', True, Env.NOTSET),
+            ('MULTILINE_QUOTED_STR_VAR', '---BEGIN---\\r\\n---END---', False, Env.NOTSET),
+            ('MULTILINE_QUOTED_STR_VAR', '---BEGIN---\n---END---', True, Env.NOTSET),
+            ('MULTILINE_ESCAPED_STR_VAR', '---BEGIN---\\\\n---END---', False, Env.NOTSET),
+            ('MULTILINE_ESCAPED_STR_VAR', '---BEGIN---\\\n---END---', True, Env.NOTSET),
         ],
     )
-    def test_str(self, var, val, multiline):
-        assert isinstance(self.env(var), str)
-        if not multiline:
-            assert self.env(var) == val
-        assert self.env.str(var, multiline=multiline) == val
+    def test_str(self, var, val, multiline, choices):
+        if choices is Env.NOTSET or val in choices:
+            assert isinstance(self.env(var), str)
+            if not multiline:
+                assert self.env(var) == val
+            assert self.env.str(var, multiline=multiline) == val
+        else:
+            with pytest.raises(ImproperlyConfigured) as excinfo:
+                self.env.str(var, multiline=multiline, choices=choices)
+            assert str(excinfo.value) == f"Invalid value: {val} not in {choices}"
 
     @pytest.mark.parametrize(
         'var,val,default',