plain 0.1.0__py3-none-any.whl

plain/utils/regex_helper.py

@@ -0,0 +1,353 @@
+"""
+Functions for reversing a regular expression (used in reverse URL resolving).
+Used internally by Plain and not intended for external use.
+
+This is not, and is not intended to be, a complete reg-exp decompiler. It
+should be good enough for a large class of URLS, however.
+"""
+import re
+
+from plain.utils.functional import SimpleLazyObject
+
+# Mapping of an escape character to a representative of that class. So, e.g.,
+# "\w" is replaced by "x" in a reverse URL. A value of None means to ignore
+# this sequence. Any missing key is mapped to itself.
+ESCAPE_MAPPINGS = {
+    "A": None,
+    "b": None,
+    "B": None,
+    "d": "0",
+    "D": "x",
+    "s": " ",
+    "S": "x",
+    "w": "x",
+    "W": "!",
+    "Z": None,
+}
+
+
+class Choice(list):
+    """Represent multiple possibilities at this point in a pattern string."""
+
+
+class Group(list):
+    """Represent a capturing group in the pattern string."""
+
+
+class NonCapture(list):
+    """Represent a non-capturing group in the pattern string."""
+
+
+def normalize(pattern):
+    r"""
+    Given a reg-exp pattern, normalize it to an iterable of forms that
+    suffice for reverse matching. This does the following:
+
+    (1) For any repeating sections, keeps the minimum number of occurrences
+        permitted (this means zero for optional groups).
+    (2) If an optional group includes parameters, include one occurrence of
+        that group (along with the zero occurrence case from step (1)).
+    (3) Select the first (essentially an arbitrary) element from any character
+        class. Select an arbitrary character for any unordered class (e.g. '.'
+        or '\w') in the pattern.
+    (4) Ignore look-ahead and look-behind assertions.
+    (5) Raise an error on any disjunctive ('|') constructs.
+
+    Plain's URLs for forward resolving are either all positional arguments or
+    all keyword arguments. That is assumed here, as well. Although reverse
+    resolving can be done using positional args when keyword args are
+    specified, the two cannot be mixed in the same reverse() call.
+    """
+    # Do a linear scan to work out the special features of this pattern. The
+    # idea is that we scan once here and collect all the information we need to
+    # make future decisions.
+    result = []
+    non_capturing_groups = []
+    consume_next = True
+    pattern_iter = next_char(iter(pattern))
+    num_args = 0
+
+    # A "while" loop is used here because later on we need to be able to peek
+    # at the next character and possibly go around without consuming another
+    # one at the top of the loop.
+    try:
+        ch, escaped = next(pattern_iter)
+    except StopIteration:
+        return [("", [])]
+
+    try:
+        while True:
+            if escaped:
+                result.append(ch)
+            elif ch == ".":
+                # Replace "any character" with an arbitrary representative.
+                result.append(".")
+            elif ch == "|":
+                # FIXME: One day we'll should do this, but not in 1.0.
+                raise NotImplementedError("Awaiting Implementation")
+            elif ch == "^":
+                pass
+            elif ch == "$":
+                break
+            elif ch == ")":
+                # This can only be the end of a non-capturing group, since all
+                # other unescaped parentheses are handled by the grouping
+                # section later (and the full group is handled there).
+                #
+                # We regroup everything inside the capturing group so that it
+                # can be quantified, if necessary.
+                start = non_capturing_groups.pop()
+                inner = NonCapture(result[start:])
+                result = result[:start] + [inner]
+            elif ch == "[":
+                # Replace ranges with the first character in the range.
+                ch, escaped = next(pattern_iter)
+                result.append(ch)
+                ch, escaped = next(pattern_iter)
+                while escaped or ch != "]":
+                    ch, escaped = next(pattern_iter)
+            elif ch == "(":
+                # Some kind of group.
+                ch, escaped = next(pattern_iter)
+                if ch != "?" or escaped:
+                    # A positional group
+                    name = "_%d" % num_args
+                    num_args += 1
+                    result.append(Group((("%%(%s)s" % name), name)))
+                    walk_to_end(ch, pattern_iter)
+                else:
+                    ch, escaped = next(pattern_iter)
+                    if ch in "!=<":
+                        # All of these are ignorable. Walk to the end of the
+                        # group.
+                        walk_to_end(ch, pattern_iter)
+                    elif ch == ":":
+                        # Non-capturing group
+                        non_capturing_groups.append(len(result))
+                    elif ch != "P":
+                        # Anything else, other than a named group, is something
+                        # we cannot reverse.
+                        raise ValueError("Non-reversible reg-exp portion: '(?%s'" % ch)
+                    else:
+                        ch, escaped = next(pattern_iter)
+                        if ch not in ("<", "="):
+                            raise ValueError(
+                                "Non-reversible reg-exp portion: '(?P%s'" % ch
+                            )
+                        # We are in a named capturing group. Extra the name and
+                        # then skip to the end.
+                        if ch == "<":
+                            terminal_char = ">"
+                        # We are in a named backreference.
+                        else:
+                            terminal_char = ")"
+                        name = []
+                        ch, escaped = next(pattern_iter)
+                        while ch != terminal_char:
+                            name.append(ch)
+                            ch, escaped = next(pattern_iter)
+                        param = "".join(name)
+                        # Named backreferences have already consumed the
+                        # parenthesis.
+                        if terminal_char != ")":
+                            result.append(Group((("%%(%s)s" % param), param)))
+                            walk_to_end(ch, pattern_iter)
+                        else:
+                            result.append(Group((("%%(%s)s" % param), None)))
+            elif ch in "*?+{":
+                # Quantifiers affect the previous item in the result list.
+                count, ch = get_quantifier(ch, pattern_iter)
+                if ch:
+                    # We had to look ahead, but it wasn't need to compute the
+                    # quantifier, so use this character next time around the
+                    # main loop.
+                    consume_next = False
+
+                if count == 0:
+                    if contains(result[-1], Group):
+                        # If we are quantifying a capturing group (or
+                        # something containing such a group) and the minimum is
+                        # zero, we must also handle the case of one occurrence
+                        # being present. All the quantifiers (except {0,0},
+                        # which we conveniently ignore) that have a 0 minimum
+                        # also allow a single occurrence.
+                        result[-1] = Choice([None, result[-1]])
+                    else:
+                        result.pop()
+                elif count > 1:
+                    result.extend([result[-1]] * (count - 1))
+            else:
+                # Anything else is a literal.
+                result.append(ch)
+
+            if consume_next:
+                ch, escaped = next(pattern_iter)
+            consume_next = True
+    except StopIteration:
+        pass
+    except NotImplementedError:
+        # A case of using the disjunctive form. No results for you!
+        return [("", [])]
+
+    return list(zip(*flatten_result(result)))
+
+
+def next_char(input_iter):
+    r"""
+    An iterator that yields the next character from "pattern_iter", respecting
+    escape sequences. An escaped character is replaced by a representative of
+    its class (e.g. \w -> "x"). If the escaped character is one that is
+    skipped, it is not returned (the next character is returned instead).
+
+    Yield the next character, along with a boolean indicating whether it is a
+    raw (unescaped) character or not.
+    """
+    for ch in input_iter:
+        if ch != "\\":
+            yield ch, False
+            continue
+        ch = next(input_iter)
+        representative = ESCAPE_MAPPINGS.get(ch, ch)
+        if representative is None:
+            continue
+        yield representative, True
+
+
+def walk_to_end(ch, input_iter):
+    """
+    The iterator is currently inside a capturing group. Walk to the close of
+    this group, skipping over any nested groups and handling escaped
+    parentheses correctly.
+    """
+    if ch == "(":
+        nesting = 1
+    else:
+        nesting = 0
+    for ch, escaped in input_iter:
+        if escaped:
+            continue
+        elif ch == "(":
+            nesting += 1
+        elif ch == ")":
+            if not nesting:
+                return
+            nesting -= 1
+
+
+def get_quantifier(ch, input_iter):
+    """
+    Parse a quantifier from the input, where "ch" is the first character in the
+    quantifier.
+
+    Return the minimum number of occurrences permitted by the quantifier and
+    either None or the next character from the input_iter if the next character
+    is not part of the quantifier.
+    """
+    if ch in "*?+":
+        try:
+            ch2, escaped = next(input_iter)
+        except StopIteration:
+            ch2 = None
+        if ch2 == "?":
+            ch2 = None
+        if ch == "+":
+            return 1, ch2
+        return 0, ch2
+
+    quant = []
+    while ch != "}":
+        ch, escaped = next(input_iter)
+        quant.append(ch)
+    quant = quant[:-1]
+    values = "".join(quant).split(",")
+
+    # Consume the trailing '?', if necessary.
+    try:
+        ch, escaped = next(input_iter)
+    except StopIteration:
+        ch = None
+    if ch == "?":
+        ch = None
+    return int(values[0]), ch
+
+
+def contains(source, inst):
+    """
+    Return True if the "source" contains an instance of "inst". False,
+    otherwise.
+    """
+    if isinstance(source, inst):
+        return True
+    if isinstance(source, NonCapture):
+        for elt in source:
+            if contains(elt, inst):
+                return True
+    return False
+
+
+def flatten_result(source):
+    """
+    Turn the given source sequence into a list of reg-exp possibilities and
+    their arguments. Return a list of strings and a list of argument lists.
+    Each of the two lists will be of the same length.
+    """
+    if source is None:
+        return [""], [[]]
+    if isinstance(source, Group):
+        if source[1] is None:
+            params = []
+        else:
+            params = [source[1]]
+        return [source[0]], [params]
+    result = [""]
+    result_args = [[]]
+    pos = last = 0
+    for pos, elt in enumerate(source):
+        if isinstance(elt, str):
+            continue
+        piece = "".join(source[last:pos])
+        if isinstance(elt, Group):
+            piece += elt[0]
+            param = elt[1]
+        else:
+            param = None
+        last = pos + 1
+        for i in range(len(result)):
+            result[i] += piece
+            if param:
+                result_args[i].append(param)
+        if isinstance(elt, Choice | NonCapture):
+            if isinstance(elt, NonCapture):
+                elt = [elt]
+            inner_result, inner_args = [], []
+            for item in elt:
+                res, args = flatten_result(item)
+                inner_result.extend(res)
+                inner_args.extend(args)
+            new_result = []
+            new_args = []
+            for item, args in zip(result, result_args):
+                for i_item, i_args in zip(inner_result, inner_args):
+                    new_result.append(item + i_item)
+                    new_args.append(args[:] + i_args)
+            result = new_result
+            result_args = new_args
+    if pos >= last:
+        piece = "".join(source[last:])
+        for i in range(len(result)):
+            result[i] += piece
+    return result, result_args
+
+
+def _lazy_re_compile(regex, flags=0):
+    """Lazily compile a regex with flags."""
+
+    def _compile():
+        # Compile the regex if it was not passed pre-compiled.
+        if isinstance(regex, str | bytes):
+            return re.compile(regex, flags)
+        else:
+            assert not flags, "flags must be empty if regex is passed pre-compiled"
+            return regex
+
+    return SimpleLazyObject(_compile)

