updates

Backend/venv/lib/python3.12/site-packages/packageurl/contrib/route.py

@@ -0,0 +1,224 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (c) the purl authors
+# SPDX-License-Identifier: MIT
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+# Visit https://github.com/package-url/packageurl-python for support and
+# download.
+
+import inspect
+import re
+from functools import wraps
+
+"""
+Given a URI regex (or some string), this module can route execution to a
+callable.
+
+There are several routing implementations available in Rails, Django, Flask,
+Paste, etc. However, these all assume that the routed processing is to craft a
+response to an incoming external HTTP request.
+
+Here we are instead doing the opposite: given a URI (and no request yet) we are
+routing the processing to emit a request externally (HTTP or other protocol)
+and handling its response.
+
+Also we crawl a lot and not only HTTP: git, svn, ftp, rsync and more.
+This simple library support this kind of arbitrary URI routing.
+
+This is inspired by Guido's http://www.artima.com/weblogs/viewpost.jsp?thread=101605
+and Django, Flask, Werkzeug and other url dispatch and routing design from web
+frameworks.
+https://github.com/douban/brownant has a similar approach, using
+Werkzeug with the limitation that it does not route based on URI scheme and is
+limited to HTTP.
+"""
+
+
+class Rule(object):
+    """
+    A rule is a mapping between a pattern (typically a URI) and a callable
+    (typically a function).
+    The pattern is a regex string pattern and must match entirely a string
+    (typically a URI) for the rule to be considered, i.e. for the endpoint to
+    be resolved and eventually invoked for a given string (typically a URI).
+    """
+
+    def __init__(self, pattern, endpoint):
+        # To ensure the pattern will match entirely, we wrap the pattern
+        # with start of line ^ and  end of line $.
+        self.pattern = pattern.lstrip("^").rstrip("$")
+        self.pattern_match = re.compile("^" + self.pattern + "$").match
+
+        # ensure the endpoint is callable
+        assert callable(endpoint)
+        # classes are not always callable, make an extra check
+        if inspect.isclass(endpoint):
+            obj = endpoint()
+            assert callable(obj)
+
+        self.endpoint = endpoint
+
+    def __repr__(self):
+        return f'Rule(r"""{self.pattern}""", {self.endpoint.__module__}.{self.endpoint.__name__})'
+
+    def match(self, string):
+        """
+        Match a string with the rule pattern, return True is matching.
+        """
+        return self.pattern_match(string)
+
+
+class RouteAlreadyDefined(TypeError):
+    """
+    Raised when this route Rule already exists in the route map.
+    """
+
+
+class NoRouteAvailable(TypeError):
+    """
+    Raised when there are no route available.
+    """
+
+
+class MultipleRoutesDefined(TypeError):
+    """
+    Raised when there are more than one route possible.
+    """
+
+
+class Router(object):
+    """
+    A router is:
+    - a container for a route map, consisting of several rules, stored in an
+     ordered dictionary keyed by pattern text
+    - a way to process a route, i.e. given a string (typically a URI), find the
+     correct rule and invoke its callable endpoint
+    - and a convenience decorator for routed callables (either a function or
+     something with a __call__ method)
+
+    Multiple routers can co-exist as needed, such as a router to collect,
+    another to fetch, etc.
+    """
+
+    def __init__(self, route_map=None):
+        """
+        'route_map' is an ordered mapping of pattern -> Rule.
+        """
+        self.route_map = route_map or dict()
+        # lazy cached pre-compiled regex match() for all route patterns
+        self._is_routable = None
+
+    def __repr__(self):
+        return repr(self.route_map)
+
+    def __iter__(self):
+        return iter(self.route_map.items())
+
+    def keys(self):
+        return self.route_map.keys()
+
+    def append(self, pattern, endpoint):
+        """
+        Append a new pattern and endpoint Rule at the end of the map.
+        Use this as an alternative to the route decorator.
+        """
+        if pattern in self.route_map:
+            raise RouteAlreadyDefined(pattern)
+        self.route_map[pattern] = Rule(pattern, endpoint)
+
+    def route(self, *patterns):
+        """
+        Decorator to make a callable 'endpoint' routed to one or more patterns.
+
+        Example:
+        >>> my_router = Router()
+        >>> @my_router.route('http://nexb.com', 'http://deja.com')
+        ... def somefunc(uri):
+        ...    pass
+        """
+
+        def decorator(endpoint):
+            assert patterns
+            for pat in patterns:
+                self.append(pat, endpoint)
+
+            @wraps(endpoint)
+            def decorated(*args, **kwargs):
+                return self.process(*args, **kwargs)
+
+            return decorated
+
+        return decorator
+
+    def process(self, string, *args, **kwargs):
+        """
+        Given a string (typically a URI), resolve this string to an endpoint
+        by searching available rules then execute the endpoint callable for
+        that string passing down all arguments to the endpoint invocation.
+        """
+        endpoint = self.resolve(string)
+        if inspect.isclass(endpoint):
+            # instantiate a class, that must define a __call__ method
+            # TODO: consider passing args to the constructor?
+            endpoint = endpoint()
+        # call the callable
+        return endpoint(string, *args, **kwargs)
+
+    def resolve(self, string):
+        """
+        Resolve a string: given a string (typically a URI) resolve and
+        return the best endpoint function for that string.
+
+        Ambiguous resolution is not allowed in order to keep things in
+        check when there are hundreds rules: if multiple routes are
+        possible for a string (typically a URI), a MultipleRoutesDefined
+        TypeError is raised.
+        """
+        # TODO: we could improve the performance of this by using a single
+        # regex and named groups if this ever becomes a bottleneck.
+        candidates = [r for r in self.route_map.values() if r.match(string)]
+
+        if not candidates:
+            raise NoRouteAvailable(string)
+
+        if len(candidates) > 1:
+            # this can happen when multiple patterns match the same string
+            # we raise an exception with enough debugging information
+            pats = repr([r.pattern for r in candidates])
+            msg = "%(string)r matches multiple patterns %(pats)r" % locals()
+            raise MultipleRoutesDefined(msg)
+
+        return candidates[0].endpoint
+
+    def is_routable(self, string):
+        """
+        Return True if `string` is routable by this router, e.g. if it
+        matches any of the route patterns.
+        """
+        if not string:
+            return
+
+        if not self._is_routable:
+            # build an alternation regex
+            routables = "^(" + "|".join(pat for pat in self.route_map) + ")$"
+            self._is_routable = re.compile(routables, re.UNICODE).match
+
+        return bool(self._is_routable(string))