django-fastresolve 0.1.0__py3-none-any.whl

django_fastresolve/__init__.py

@@ -0,0 +1,9 @@
+__version__ = '0.1.0'
+
+from django_fastresolve.resolver import (
+    install,
+    stock_resolving,
+    uninstall,
+)
+
+__all__ = ['install', 'stock_resolving', 'uninstall']

django_fastresolve/apps.py

@@ -0,0 +1,11 @@
+from django.apps import AppConfig
+
+
+class FastResolveConfig(AppConfig):
+    name = 'django_fastresolve'
+    verbose_name = 'django-fastresolve'
+
+    def ready(self):
+        from django_fastresolve import install
+
+        install()

django_fastresolve/resolver.py

@@ -0,0 +1,234 @@
+"""A faster drop-in for ``URLResolver.resolve``.
+
+Django resolves a path by trying every child pattern of a resolver in order,
+and recursing into includes. With hundreds of patterns at one level, that's
+hundreds of regex searches or string compares per request.
+
+This module indexes each resolver's children by their *literal prefix*: the
+part of the pattern that must appear verbatim at the start of the path for the
+pattern to have any chance of matching. A path then only needs to try the
+children whose literal prefix it starts with, still in their original order.
+Everything else (converters, ``ValueError`` from ``to_python`` falling through
+to later patterns, namespaces, default kwargs) is Django's own code.
+
+When the prefix of a child can't be determined safely, its prefix is the empty
+string, meaning it is a candidate for every path. Correctness never depends on
+the index being clever, only on it never excluding a pattern that could match.
+"""
+
+import string
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from django.conf import settings
+from django.urls.exceptions import Resolver404
+from django.urls.resolvers import (
+    RegexPattern,
+    ResolverMatch,
+    RoutePattern,
+    URLPattern,
+    URLResolver,
+)
+
+stock_resolve = URLResolver.resolve
+
+_use_stock = ContextVar('django_fastresolve_use_stock', default=False)
+
+# Characters that mean themselves when unescaped in a regex, outside a character class
+_REGEX_LITERAL_CHARS = frozenset(string.ascii_letters + string.digits + '/-_~%=,;:@!&\'"<>')
+_REGEX_QUANTIFIER_START = frozenset('?*+{')
+
+
+@contextmanager
+def stock_resolving():
+    """Resolve with Django's own implementation inside this block, in this context only."""
+    token = _use_stock.set(True)
+    try:
+        yield
+    finally:
+        _use_stock.reset(token)
+
+
+def regex_literal_prefix(regex):
+    """The literal text any match of `regex` (searched with `re.search`) must start with.
+
+    Conservative: returns '' whenever the regex isn't plainly ``^literal...``.
+    """
+    if not isinstance(regex, str) or not regex.startswith('^') or '|' in regex:
+        return ''
+
+    prefix = []
+    i = 1
+    while i < len(regex):
+        c = regex[i]
+        if c in _REGEX_LITERAL_CHARS:
+            literal, width = c, 1
+        elif c == '\\' and i + 1 < len(regex) and not regex[i + 1].isalnum():
+            literal, width = regex[i + 1], 2
+        else:
+            break
+
+        i += width
+        if i < len(regex) and regex[i] in _REGEX_QUANTIFIER_START:
+            # The char we just read is optional or repeated, so it's not a fixed prefix
+            break
+        prefix.append(literal)
+
+    return ''.join(prefix)
+
+
+def literal_prefix(url_pattern):
+    """The prefix a path must start with for `url_pattern` to possibly resolve it."""
+    resolve_method = getattr(type(url_pattern), 'resolve', None)
+    if resolve_method is not URLPattern.resolve and resolve_method is not fast_resolve:
+        # A subclass with its own idea of matching, we can't reason about it
+        return ''
+
+    pattern = url_pattern.pattern
+    if type(pattern) is RoutePattern:
+        route = pattern._route
+        if not isinstance(route, str):
+            # Lazily translated, depends on the active language
+            return ''
+        # Cutting at any '<' is safe even when it doesn't start a converter: a shorter prefix only means more candidates
+        index = route.find('<')
+        return route if index == -1 else route[:index]
+
+    if type(pattern) is RegexPattern:
+        return regex_literal_prefix(pattern._regex)
+
+    # LocalePrefixPattern, or a pattern type we don't know
+    return ''
+
+
+class Index:
+    __slots__ = ('patterns', 'length', 'lengths_desc', 'candidates_by_prefix', 'is_root')
+
+    def __init__(self, resolver, patterns):
+        self.patterns = patterns
+        self.length = len(patterns)
+        self.is_root = type(resolver.pattern) is RegexPattern and resolver.pattern._regex == '^/'
+
+        indexes_by_own_prefix = {}
+        for i, url_pattern in enumerate(patterns):
+            indexes_by_own_prefix.setdefault(literal_prefix(url_pattern), []).append(i)
+
+        lengths = sorted({len(prefix) for prefix in indexes_by_own_prefix})
+
+        # For every prefix, the candidates are its own patterns plus those of every
+        # shorter prefix it starts with. Any path's candidates are then those of the
+        # longest prefix it starts with. Shortest first, so parents are done before
+        # their children.
+        indexes_by_prefix = {}
+        for prefix in sorted(indexes_by_own_prefix, key=len):
+            inherited = ()
+            for length in reversed(lengths):
+                if length < len(prefix):
+                    parent = indexes_by_prefix.get(prefix[:length])
+                    if parent is not None:
+                        inherited = parent
+                        break
+            indexes_by_prefix[prefix] = tuple(sorted({*inherited, *indexes_by_own_prefix[prefix]}))
+
+        self.candidates_by_prefix = {prefix: tuple(patterns[i] for i in indexes) for prefix, indexes in indexes_by_prefix.items()}
+        self.lengths_desc = tuple(reversed(lengths))
+
+    def candidates(self, path):
+        candidates_by_prefix = self.candidates_by_prefix
+        path_length = len(path)
+        for length in self.lengths_desc:
+            if length <= path_length:
+                candidates = candidates_by_prefix.get(path[:length])
+                if candidates is not None:
+                    return candidates
+        return ()
+
+
+def _get_index(resolver):
+    patterns = resolver.url_patterns
+    index = resolver.__dict__.get('_fastresolve_index')
+    # The length check catches the common case of urlpatterns being appended to after the first resolve
+    if index is None or index.patterns is not patterns or index.length != len(patterns):
+        if not isinstance(patterns, (list, tuple)):
+            return None
+        index = Index(resolver, patterns)
+        resolver._fastresolve_index = index
+    return index
+
+
+def fast_resolve(self, path):
+    if _use_stock.get():
+        return stock_resolve(self, path)
+
+    path = str(path)  # path may be a reverse_lazy object
+    match = self.pattern.match(path)
+    if not match:
+        raise Resolver404({'path': path})
+
+    index = _get_index(self)
+    if index is None:
+        return stock_resolve(self, path)
+
+    new_path, args, kwargs = match
+    tried = []
+    # From here on, this is Django's URLResolver.resolve, only looping over the candidates instead of all patterns
+    for pattern in index.candidates(new_path):
+        try:
+            sub_match = pattern.resolve(new_path)
+        except Resolver404 as e:
+            self._extend_tried(tried, pattern, e.args[0].get('tried'))
+        else:
+            if sub_match:
+                # Merge captured arguments in match with submatch
+                sub_match_dict = {**kwargs, **self.default_kwargs}
+                # Update the sub_match_dict with the kwargs from the sub_match.
+                sub_match_dict.update(sub_match.kwargs)
+                # If there are *any* named groups, ignore all non-named
+                # groups. Otherwise, pass all non-named arguments as
+                # positional arguments.
+                sub_match_args = sub_match.args
+                if not sub_match_dict:
+                    sub_match_args = args + sub_match.args
+                current_route = '' if isinstance(pattern, URLPattern) else str(pattern.pattern)
+                self._extend_tried(tried, pattern, sub_match.tried)
+                return ResolverMatch(
+                    sub_match.func,
+                    sub_match_args,
+                    sub_match_dict,
+                    sub_match.url_name,
+                    [self.app_name, *sub_match.app_names],
+                    [self.namespace, *sub_match.namespaces],
+                    self._join_route(current_route, sub_match.route),
+                    tried,
+                    captured_kwargs=sub_match.captured_kwargs,
+                    extra_kwargs={
+                        **self.default_kwargs,
+                        **sub_match.extra_kwargs,
+                    },
+                )
+            tried.append([pattern])
+
+    if index.is_root and settings.DEBUG:
+        _check_stock_404(self, path)
+
+    raise Resolver404({'tried': tried, 'path': new_path})
+
+
+def _check_stock_404(resolver, path):
+    """In DEBUG, redo a 404 the stock way.
+
+    The 404 debug page then lists every pattern instead of only the candidates,
+    and if stock Django does find a match, that's a bug in this library and we
+    say so loudly instead of serving a wrong 404.
+    """
+    with stock_resolving():
+        match = stock_resolve(resolver, path)
+    raise AssertionError(f'django-fastresolve bug: {path!r} resolved to {match._func_path} with stock Django, but not with django-fastresolve. Please report this at https://github.com/boxed/django-fastresolve/issues')
+
+
+def install():
+    URLResolver.resolve = fast_resolve
+
+
+def uninstall():
+    URLResolver.resolve = stock_resolve