plain/utils/safestring.py

@@ -0,0 +1,72 @@
+"""
+Functions for working with "safe strings": strings that can be displayed safely
+without further escaping in HTML. Marking something as a "safe string" means
+that the producer of the string has already turned characters that should not
+be interpreted by the HTML engine (e.g. '<') into the appropriate entities.
+"""
+
+from functools import wraps
+
+from plain.utils.functional import keep_lazy
+
+
+class SafeData:
+    __slots__ = ()
+
+    def __html__(self):
+        """
+        Return the html representation of a string for interoperability.
+
+        This allows other template engines to understand Plain's SafeData.
+        """
+        return self
+
+
+class SafeString(str, SafeData):
+    """
+    A str subclass that has been specifically marked as "safe" for HTML output
+    purposes.
+    """
+
+    __slots__ = ()
+
+    def __add__(self, rhs):
+        """
+        Concatenating a safe string with another safe bytestring or
+        safe string is safe. Otherwise, the result is no longer safe.
+        """
+        t = super().__add__(rhs)
+        if isinstance(rhs, SafeData):
+            return SafeString(t)
+        return t
+
+    def __str__(self):
+        return self
+
+
+SafeText = SafeString  # For backwards compatibility since Plain 2.0.
+
+
+def _safety_decorator(safety_marker, func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        return safety_marker(func(*args, **kwargs))
+
+    return wrapper
+
+
+@keep_lazy(SafeString)
+def mark_safe(s):
+    """
+    Explicitly mark a string as safe for (HTML) output purposes. The returned
+    object can be used everywhere a string is appropriate.
+
+    If used on a method as a decorator, mark the returned data as safe.
+
+    Can be called multiple times on a single string.
+    """
+    if hasattr(s, "__html__"):
+        return s
+    if callable(s):
+        return _safety_decorator(mark_safe, s)
+    return SafeString(s)

plain/utils/termcolors.py

@@ -0,0 +1,221 @@
+"""
+termcolors.py
+"""
+
+color_names = ("black", "red", "green", "yellow", "blue", "magenta", "cyan", "white")
+foreground = {color_names[x]: "3%s" % x for x in range(8)}
+background = {color_names[x]: "4%s" % x for x in range(8)}
+
+RESET = "0"
+opt_dict = {
+    "bold": "1",
+    "underscore": "4",
+    "blink": "5",
+    "reverse": "7",
+    "conceal": "8",
+}
+
+
+def colorize(text="", opts=(), **kwargs):
+    """
+    Return your text, enclosed in ANSI graphics codes.
+
+    Depends on the keyword arguments 'fg' and 'bg', and the contents of
+    the opts tuple/list.
+
+    Return the RESET code if no parameters are given.
+
+    Valid colors:
+        'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'
+
+    Valid options:
+        'bold'
+        'underscore'
+        'blink'
+        'reverse'
+        'conceal'
+        'noreset' - string will not be auto-terminated with the RESET code
+
+    Examples:
+        colorize('hello', fg='red', bg='blue', opts=('blink',))
+        colorize()
+        colorize('goodbye', opts=('underscore',))
+        print(colorize('first line', fg='red', opts=('noreset',)))
+        print('this should be red too')
+        print(colorize('and so should this'))
+        print('this should not be red')
+    """
+    code_list = []
+    if text == "" and len(opts) == 1 and opts[0] == "reset":
+        return "\x1b[%sm" % RESET
+    for k, v in kwargs.items():
+        if k == "fg":
+            code_list.append(foreground[v])
+        elif k == "bg":
+            code_list.append(background[v])
+    for o in opts:
+        if o in opt_dict:
+            code_list.append(opt_dict[o])
+    if "noreset" not in opts:
+        text = "{}\x1b[{}m".format(text or "", RESET)
+    return "{}{}".format(("\x1b[%sm" % ";".join(code_list)), text or "")
+
+
+def make_style(opts=(), **kwargs):
+    """
+    Return a function with default parameters for colorize()
+
+    Example:
+        bold_red = make_style(opts=('bold',), fg='red')
+        print(bold_red('hello'))
+        KEYWORD = make_style(fg='yellow')
+        COMMENT = make_style(fg='blue', opts=('bold',))
+    """
+    return lambda text: colorize(text, opts, **kwargs)
+
+
+NOCOLOR_PALETTE = "nocolor"
+DARK_PALETTE = "dark"
+LIGHT_PALETTE = "light"
+
+PALETTES = {
+    NOCOLOR_PALETTE: {
+        "ERROR": {},
+        "SUCCESS": {},
+        "WARNING": {},
+        "NOTICE": {},
+        "SQL_FIELD": {},
+        "SQL_COLTYPE": {},
+        "SQL_KEYWORD": {},
+        "SQL_TABLE": {},
+        "HTTP_INFO": {},
+        "HTTP_SUCCESS": {},
+        "HTTP_REDIRECT": {},
+        "HTTP_NOT_MODIFIED": {},
+        "HTTP_BAD_REQUEST": {},
+        "HTTP_NOT_FOUND": {},
+        "HTTP_SERVER_ERROR": {},
+        "MIGRATE_HEADING": {},
+        "MIGRATE_LABEL": {},
+    },
+    DARK_PALETTE: {
+        "ERROR": {"fg": "red", "opts": ("bold",)},
+        "SUCCESS": {"fg": "green", "opts": ("bold",)},
+        "WARNING": {"fg": "yellow", "opts": ("bold",)},
+        "NOTICE": {"fg": "red"},
+        "SQL_FIELD": {"fg": "green", "opts": ("bold",)},
+        "SQL_COLTYPE": {"fg": "green"},
+        "SQL_KEYWORD": {"fg": "yellow"},
+        "SQL_TABLE": {"opts": ("bold",)},
+        "HTTP_INFO": {"opts": ("bold",)},
+        "HTTP_SUCCESS": {},
+        "HTTP_REDIRECT": {"fg": "green"},
+        "HTTP_NOT_MODIFIED": {"fg": "cyan"},
+        "HTTP_BAD_REQUEST": {"fg": "red", "opts": ("bold",)},
+        "HTTP_NOT_FOUND": {"fg": "yellow"},
+        "HTTP_SERVER_ERROR": {"fg": "magenta", "opts": ("bold",)},
+        "MIGRATE_HEADING": {"fg": "cyan", "opts": ("bold",)},
+        "MIGRATE_LABEL": {"opts": ("bold",)},
+    },
+    LIGHT_PALETTE: {
+        "ERROR": {"fg": "red", "opts": ("bold",)},
+        "SUCCESS": {"fg": "green", "opts": ("bold",)},
+        "WARNING": {"fg": "yellow", "opts": ("bold",)},
+        "NOTICE": {"fg": "red"},
+        "SQL_FIELD": {"fg": "green", "opts": ("bold",)},
+        "SQL_COLTYPE": {"fg": "green"},
+        "SQL_KEYWORD": {"fg": "blue"},
+        "SQL_TABLE": {"opts": ("bold",)},
+        "HTTP_INFO": {"opts": ("bold",)},
+        "HTTP_SUCCESS": {},
+        "HTTP_REDIRECT": {"fg": "green", "opts": ("bold",)},
+        "HTTP_NOT_MODIFIED": {"fg": "green"},
+        "HTTP_BAD_REQUEST": {"fg": "red", "opts": ("bold",)},
+        "HTTP_NOT_FOUND": {"fg": "red"},
+        "HTTP_SERVER_ERROR": {"fg": "magenta", "opts": ("bold",)},
+        "MIGRATE_HEADING": {"fg": "cyan", "opts": ("bold",)},
+        "MIGRATE_LABEL": {"opts": ("bold",)},
+    },
+}
+DEFAULT_PALETTE = DARK_PALETTE
+
+
+def parse_color_setting(config_string):
+    """Parse a DJANGO_COLORS environment variable to produce the system palette
+
+    The general form of a palette definition is:
+
+        "palette;role=fg;role=fg/bg;role=fg,option,option;role=fg/bg,option,option"
+
+    where:
+        palette is a named palette; one of 'light', 'dark', or 'nocolor'.
+        role is a named style used by Django
+        fg is a foreground color.
+        bg is a background color.
+        option is a display options.
+
+    Specifying a named palette is the same as manually specifying the individual
+    definitions for each role. Any individual definitions following the palette
+    definition will augment the base palette definition.
+
+    Valid roles:
+        'error', 'success', 'warning', 'notice', 'sql_field', 'sql_coltype',
+        'sql_keyword', 'sql_table', 'http_info', 'http_success',
+        'http_redirect', 'http_not_modified', 'http_bad_request',
+        'http_not_found', 'http_server_error', 'migrate_heading',
+        'migrate_label'
+
+    Valid colors:
+        'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'
+
+    Valid options:
+        'bold', 'underscore', 'blink', 'reverse', 'conceal', 'noreset'
+    """
+    if not config_string:
+        return PALETTES[DEFAULT_PALETTE]
+
+    # Split the color configuration into parts
+    parts = config_string.lower().split(";")
+    palette = PALETTES[NOCOLOR_PALETTE].copy()
+    for part in parts:
+        if part in PALETTES:
+            # A default palette has been specified
+            palette.update(PALETTES[part])
+        elif "=" in part:
+            # Process a palette defining string
+            definition = {}
+
+            # Break the definition into the role,
+            # plus the list of specific instructions.
+            # The role must be in upper case
+            role, instructions = part.split("=")
+            role = role.upper()
+
+            styles = instructions.split(",")
+            styles.reverse()
+
+            # The first instruction can contain a slash
+            # to break apart fg/bg.
+            colors = styles.pop().split("/")
+            colors.reverse()
+            fg = colors.pop()
+            if fg in color_names:
+                definition["fg"] = fg
+            if colors and colors[-1] in color_names:
+                definition["bg"] = colors[-1]
+
+            # All remaining instructions are options
+            opts = tuple(s for s in styles if s in opt_dict)
+            if opts:
+                definition["opts"] = opts
+
+            # The nocolor palette has all available roles.
+            # Use that palette as the basis for determining
+            # if the role is valid.
+            if role in PALETTES[NOCOLOR_PALETTE] and definition:
+                palette[role] = definition
+
+    # If there are no colors specified, return the empty palette.
+    if palette == PALETTES[NOCOLOR_PALETTE]:
+        return None
+    return palette