Enhance version_path_separator behaviour by adding a newline option

### Description
version_path_separator now consists a new option "newline" which allows you to specify multiple version locations across multiple lines like this:
```
version_locations =
  /foo/versions
  /bar/versions
  /baz/versions

version_path_separator = newline
```

### Checklist
This pull request is:

- [ ] A documentation / typographical error fix
	- Good to go, no issue or tests are needed
- [ ] A short code fix
	- please include the issue number, and create an issue if none exists, which
	  must include a complete example of the issue.  one line code fixes without an
	  issue and demonstration will not be accepted.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.   one line code fixes without tests will not be accepted.
- [x] A new feature implementation
	- please include the issue number, and create an issue if none exists, which must
	  include a complete example of how the feature would look.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.

**Have a nice day!**

Closes: #1510
Pull-request: #1510
Pull-request-sha: 6155da7

Change-Id: I364906906a9c7164e8f7fa5f51f3097ab118cc65

alembic/script/base.py

@@ -187,6 +187,7 @@ def from_config(cls, config: Config) -> ScriptDirectory:
             split_on_path = {
                 None: None,
                 "space": " ",
+                "newline": "\n",
                 "os": os.pathsep,
                 ":": ":",
                 ";": ";",
@@ -200,7 +201,8 @@ def from_config(cls, config: Config) -> ScriptDirectory:
                 raise ValueError(
                     "'%s' is not a valid value for "
                     "version_path_separator; "
-                    "expected 'space', 'os', ':', ';'" % version_path_separator
+                    "expected 'space', 'newline', 'os', ':', ';'"
+                    % version_path_separator
                 ) from ke
             else:
                 if split_char is None:
@@ -210,7 +212,9 @@ def from_config(cls, config: Config) -> ScriptDirectory:
                     )
                 else:
                     version_locations = [
-                        x for x in version_locations_str.split(split_char) if x
+                        x.strip()
+                        for x in version_locations_str.split(split_char)
+                        if x
                     ]
         else:
             version_locations = None

alembic/templates/async/alembic.ini.mako

@@ -47,6 +47,7 @@ prepend_sys_path = .
 # version_path_separator = :
 # version_path_separator = ;
 # version_path_separator = space
+# version_path_separator = newline
 version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
 # set to 'true' to search source files recursively

alembic/templates/generic/alembic.ini.mako

@@ -49,6 +49,7 @@ prepend_sys_path = .
 # version_path_separator = :
 # version_path_separator = ;
 # version_path_separator = space
+# version_path_separator = newline
 version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
 # set to 'true' to search source files recursively

alembic/templates/multidb/alembic.ini.mako

@@ -49,6 +49,7 @@ prepend_sys_path = .
 # version_path_separator = :
 # version_path_separator = ;
 # version_path_separator = space
+# version_path_separator = newline
 version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
 # set to 'true' to search source files recursively

alembic/testing/assertions.py

@@ -74,7 +74,9 @@ class _ErrorContainer:
 
 
 @contextlib.contextmanager
-def _expect_raises(except_cls, msg=None, check_context=False):
+def _expect_raises(
+    except_cls, msg=None, check_context=False, text_exact=False
+):
     ec = _ErrorContainer()
     if check_context:
         are_we_already_in_a_traceback = sys.exc_info()[0]
@@ -85,7 +87,10 @@ def _expect_raises(except_cls, msg=None, check_context=False):
         ec.error = err
         success = True
         if msg is not None:
-            assert re.search(msg, str(err), re.UNICODE), f"{msg} !~ {err}"
+            if text_exact:
+                assert str(err) == msg, f"{msg} != {err}"
+            else:
+                assert re.search(msg, str(err), re.UNICODE), f"{msg} !~ {err}"
         if check_context and not are_we_already_in_a_traceback:
             _assert_proper_exception_context(err)
         print(str(err).encode("utf-8"))
@@ -98,8 +103,12 @@ def expect_raises(except_cls, check_context=True):
     return _expect_raises(except_cls, check_context=check_context)
 
 
-def expect_raises_message(except_cls, msg, check_context=True):
-    return _expect_raises(except_cls, msg=msg, check_context=check_context)
+def expect_raises_message(
+    except_cls, msg, check_context=True, text_exact=False
+):
+    return _expect_raises(
+        except_cls, msg=msg, check_context=check_context, text_exact=text_exact
+    )
 
 
 def eq_ignore_whitespace(a, b, msg=None):

docs/build/tutorial.rst

@@ -174,6 +174,7 @@ The file generated with the "generic" configuration looks like::
     # version_path_separator = :
     # version_path_separator = ;
     # version_path_separator = space
+    # version_path_separator = newline
     version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
     # set to 'true' to search source files recursively

docs/build/unreleased/1509.rst

@@ -0,0 +1,5 @@
+.. change::
+    :tags: feature, environment
+    :tickets: 1509
+
+    Enhance ``version_locations`` parsing to handle paths containing newlines.

tests/test_config.py

@@ -134,6 +134,12 @@ def test_attributes_constructor(self):
             "/foo /bar",
             ["/foo", "/bar"],
         ),
+        (
+            "multiline string 1",
+            "newline",
+            " /foo  \n/bar  ",
+            ["/foo", "/bar"],
+        ),
         (
             "Linux pathsep 1",
             ":",
@@ -171,7 +177,7 @@ def test_attributes_constructor(self):
             "/foo|/bar",
             ValueError(
                 "'|' is not a valid value for version_path_separator; "
-                "expected 'space', 'os', ':', ';'"
+                "expected 'space', 'newline', 'os', ':', ';'"
             ),
         ),
         id_="iaaa",
@@ -188,7 +194,8 @@ def test_version_locations(self, separator, string_value, expected_result):
         cfg.set_main_option("version_locations", string_value)
 
         if isinstance(expected_result, ValueError):
-            with expect_raises_message(ValueError, expected_result.args[0]):
+            message = str(expected_result)
+            with expect_raises_message(ValueError, message, text_exact=True):
                 ScriptDirectory.from_config(cfg)
         else:
             s = ScriptDirectory.from_config(cfg)