Pyjoyment 0.1.0__py3-none-any.whl

Pyjoyment/Routes/Match.py

@@ -0,0 +1,251 @@
+"""
+Pyjoyment.Routes.Match - Find routes
+====================================
+::
+
+    import Pyjoyment.Controller
+    import Pyjoyment.Routes
+
+    from Pyjoyment.Routes.Match import Match
+
+    # Routes
+    r = Pyjoyment.Routes.new()
+    r.get('/user/:id')
+    r.put('/user/:id')
+
+    # Match
+    c = Pyjoyment.Controller.new()
+    match = Match(root=r)
+    match.find(c, method='PUT', path='/user/23')
+    print(match.stack[0]['id'])
+
+    # Or import the module, as in Google Python Style Guide
+
+    import Pyjoyment.Controller
+    import Pyjoyment.Routes
+    import Pyjoyment.Routes.Match
+
+    # Routes
+    r = Pyjoyment.Routes.new()
+    r.get('/user/:id')
+    r.put('/user/:id')
+
+    # Match
+    c = Pyjoyment.Controller.new()
+    match = Pyjoyment.Routes.Match.new(root=r)
+    match.find(c, method='PUT', path='/user/23')
+    print(match.stack[0]['id'])
+
+    # Render
+    print(match.path_for()['path'])
+    print(match.path_for(id=24)['path'])
+
+:mod:`Pyjoyment.Routes.Match` finds routes in :mod:`Pyjoyment.Routes`
+structures.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Routes::Match
+<https://github.com/mojolicious/mojo/blob/v9.52/lib/Mojolicious/Routes/Match.pm>`_ of Mojolicious 9.52.
+"""
+
+import Pyjo.Base
+import Pyjo.Util
+import Pyjoyment.Routes.Route
+
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    import Pyjoyment.Controller
+
+
+_MISSING = object()
+
+
+class Pyjoyment_Routes_Match(Pyjo.Base.object):
+    """
+    :mod:`Pyjoyment.Routes.Match` inherits all methods from :mod:`Pyjo.Base`
+    and implements the following new ones.
+    """
+
+    def __init__(
+        self,
+        endpoint: Pyjoyment.Routes.Route.object | None = None,
+        position: int = 0,
+        root: Any = None,
+        stack: list[dict[str, Any]] | None = None,
+    ) -> None:
+        """::
+
+            match = Pyjoyment.Routes.Match.new(root=r)
+
+        Construct a new :mod:`Pyjoyment.Routes.Match` object.
+        """
+        self.endpoint = endpoint
+        """::
+
+            route = match.endpoint
+            match.endpoint = Pyjoyment.Routes.Route.new()
+
+        The route endpoint that matched, usually a :mod:`Pyjoyment.Routes.Route`
+        object.
+        """
+
+        self.position = position
+        """::
+
+            position = match.position
+            match.position = 2
+
+        Current position on the :attr:`stack`, defaults to ``0``.
+        """
+
+        # The root has the attributes of Pyjoyment.Routes, which imports this module
+        self.root = root
+        """::
+
+            root = match.root
+            match.root = Pyjoyment.Routes.new()
+
+        The root of the route structure, usually a :mod:`Pyjoyment.Routes`
+        object.
+        """
+
+        self.stack: list[dict[str, Any]] = stack if stack is not None else []
+        """::
+
+            stack = match.stack
+            match.stack = [{'action': 'foo'}, {'action': 'bar'}]
+
+        Captured parameters with nesting history.
+        """
+
+        self._captures: dict[str, Any] = {}
+        self._conditions: dict[str, Any] | None = None
+
+    def find(self, c: 'Pyjoyment.Controller.object', *, method: str, path: str, websocket: bool = False) -> bool:
+        """::
+
+            match.find(Pyjoyment.Controller.new(), method='GET', path='/')
+
+        Match controller and options against :attr:`root` to find an
+        appropriate :attr:`endpoint`.
+        """
+        return self._match(self.root, c, method, path, websocket)
+
+    def path_for(self, *args: Any, **values: Any) -> dict[str, Any]:
+        """::
+
+            info = match.path_for()
+            info = match.path_for(foo='bar')
+            info = match.path_for({'foo': 'bar'})
+            info = match.path_for('named')
+            info = match.path_for('named', foo='bar')
+            info = match.path_for('named', {'foo': 'bar'})
+
+        Render matching route with parameters into path.
+        """
+        name, values = Pyjo.Util._options(args, values)  # pyright: ignore[reportPrivateUsage]
+
+        # Current route
+        current = not name or name == 'current'
+        if current:
+            if (route := self.endpoint) is None:
+                return {}
+
+        # Find endpoint
+        elif (route := self.root.lookup(name)) is None:
+            return {'path': name}
+
+        # Merge values (clear format)
+        captures = self.stack[-1] if self.stack else {}
+        merged = {**captures, 'format': None, **values}
+        pattern = route.pattern
+        constraints = pattern.constraints
+        if 'format' not in values and (format := constraints.get('format')) and format is not True:
+            value = captures.get('format') if current else None
+            merged['format'] = value if value is not None else pattern.defaults.get('format')
+
+        return {'path': route.render(merged), 'websocket': route.has_websocket}
+
+    def _match(
+        self,
+        r: Pyjoyment.Routes.Route.object,
+        c: 'Pyjoyment.Controller.object',
+        method: str,
+        path: str,
+        websocket: bool,
+    ) -> bool:
+        # Pattern
+        partial = r.partial
+        detect = (endpoint := r.is_endpoint) and not partial
+        if (result := r.pattern.match_partial(path, detect)) is None:
+            return False
+        found, path = result
+
+        # The captures of this route are set until it returns, as Mojo does with local
+        captures = self._captures
+        saved = [(key, captures.get(key, _MISSING)) for key in found]
+        captures.update(found)
+        try:
+            # Method
+            if (methods := r.methods()) and method not in methods:
+                return False
+
+            # Conditions
+            if over := r.requires():
+                if (conditions := self._conditions) is None:
+                    conditions = self._conditions = self.root.conditions
+                for name, value in over:
+                    if not (condition := conditions.get(name)):
+                        return False
+                    if not condition(r, c, captures, value):
+                        return False
+
+            # WebSocket
+            if r.is_websocket and not websocket:
+                return False
+
+            # Partial
+            empty = not path or path == '/'
+            if partial:
+                captures['path'] = path
+                self.endpoint = r
+                empty = True
+
+            # Endpoint (or intermediate destination)
+            if (endpoint and empty) or r.inline:
+                self.stack.append({**captures})
+                if endpoint and empty:
+                    if format := captures.get('format'):
+                        for frame in self.stack:
+                            frame['format'] = format
+                    self.endpoint = r
+                    return True
+                captures.pop('app', None)
+                captures.pop('cb', None)
+
+            # Match children
+            snapshot = list(self.stack) if r.parent is not None else []
+            for child in r._candidates(path):  # pyright: ignore[reportPrivateUsage]
+                if self._match(child, c, method, path, websocket):
+                    return True
+                self.stack = list(snapshot)
+
+            return False
+
+        finally:
+            for key, value in saved:
+                if value is _MISSING:
+                    captures.pop(key, None)
+                else:
+                    captures[key] = value
+
+
+new = Pyjoyment_Routes_Match.new
+object = Pyjoyment_Routes_Match
+Match = Pyjoyment_Routes_Match

