⚡️ Speed up method Route.matches by 13%

[codeflash-ai]

📄 13% (0.13x) speedup for Route.matches in starlette/routing.py

⏱️ Runtime : 328 microseconds → 290 microseconds (best of 74 runs)

📝 Explanation and details

The optimization achieves a 12% speedup by eliminating the expensive get_route_path function call in the hot path and optimizing dictionary operations in the matches method.

Key optimizations:

1. Inlined route path extraction: Instead of always calling get_route_path(), the code directly extracts path from scope and only falls back to the function when necessary (when path is None or root_path exists). This eliminates ~52% of the original runtime spent on the function call.

2. Optimized path_params handling: Rather than always creating a new dictionary with dict(scope.get("path_params", {})), the code now only creates a copy when path_params already exists in scope. When no existing path_params are present, it directly assigns matched_params, avoiding unnecessary dictionary creation and update operations.

3. Improved methods set construction: In __init__, replaced set comprehension {method.upper() for method in methods} with explicit loop-based construction, which is slightly more efficient for small collections.

The optimizations are particularly effective for:

• Simple routes without root_path (15-20% faster): Direct path access avoids function call overhead
• Routes with multiple parameters (17-19% faster): Reduced dictionary operations compound the savings
• Routes without existing path_params (most common case): Avoids unnecessary dict() calls

The performance gains are consistent across different route patterns, with the largest improvements seen in parameter-heavy routes where both optimizations provide cumulative benefits.

✅ Correctness verification report:

Test	Status
⚙️ Existing Unit Tests	🔘 None Found
🌀 Generated Regression Tests	✅ 332 Passed
⏪ Replay Tests	🔘 None Found
🔎 Concolic Coverage Tests	🔘 None Found
📊 Tests Coverage	100.0%

🌀 Generated Regression Tests and Runtime

import re
from typing import Any

# imports
import pytest
from starlette.routing import Route

# Function to test (matches method from Route class)
# For testing, we need to define minimal stubs for:
# - Scope dict
# - Match enum
# - Convertor classes
# - Route class (with only what's needed for matches)
# - CONVERTOR_TYPES
# - get_route_path
# We'll define only what's necessary for the tests.


class Match:
    FULL = "full"
    PARTIAL = "partial"
    NONE = "none"

# Minimal convertor classes
class StringConvertor:
    regex = "[^/]+"
    def convert(self, value): return value

class IntConvertor:
    regex = "[0-9]+"
    def convert(self, value): return int(value)

class PathConvertor:
    regex = ".*"
    def convert(self, value): return value

CONVERTOR_TYPES = {
    "str": StringConvertor(),
    "int": IntConvertor(),
    "path": PathConvertor(),
}

PARAM_REGEX = re.compile("{([a-zA-Z_][a-zA-Z0-9_]*)(:[a-zA-Z_][a-zA-Z0-9_]*)?}")

def compile_path(path: str):
    is_host = not path.startswith("/")
    path_regex = "^"
    path_format = ""
    duplicated_params = set()
    idx = 0
    param_convertors = {}
    for match in PARAM_REGEX.finditer(path):
        param_name, convertor_type = match.groups("str")
        convertor_type = convertor_type.lstrip(":")
        convertor = CONVERTOR_TYPES[convertor_type]
        path_regex += re.escape(path[idx : match.start()])
        path_regex += f"(?P<{param_name}>{convertor.regex})"
        path_format += path[idx : match.start()]
        path_format += "{%s}" % param_name
        if param_name in param_convertors:
            duplicated_params.add(param_name)
        param_convertors[param_name] = convertor
        idx = match.end()
    if duplicated_params:
        names = ", ".join(sorted(duplicated_params))
        ending = "s" if len(duplicated_params) > 1 else ""
        raise ValueError(f"Duplicated param name{ending} {names} at path {path}")
    if is_host:
        hostname = path[idx:].split(":")[0]
        path_regex += re.escape(hostname) + "$"
    else:
        path_regex += re.escape(path[idx:]) + "$"
    path_format += path[idx:]
    return re.compile(path_regex), path_format, param_convertors
from starlette.routing import Route

# ---- UNIT TESTS ----

# Basic Test Cases