django_fastresolve-0.1.0.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: django-fastresolve
+Version: 0.1.0
+Summary: Faster URL resolving for Django, by indexing url patterns on their literal prefixes
+Project-URL: Homepage, https://github.com/boxed/django-fastresolve
+Author-email: Anders Hovmöller <boxed@killingar.net>
+License: BSD
+License-File: LICENSE
+Keywords: django,performance,urls
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Description-Content-Type: text/x-rst
+
+django-fastresolve
+==================
+
+Faster URL resolving for Django, as a drop-in. No changes to your urlconfs.
+
+Django resolves a path by trying every pattern of a urlconf in order, recursing
+into includes. With a few hundred patterns at one level, every request pays for
+a few hundred regex searches or string compares, and a 404 pays for all of them.
+
+django-fastresolve indexes the patterns of each resolver on their *literal
+prefix*: the text a path must start with for the pattern to have any chance of
+matching (``'projects/'`` for ``path('projects/<int:pk>/', ...)``, ``'blog/'``
+for ``re_path(r'^blog/(?P<slug>\w+)/$', ...)``). A path then only tries the
+patterns whose prefix it starts with, still in their original order. All the
+matching itself is still Django's own code: converters, a ``to_python`` raising
+``ValueError`` falling through to later patterns, namespaces, default kwargs.
+
+
+Installation
+------------
+
+.. code-block::
+
+    pip install django-fastresolve
+
+and add ``'django_fastresolve'`` to ``INSTALLED_APPS``. That's it.
+
+You can also call ``django_fastresolve.install()`` and
+``django_fastresolve.uninstall()`` yourself.
+
+
+How much faster?
+----------------
+
+On a real project with three urlconfs, timing ``resolve()`` on every route,
+with ``DEBUG = False``:
+
+=====================  ======  ============  ==============  ==========  ==========
+urlconf                routes  stock median  fast median     stock 404   fast 404
+=====================  ======  ============  ==============  ==========  ==========
+internal app           785     25 µs         6 µs            27 µs       2 µs
+public site            894     64 µs         4.6 µs          125 µs      4.8 µs
+small                  83      8 µs          7 µs            6 µs        3 µs
+=====================  ======  ============  ==============  ==========  ==========
+
+The more patterns share a level, the bigger the win. Patterns that stock Django
+already finds in the first couple of tries get about 1 µs slower, from the
+index lookup.
+
+
+When does it fall back?
+-----------------------
+
+A pattern whose prefix can't be determined safely gets the empty prefix, which
+means it is tried for every path, exactly where stock Django would try it. That
+is the case for:
+
+- lazily translated routes (``path(gettext_lazy('about/'), ...)``)
+- regexes that aren't anchored with ``^``, or that contain ``|``
+- ``i18n_patterns`` (``LocalePrefixPattern``)
+- ``URLPattern``/``URLResolver`` subclasses that override ``resolve()``
+- pattern classes it doesn't know
+
+Only the leading literal part of a regex counts: ``r'^ab?c/'`` has the prefix
+``'a'``.
+
+
+Differences from stock Django
+-----------------------------
+
+``tried`` (on ``Resolver404`` and on ``ResolverMatch.tried``) only lists the
+patterns that were actually tried, not every pattern before the match.
+
+With ``DEBUG = True`` a 404 is resolved again the stock way, so the 404 debug
+page lists every pattern as usual. That also acts as a self check: if stock
+Django finds a match where django-fastresolve didn't, you get an
+``AssertionError`` saying so, instead of a wrong 404. Please report it if that
+happens.
+
+The index for a resolver is built on first use. If you append to or remove from
+``urlpatterns`` afterwards the index is rebuilt; replacing an item in place is
+not noticed.
+
+To resolve the stock way for a block of code, in the current context only:
+
+.. code-block:: python
+
+    from django_fastresolve import stock_resolving
+
+    with stock_resolving():
+        match = resolve('/some/path/')
+
+
+Running the tests
+-----------------
+
+.. code-block::
+
+    uv run pytest
+
+The tests resolve a urlconf full of edge cases, plus a few thousand fuzzed
+paths, both ways, and assert identical results.

django_fastresolve-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+django_fastresolve/__init__.py,sha256=IdMJYacIEgfN35FGXcB38kS6WGqkYE8lBsYCQwQw8tE,171
+django_fastresolve/apps.py,sha256=AUDRDJ6T8KIVJk8oLs1wC127CFg2_g4jDtEkncVgRQM,232
+django_fastresolve/resolver.py,sha256=ZDuN7nskDYuE8KXTnTV75IBrtjGLDKdnpHABNhgJd6Y,9091
+django_fastresolve-0.1.0.dist-info/METADATA,sha256=zbC65L6cJYhwy85B8lKD-dKiWop_CkBvFVrTEVSZmvc,4523
+django_fastresolve-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+django_fastresolve-0.1.0.dist-info/licenses/LICENSE,sha256=5YqUYm5p9jhO9NonNaxla96fIbZPC2U0YSNoPTeTVvE,1479
+django_fastresolve-0.1.0.dist-info/RECORD,,

django_fastresolve-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

django_fastresolve-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2026, Anders Hovmöller
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of django-fastdev nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.