Pyjoyment/Routes/Pattern.py

@@ -0,0 +1,443 @@
+"""
+Pyjoyment.Routes.Pattern - Route pattern
+========================================
+::
+
+    from Pyjoyment.Routes.Pattern import Pattern
+
+    # Create pattern
+    pattern = Pattern('/test/:name')
+
+    # Or import the module, as in Google Python Style Guide
+
+    import Pyjoyment.Routes.Pattern
+
+    # Create pattern
+    pattern = Pyjoyment.Routes.Pattern.new('/test/:name')
+
+    # Match routes
+    captures = pattern.match('/test/sebastian')
+    print(captures['name'])
+
+:mod:`Pyjoyment.Routes.Pattern` is the core of :mod:`Pyjoyment.Routes`.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojolicious::Routes::Pattern
+<https://github.com/mojolicious/mojo/blob/v9.52/lib/Mojolicious/Routes/Pattern.pm>`_ of Mojolicious 9.52.
+"""
+
+import Pyjo.Base
+
+import re
+
+from typing import Any, Self
+
+
+# A constraint is a regular expression, as a string or compiled, a list of alternatives, or for the format True to
+# detect any and False to detect none
+type Constraint = str | re.Pattern[str] | list[str] | bool
+
+# A token of the tree is a list of its kind and its values, which the tokenizer changes as it reads the characters:
+# ['text', '/foo'], ['slash'] or ['placeholder', [name, type], 'relaxed' | 'wildcard']
+type Token = list[Any]
+
+
+class Pyjoyment_Routes_Pattern(Pyjo.Base.object):
+    """
+    :mod:`Pyjoyment.Routes.Pattern` inherits all methods from :mod:`Pyjo.Base`
+    and implements the following new ones.
+    """
+
+    def __init__(self, pattern: str | None = None, /, **constraints: Constraint) -> None:
+        """::
+
+            pattern = Pyjoyment.Routes.Pattern.new()
+            pattern = Pyjoyment.Routes.Pattern.new('/users/:id')
+            pattern = Pyjoyment.Routes.Pattern.new('/user/:id', id=re.compile(r'\\d+'))
+            pattern = Pyjoyment.Routes.Pattern.new(format=['json', 'yaml'])
+
+        Construct a new :mod:`Pyjoyment.Routes.Pattern` object and
+        :meth:`parse` pattern if necessary.
+        """
+        self.constraints: dict[str, Constraint] = {}
+        """::
+
+            constraints = pattern.constraints
+            pattern.constraints = {'foo': re.compile(r'\\w+')}
+
+        Regular expression constraints.
+        """
+
+        self.defaults: dict[str, Any] = {}
+        """::
+
+            defaults = pattern.defaults
+            pattern.defaults = {'foo': 'bar'}
+
+        Default parameters.
+        """
+
+        self.placeholder_start = ':'
+        """::
+
+            start = pattern.placeholder_start
+            pattern.placeholder_start = ':'
+
+        Character indicating a placeholder, defaults to ``:``.
+        """
+
+        self.placeholders: list[str] = []
+        """::
+
+            placeholders = pattern.placeholders
+            pattern.placeholders = ['foo', 'bar']
+
+        Placeholder names.
+        """
+
+        self.quote_end = '>'
+        """::
+
+            end = pattern.quote_end
+            pattern.quote_end = '}'
+
+        Character indicating the end of a quoted placeholder, defaults to ``>``.
+        """
+
+        self.quote_start = '<'
+        """::
+
+            start = pattern.quote_start
+            pattern.quote_start = '{'
+
+        Character indicating the start of a quoted placeholder, defaults to
+        ``<``.
+        """
+
+        self.regex: re.Pattern[str] | None = None
+        """::
+
+            regex = pattern.regex
+            pattern.regex = regex
+
+        Pattern in compiled regular expression form.
+        """
+
+        self.relaxed_start = '#'
+        """::
+
+            start = pattern.relaxed_start
+            pattern.relaxed_start = '*'
+
+        Character indicating a relaxed placeholder, defaults to ``#``.
+        """
+
+        self.tree: list[Token] = []
+        """::
+
+            tree = pattern.tree
+            pattern.tree = [['text', '/foo']]
+
+        Pattern in parsed form. Note that this structure should only be used
+        very carefully since it is very dynamic.
+        """
+
+        self.type_start = ':'
+        """::
+
+            start = pattern.type_start
+            pattern.type_start = '|'
+
+        Character indicating the start of a placeholder type, defaults to ``:``.
+        """
+
+        self.types: dict[str, Constraint] = {}
+        """::
+
+            types = pattern.types
+            pattern.types = {'int': re.compile(r'[0-9]+')}
+
+        Placeholder types.
+        """
+
+        self.unparsed: str | None = None
+        """::
+
+            unparsed = pattern.unparsed
+            pattern.unparsed = '/:foo/:bar'
+
+        Raw unparsed pattern.
+        """
+
+        self.wildcard_start = '*'
+        """::
+
+            start = pattern.wildcard_start
+            pattern.wildcard_start = '*'
+
+        Character indicating the start of a wildcard placeholder, defaults to
+        ``*``.
+        """
+
+        # The regex that _compile made, which tells a custom one apart
+        self._compiled: re.Pattern[str] | None = None
+
+        if pattern is not None or constraints:
+            self.parse(pattern, **constraints)
+
+    def match(self, path: str, detect: bool = False) -> dict[str, Any] | None:
+        """::
+
+            captures = pattern.match('/foo/bar')
+            captures = pattern.match('/foo/bar', True)
+
+        Match pattern against entire path, format detection is disabled by
+        default.
+        """
+        if (result := self.match_partial(path, detect)) is None:
+            return None
+        captures, path = result
+        # Unlike Mojolicious: a rest of "0" is no match, which Mojo's !$path takes for an empty one, as 0 is false
+        return captures if not path or path == '/' else None
+
+    def match_partial(self, path: str, detect: bool = False) -> tuple[dict[str, Any], str] | None:
+        """::
+
+            captures, path = pattern.match_partial(path)
+            captures, path = pattern.match_partial(path, True)
+
+        Match pattern against path and return the captures with the rest of the
+        path, without the matching parts, format detection is disabled by
+        default.
+        """
+        # Compile on demand
+        if (regex := self.regex) is None:
+            regex = self._compile(detect)
+
+        if (m := regex.match(path)) is None:
+            return None
+        groups = list(m.groups())
+        captures = {**self.defaults}
+        for placeholder in [*self.placeholders, 'format']:
+            if not groups:
+                break
+            if (capture := groups.pop(0)) is not None:
+                captures[placeholder] = capture
+
+        return captures, path[m.end() :]
+
+    def parse(self, pattern: str | None = None, /, **constraints: Constraint) -> Self:
+        """::
+
+            pattern = pattern.parse('/user/:id')
+            pattern = pattern.parse('/user/:id', id=re.compile(r'\\d+'))
+            pattern = pattern.parse(format=['json', 'yaml'])
+
+        Parse pattern.
+        """
+        pattern = re.sub(r'^/*|/+', '/', pattern if pattern is not None else '/')
+        self.constraints = constraints
+        if pattern == '/':
+            return self
+
+        return self._tokenize(re.sub(r'/$', '', pattern, count=1))
+
+    def render(self, values: dict[str, Any] | None = None, endpoint: bool = False) -> str:
+        """::
+
+            path = pattern.render({'id': 24})
+            path = pattern.render({'id': 24}, True)
+
+        Render pattern into a path with parameters, format rendering is
+        disabled by default.
+        """
+        values = values if values is not None else {}
+
+        # Placeholders can only be optional without a format
+        optional = not (format := values.get('format'))
+
+        parts: list[str] = []
+        for token in reversed(self.tree):
+            op = token[0]
+            part = ''
+
+            # Text
+            if op == 'text':
+                part, optional = token[1], False
+
+            # Slash
+            elif op == 'slash':
+                if not optional:
+                    part = '/'
+
+            # Placeholder
+            else:
+                name = token[1][0]
+                default = self.defaults.get(name)
+                value = values.get(name)
+                part = str(value if value is not None else default if default is not None else '')
+                if default is None or str(default) != part:
+                    optional = False
+                elif optional:
+                    part = ''
+
+            parts.append(part)
+
+        # Format can be optional
+        path = ''.join(reversed(parts))
+        return f'{path}.{format}' if endpoint and format else path
+
+    def _compile(self, detect: bool) -> re.Pattern[str]:
+        constraints = self.constraints
+        defaults = self.defaults
+        types = self.types
+
+        block = regex = ''
+        optional = True
+        for token in reversed(self.tree):
+            op = token[0]
+            part = ''
+
+            # Text
+            if op == 'text':
+                part, optional = re.escape(token[1]), False
+
+            # Slash
+            elif op == 'slash':
+                regex = (f'(?:/{block})?' if optional else f'/{block}') + regex
+                block, optional = '', True
+                continue
+
+            # Placeholder
+            else:
+                value: list[str] = token[1]
+                if len(value) > 1:
+                    part = _compile_req(types.get(value[1], '?!'))
+                else:
+                    type = token[2] if len(token) > 2 else None
+                    part = ('([^/]+)' if type == 'relaxed' else '(.+)') if type else '([^/.]+)'
+
+                # Custom regex
+                if c := constraints.get(value[0]):
+                    part = _compile_req(c)
+
+                # Optional placeholder
+                if value[0] in defaults:
+                    part += '?'
+                else:
+                    optional = False
+
+            block = part + block
+
+        # Not rooted with a slash
+        if block:
+            regex = block + regex
+
+        # Format
+        if detect:
+            regex += _compile_format(constraints.get('format'), 'format' in defaults)
+
+        self.regex = self._compiled = re.compile(f'^{regex}', re.DOTALL)
+        return self.regex
+
+    def _tokenize(self, pattern: str) -> Self:
+        placeholders = self.placeholders
+        type_start = self.type_start
+        quote_end = self.quote_end
+        quote_start = self.quote_start
+        start = self.placeholder_start
+        relaxed = self.relaxed_start
+        wildcard = self.wildcard_start
+
+        tree: list[Token] = []
+        spec = more = 0
+        for char in pattern:
+            # Quoted
+            if char == quote_start:
+                spec += 1
+                tree.append(['placeholder', ''])
+            elif char == quote_end:
+                spec = more = 0
+
+            # Placeholder
+            elif not more and char == start:
+                if not spec:
+                    tree.append(['placeholder', ''])
+                spec += 1
+
+            # Relaxed or wildcard (upgrade when quoted)
+            elif not more and char in (relaxed, wildcard):
+                if not spec:
+                    tree.append(['placeholder', ''])
+                spec += 1
+                tree[-1][2:] = ['relaxed' if char == relaxed else 'wildcard']
+
+            # Slash
+            elif char == '/':
+                tree.append(['slash'])
+                spec = more = 0
+
+            # Placeholder
+            elif spec:
+                more += 1
+                tree[-1][1] += char
+
+            # Text (optimize slash+text and *+text+slash+text)
+            elif tree and tree[-1][0] == 'text':
+                tree[-1][-1] += char
+            elif len(tree) == 1 and tree[-1][0] == 'slash':
+                tree = [['text', f'/{char}']]
+            elif len(tree) > 1 and tree[-2][0] == 'text' and tree[-1][0] == 'slash':
+                tree.pop()
+                tree[-1][-1] += f'/{char}'
+            else:
+                tree.append(['text', char])
+
+        # Placeholder types
+        for token in reversed(tree):
+            if token[0] != 'placeholder':
+                continue
+            m = re.match(rf'^(.+){re.escape(type_start)}(.+)$', token[1])
+            token[1] = [m[1], m[2]] if m else [token[1]]
+            placeholders.insert(0, token[1][0])
+
+        self.unparsed = pattern
+        self.tree = tree
+        return self
+
+
+def _compile_format(format: Constraint | None, has_default: bool) -> str:
+    # No regex
+    if not format:
+        return ''
+
+    # Default regex
+    if format is True:
+        return r'/?(?:\.([^/]+))?$'
+
+    # Compile custom regex
+    regex = r'\.' + _compile_req(format)
+    return f'/?(?:{regex})?$' if has_default else f'/?{regex}$'
+
+
+def _compile_req(req: Constraint) -> str:
+    if isinstance(req, list):
+        return '(' + '|'.join(re.escape(alternative) for alternative in sorted(map(str, req), reverse=True)) + ')'
+    if isinstance(req, re.Pattern):
+        return f'({_regex_source(req)})'
+    return f'({req})'
+
+
+# The source of a compiled regular expression with its flags, as Perl stringifies a qr// with (?^flags:...)
+def _regex_source(regex: re.Pattern[str]) -> str:
+    flags = ''.join(flag for flag, value in (('i', re.I), ('m', re.M), ('s', re.S), ('x', re.X)) if regex.flags & value)
+    return f'(?{flags}:{regex.pattern})' if flags else regex.pattern
+
+
+new = Pyjoyment_Routes_Pattern.new
+object = Pyjoyment_Routes_Pattern
+Pattern = Pyjoyment_Routes_Pattern