def test_exact_path_match():
    # Route with exact path, method GET
    route = Route("/home", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/home", "method": "GET"}
    match, child_scope = route.matches(scope) # 3.59μs -> 3.21μs (11.9% faster)

def test_path_with_param_str():
    # Route with string param
    route = Route("/user/{username:str}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/user/alice", "method": "GET"}
    match, child_scope = route.matches(scope) # 3.78μs -> 3.28μs (15.2% faster)

def test_path_with_param_int():
    # Route with int param
    route = Route("/item/{id:int}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/item/42", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.00μs -> 3.45μs (15.9% faster)

def test_path_with_multiple_params():
    # Route with multiple params
    route = Route("/shop/{shop_id:int}/product/{product_id:str}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/shop/7/product/widget", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.47μs -> 3.75μs (19.1% faster)

def test_head_method_included_with_get():
    # Route with GET, HEAD should also match
    route = Route("/status", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/status", "method": "HEAD"}
    match, child_scope = route.matches(scope) # 2.87μs -> 2.48μs (15.7% faster)

def test_partial_match_wrong_method():
    # Route with POST, request with GET
    route = Route("/submit", "endpoint", methods=["POST"])
    scope = {"type": "http", "path": "/submit", "method": "GET"}
    match, child_scope = route.matches(scope) # 2.84μs -> 2.35μs (20.9% faster)

def test_none_match_wrong_path():
    # Route with /foo, request to /bar
    route = Route("/foo", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/bar", "method": "GET"}
    match, child_scope = route.matches(scope) # 1.65μs -> 1.65μs (0.182% faster)

def test_none_match_wrong_type():
    # Route with /foo, non-http scope
    route = Route("/foo", "endpoint", methods=["GET"])
    scope = {"type": "websocket", "path": "/foo", "method": "GET"}
    match, child_scope = route.matches(scope) # 680ns -> 793ns (14.2% slower)

# Edge Test Cases

def test_path_with_path_convertor():
    # Route with path convertor (greedy)
    route = Route("/files/{filepath:path}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/files/a/b/c.txt", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.09μs -> 3.50μs (17.0% faster)

def test_path_with_existing_path_params():
    # Route with param, existing path_params in scope
    route = Route("/hello/{name:str}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/hello/world", "method": "GET", "path_params": {"foo": "bar"}}
    match, child_scope = route.matches(scope) # 3.65μs -> 3.50μs (4.29% faster)

def test_duplicate_param_name_raises():
    # Route with duplicate param names should raise ValueError
    with pytest.raises(ValueError):
        Route("/foo/{id:int}/bar/{id:str}", "endpoint", methods=["GET"])

def test_unknown_convertor_type_raises():
    # Route with unknown convertor type should raise AssertionError
    with pytest.raises(AssertionError):
        Route("/foo/{id:unknown}", "endpoint", methods=["GET"])

def test_partial_match_with_multiple_methods():
    # Route with multiple methods, request with non-listed method
    route = Route("/multi", "endpoint", methods=["GET", "POST"])
    scope = {"type": "http", "path": "/multi", "method": "DELETE"}
    match, child_scope = route.matches(scope) # 3.21μs -> 2.76μs (16.5% faster)

def test_param_type_conversion_failure():
    # Route with int param, but path value is not int
    route = Route("/num/{id:int}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/num/abc", "method": "GET"}
    match, child_scope = route.matches(scope) # 1.72μs -> 1.66μs (3.56% faster)

def test_path_with_trailing_slash():
    # Route with trailing slash, should match only if path matches exactly
    route = Route("/trailing/", "endpoint", methods=["GET"])
    scope1 = {"type": "http", "path": "/trailing/", "method": "GET"}
    scope2 = {"type": "http", "path": "/trailing", "method": "GET"}
    match1, _ = route.matches(scope1) # 2.92μs -> 2.61μs (12.0% faster)
    match2, _ = route.matches(scope2) # 948ns -> 947ns (0.106% faster)

def test_path_with_leading_slash():
    # Route must start with slash, path must match
    route = Route("/lead", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "lead", "method": "GET"}
    match, child_scope = route.matches(scope) # 1.54μs -> 1.49μs (3.70% faster)

def test_path_with_no_methods():
    # Route with no methods specified (should match any method)
    route = Route("/any", "endpoint")
    scope = {"type": "http", "path": "/any", "method": "PUT"}
    match, child_scope = route.matches(scope) # 2.66μs -> 2.32μs (14.8% faster)

def test_path_with_underscore_param():
    # Route with param containing underscore
    route = Route("/foo/{bar_baz:str}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": "/foo/hello_world", "method": "GET"}
    match, child_scope = route.matches(scope) # 3.63μs -> 3.19μs (13.8% faster)

# Large Scale Test Cases


def test_long_path_param():
    # Path param with long value
    long_value = "a" * 500
    route = Route("/long/{val:str}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": f"/long/{long_value}", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.60μs -> 4.05μs (13.7% faster)

def test_many_methods():
    # Route with many methods, test all match
    methods = [f"METHOD{i}" for i in range(50)]
    route = Route("/multi", "endpoint", methods=methods)
    for method in methods:
        scope = {"type": "http", "path": "/multi", "method": method}
        match, child_scope = route.matches(scope) # 42.1μs -> 35.9μs (17.1% faster)
    # Non-listed method
    scope = {"type": "http", "path": "/multi", "method": "FOO"}
    match, child_scope = route.matches(scope) # 1.27μs -> 1.12μs (13.5% faster)

def test_many_params_in_path():
    # Route with many params
    path = "/foo" + "".join([f"/{{p{i}:int}}" for i in range(20)])
    route = Route(path, "endpoint", methods=["GET"])
    test_path = "/foo" + "".join([f"/{i}" for i in range(20)])
    scope = {"type": "http", "path": test_path, "method": "GET"}
    match, child_scope = route.matches(scope) # 9.95μs -> 9.04μs (10.0% faster)
    for i in range(20):
        pass

def test_path_param_max_length():
    # Path param with max allowed length (999 chars)
    long_value = "x" * 999
    route = Route("/maxlen/{val:str}", "endpoint", methods=["GET"])
    scope = {"type": "http", "path": f"/maxlen/{long_value}", "method": "GET"}
    match, child_scope = route.matches(scope) # 3.96μs -> 3.54μs (11.8% faster)
# codeflash_output is used to check that the output of the original code is the same as that of the optimized code.
#------------------------------------------------
import re
from typing import Any, Callable

# imports
import pytest  # used for our unit tests
from starlette.routing import Route

# Function to test (matches method is inside Route)
# For testing, we need to define minimal stubs for dependencies and Route itself.
# We'll define only what's necessary for testing Route.matches.


# Minimal stub for Match enum
class Match:
    FULL = "full"
    PARTIAL = "partial"
    NONE = "none"

# Minimal stub for Convertor
class Convertor:
    def __init__(self, regex, convert):
        self.regex = regex
        self._convert = convert

    def convert(self, value):
        return self._convert(value)

# Minimal convertor types
CONVERTOR_TYPES = {
    "str": Convertor("[^/]+", str),
    "int": Convertor("[0-9]+", int),
    "float": Convertor("[0-9]+(?:\\.[0-9]+)?", float),
    "path": Convertor(".+", str),
}
from starlette.routing import Route


# Dummy endpoint for routing
def dummy_endpoint(request=None):
    return "response"

# -------------------------
# Unit Tests for matches()
# -------------------------

# 1. BASIC TEST CASES

def test_basic_static_path_match():
    # Matching a static path
    route = Route("/home", dummy_endpoint)
    scope = {"type": "http", "path": "/home", "method": "GET"}
    match, child_scope = route.matches(scope) # 3.33μs -> 2.85μs (16.6% faster)

def test_basic_static_path_no_match():
    # Not matching a static path
    route = Route("/about", dummy_endpoint)
    scope = {"type": "http", "path": "/contact", "method": "GET"}
    match, child_scope = route.matches(scope) # 1.79μs -> 1.78μs (0.787% faster)

def test_basic_dynamic_path_match():
    # Matching a dynamic path with a string parameter
    route = Route("/user/{username}", dummy_endpoint)
    scope = {"type": "http", "path": "/user/alice", "method": "GET"}
    match, child_scope = route.matches(scope) # 3.73μs -> 3.17μs (17.5% faster)

def test_basic_dynamic_path_int_convertor():
    # Matching a dynamic path with int convertor
    route = Route("/item/{id:int}", dummy_endpoint)
    scope = {"type": "http", "path": "/item/123", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.17μs -> 3.49μs (19.4% faster)

def test_basic_method_partial_match():
    # Matching path, but method not allowed
    route = Route("/api", dummy_endpoint, methods=["POST"])
    scope = {"type": "http", "path": "/api", "method": "GET"}
    match, child_scope = route.matches(scope) # 2.90μs -> 2.54μs (13.9% faster)

def test_basic_method_full_match():
    # Matching path and method
    route = Route("/api", dummy_endpoint, methods=["POST"])
    scope = {"type": "http", "path": "/api", "method": "POST"}
    match, child_scope = route.matches(scope) # 2.90μs -> 2.52μs (15.3% faster)

def test_basic_head_method_addition():
    # GET method should also allow HEAD
    route = Route("/api", dummy_endpoint, methods=["GET"])
    scope = {"type": "http", "path": "/api", "method": "HEAD"}
    match, child_scope = route.matches(scope) # 2.86μs -> 2.46μs (16.0% faster)

# 2. EDGE TEST CASES

def test_edge_empty_path():
    # Path is empty string (should not match)
    route = Route("/empty", dummy_endpoint)
    scope = {"type": "http", "path": "", "method": "GET"}
    match, child_scope = route.matches(scope) # 1.68μs -> 1.62μs (3.33% faster)

def test_edge_path_with_extra_slash():
    # Path with extra trailing slash
    route = Route("/docs", dummy_endpoint)
    scope = {"type": "http", "path": "/docs/", "method": "GET"}
    match, child_scope = route.matches(scope) # 1.77μs -> 1.77μs (0.396% faster)

def test_edge_dynamic_path_with_multiple_params():
    # Path with multiple dynamic parameters
    route = Route("/user/{username}/post/{post_id:int}", dummy_endpoint)
    scope = {"type": "http", "path": "/user/bob/post/42", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.72μs -> 4.01μs (17.6% faster)

def test_edge_dynamic_path_wrong_type():
    # Dynamic path with wrong type for int convertor
    route = Route("/item/{id:int}", dummy_endpoint)
    scope = {"type": "http", "path": "/item/abc", "method": "GET"}
    with pytest.raises(ValueError):
        # Should raise ValueError when trying to convert 'abc' to int
        route.matches(scope)

def test_edge_partial_match_with_path_params():
    # Method mismatch, but path params should still be present
    route = Route("/user/{id:int}", dummy_endpoint, methods=["POST"])
    scope = {"type": "http", "path": "/user/99", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.82μs -> 4.27μs (12.7% faster)

def test_edge_path_params_merge():
    # Existing path_params in scope should be merged with matched params
    route = Route("/product/{pid:int}", dummy_endpoint)
    scope = {"type": "http", "path": "/product/123", "method": "GET", "path_params": {"foo": "bar"}}
    match, child_scope = route.matches(scope) # 4.24μs -> 4.05μs (4.66% faster)

def test_edge_path_with_path_convertor():
    # Path convertor should match slashes
    route = Route("/files/{filepath:path}", dummy_endpoint)
    scope = {"type": "http", "path": "/files/a/b/c.txt", "method": "GET"}
    match, child_scope = route.matches(scope) # 3.88μs -> 3.48μs (11.5% faster)

def test_edge_non_http_scope():
    # Non-http scope should not match
    route = Route("/ws", dummy_endpoint)
    scope = {"type": "websocket", "path": "/ws", "method": "GET"}
    match, child_scope = route.matches(scope) # 706ns -> 821ns (14.0% slower)

def test_edge_unknown_convertor_type():
    # Unknown convertor type should raise AssertionError
    with pytest.raises(AssertionError):
        Route("/foo/{bar:unknown}", dummy_endpoint)



def test_large_long_path_param():
    # Test matching a very long path param
    long_name = "a" * 500
    route = Route("/user/{username}", dummy_endpoint)
    scope = {"type": "http", "path": f"/user/{long_name}", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.76μs -> 4.21μs (13.0% faster)

def test_large_many_path_params():
    # Path with many dynamic parameters
    param_str = "/".join([f"{{p{i}:int}}" for i in range(20)])
    route = Route(f"/{param_str}", dummy_endpoint)
    path_str = "/" + "/".join(str(i) for i in range(20))
    scope = {"type": "http", "path": path_str, "method": "GET"}
    match, child_scope = route.matches(scope) # 10.2μs -> 9.32μs (9.50% faster)
    for i in range(20):
        pass

def test_large_path_convertor_with_long_path():
    # Path convertor with a long path value
    long_path = "/".join([f"dir{i}" for i in range(100)])
    route = Route("/files/{filepath:path}", dummy_endpoint)
    scope = {"type": "http", "path": f"/files/{long_path}", "method": "GET"}
    match, child_scope = route.matches(scope) # 4.34μs -> 3.82μs (13.5% faster)

def test_large_batch_of_scopes():
    # Matching a batch of scopes with different paths
    route = Route("/user/{id:int}", dummy_endpoint)
    scopes = [
        {"type": "http", "path": f"/user/{i}", "method": "GET"}
        for i in range(100)
    ]
    for i, scope in enumerate(scopes):
        match, child_scope = route.matches(scope) # 107μs -> 91.8μs (17.0% faster)

def test_large_batch_of_non_matching_scopes():
    # Batch of scopes that should not match
    route = Route("/user/{id:int}", dummy_endpoint)
    scopes = [
        {"type": "http", "path": f"/user/{chr(65+i)}", "method": "GET"}
        for i in range(100)
    ]
    for scope in scopes:
        match, child_scope = route.matches(scope) # 47.5μs -> 45.5μs (4.37% faster)
# codeflash_output is used to check that the output of the original code is the same as that of the optimized code.

To edit these changes git checkout codeflash/optimize-Route.matches-mhbm0x0g and push.