improve exception handling for _extract_and_validate_wildcards

Author: daniel-sanche

packages/google-api-core/google/api_core/path_template.py

@@ -63,6 +63,10 @@
 _MULTI_SEGMENT_PATTERN = r"(.+)"
 
 
+class _PathValidationFailed(Exception):
+    """Internal exception used when an invalid path is encountered."""
+
+
 def _validate_multi_segment_value(val: str) -> bool:
     """Validate a multi-segment wildcard value.
 
@@ -209,39 +213,40 @@ def _extract_and_validate_wildcards(
     Raises:
         ValueError: If a wildcard within a structurally valid value violates path traversal rules.
     """
-    err = ValueError(
-        f"Invalid value {val} for {property_name or 'positional variable'}."
-    )
-
-    if template_str is None or template_str == "*":
-        # Single-segment templates (None or "*") cannot match exactly "." or ".."
-        # and cannot have multi-segment paths resolving to 0 segments.
-        #
-        # Empty strings pose no traversal security risk here.
-        if val and not _validate_multi_segment_value(val):
-            raise err
-    elif template_str == "**":
-        # Multi-segment templates ("**") must represent at least one valid,
-        # non-escaped segment.
-        if not _validate_multi_segment_value(val):
-            raise err
-    else:
-        # Compile the sub-template into a regex capture pattern
-        # to isolate and validate individual wildcard values.
-        pattern, wildcard_types = _build_capture_pattern(template_str)
-
-        m = pattern.fullmatch(val)
-        if m is not None:
-            # Validate each wildcard value within its matched boundaries,
-            # preventing traversals from escaping their structural positions.
-            for captured_val in m.groups():
-                if not _validate_multi_segment_value(captured_val):
-                    raise err
-        else:
-            # For values that don't match the pattern, ensure the value doesn't
-            # resolve to 0 segments (e.g. "projects/..").
+    try:
+        if template_str is None or template_str == "*":
+            # Single-segment templates (None or "*") cannot match exactly "." or ".."
+            # and cannot have multi-segment paths resolving to 0 segments.
+            #
+            # Empty strings pose no traversal security risk here.
             if val and not _validate_multi_segment_value(val):
-                raise err
+                raise _PathValidationFailed()
+        elif template_str == "**":
+            # Multi-segment templates ("**") must represent at least one valid,
+            # non-escaped segment.
+            if not _validate_multi_segment_value(val):
+                raise _PathValidationFailed()
+        else:
+            # Compile the sub-template into a regex capture pattern
+            # to isolate and validate individual wildcard values.
+            pattern, wildcard_types = _build_capture_pattern(template_str)
+
+            m = pattern.fullmatch(val)
+            if m is not None:
+                # Validate each wildcard value within its matched boundaries,
+                # preventing traversals from escaping their structural positions.
+                for captured_val in m.groups():
+                    if not _validate_multi_segment_value(captured_val):
+                        raise _PathValidationFailed()
+            else:
+                # For values that don't match the pattern, ensure the value doesn't
+                # resolve to 0 segments (e.g. "projects/..").
+                if val and not _validate_multi_segment_value(val):
+                    raise _PathValidationFailed()
+    except _PathValidationFailed:
+        raise ValueError(
+            f"Invalid value {val} for {property_name or 'positional variable'}."
+        )
 
 
 def _expand_variable_match(positional_vars, named_vars, match):