plain 0.1.0__py3-none-any.whl

plain/utils/text.py

@@ -0,0 +1,518 @@
+import gzip
+import re
+import secrets
+import unicodedata
+from gzip import GzipFile
+from gzip import compress as gzip_compress
+from io import BytesIO
+
+from plain.exceptions import SuspiciousFileOperation
+from plain.utils.functional import SimpleLazyObject, keep_lazy_text, lazy
+from plain.utils.regex_helper import _lazy_re_compile
+
+
+@keep_lazy_text
+def capfirst(x):
+    """Capitalize the first letter of a string."""
+    if not x:
+        return x
+    if not isinstance(x, str):
+        x = str(x)
+    return x[0].upper() + x[1:]
+
+
+# Set up regular expressions
+re_words = _lazy_re_compile(r"<[^>]+?>|([^<>\s]+)", re.S)
+re_chars = _lazy_re_compile(r"<[^>]+?>|(.)", re.S)
+re_tag = _lazy_re_compile(r"<(/)?(\S+?)(?:(\s*/)|\s.*?)?>", re.S)
+re_newlines = _lazy_re_compile(r"\r\n|\r")  # Used in normalize_newlines
+re_camel_case = _lazy_re_compile(r"(((?<=[a-z])[A-Z])|([A-Z](?![A-Z]|$)))")
+
+
+@keep_lazy_text
+def wrap(text, width):
+    """
+    A word-wrap function that preserves existing line breaks. Expects that
+    existing line breaks are posix newlines.
+
+    Preserve all white space except added line breaks consume the space on
+    which they break the line.
+
+    Don't wrap long words, thus the output text may have lines longer than
+    ``width``.
+    """
+
+    def _generator():
+        for line in text.splitlines(True):  # True keeps trailing linebreaks
+            max_width = min((line.endswith("\n") and width + 1 or width), width)
+            while len(line) > max_width:
+                space = line[: max_width + 1].rfind(" ") + 1
+                if space == 0:
+                    space = line.find(" ") + 1
+                    if space == 0:
+                        yield line
+                        line = ""
+                        break
+                yield "%s\n" % line[: space - 1]
+                line = line[space:]
+                max_width = min((line.endswith("\n") and width + 1 or width), width)
+            if line:
+                yield line
+
+    return "".join(_generator())
+
+
+class Truncator(SimpleLazyObject):
+    """
+    An object used to truncate text, either by characters or words.
+    """
+
+    def __init__(self, text):
+        super().__init__(lambda: str(text))
+
+    def add_truncation_text(self, text, truncate=None):
+        if truncate is None:
+            truncate = "%(truncated_text)s…"
+        if "%(truncated_text)s" in truncate:
+            return truncate % {"truncated_text": text}
+        # The truncation text didn't contain the %(truncated_text)s string
+        # replacement argument so just append it to the text.
+        if text.endswith(truncate):
+            # But don't append the truncation text if the current text already
+            # ends in this.
+            return text
+        return f"{text}{truncate}"
+
+    def chars(self, num, truncate=None, html=False):
+        """
+        Return the text truncated to be no longer than the specified number
+        of characters.
+
+        `truncate` specifies what should be used to notify that the string has
+        been truncated, defaulting to a translatable string of an ellipsis.
+        """
+        self._setup()
+        length = int(num)
+        text = unicodedata.normalize("NFC", self._wrapped)
+
+        # Calculate the length to truncate to (max length - end_text length)
+        truncate_len = length
+        for char in self.add_truncation_text("", truncate):
+            if not unicodedata.combining(char):
+                truncate_len -= 1
+                if truncate_len == 0:
+                    break
+        if html:
+            return self._truncate_html(length, truncate, text, truncate_len, False)
+        return self._text_chars(length, truncate, text, truncate_len)
+
+    def _text_chars(self, length, truncate, text, truncate_len):
+        """Truncate a string after a certain number of chars."""
+        s_len = 0
+        end_index = None
+        for i, char in enumerate(text):
+            if unicodedata.combining(char):
+                # Don't consider combining characters
+                # as adding to the string length
+                continue
+            s_len += 1
+            if end_index is None and s_len > truncate_len:
+                end_index = i
+            if s_len > length:
+                # Return the truncated string
+                return self.add_truncation_text(text[: end_index or 0], truncate)
+
+        # Return the original string since no truncation was necessary
+        return text
+
+    def words(self, num, truncate=None, html=False):
+        """
+        Truncate a string after a certain number of words. `truncate` specifies
+        what should be used to notify that the string has been truncated,
+        defaulting to ellipsis.
+        """
+        self._setup()
+        length = int(num)
+        if html:
+            return self._truncate_html(length, truncate, self._wrapped, length, True)
+        return self._text_words(length, truncate)
+
+    def _text_words(self, length, truncate):
+        """
+        Truncate a string after a certain number of words.
+
+        Strip newlines in the string.
+        """
+        words = self._wrapped.split()
+        if len(words) > length:
+            words = words[:length]
+            return self.add_truncation_text(" ".join(words), truncate)
+        return " ".join(words)
+
+    def _truncate_html(self, length, truncate, text, truncate_len, words):
+        """
+        Truncate HTML to a certain number of chars (not counting tags and
+        comments), or, if words is True, then to a certain number of words.
+        Close opened tags if they were correctly closed in the given HTML.
+
+        Preserve newlines in the HTML.
+        """
+        if words and length <= 0:
+            return ""
+
+        html4_singlets = (
+            "br",
+            "col",
+            "link",
+            "base",
+            "img",
+            "param",
+            "area",
+            "hr",
+            "input",
+        )
+
+        # Count non-HTML chars/words and keep note of open tags
+        pos = 0
+        end_text_pos = 0
+        current_len = 0
+        open_tags = []
+
+        regex = re_words if words else re_chars
+
+        while current_len <= length:
+            m = regex.search(text, pos)
+            if not m:
+                # Checked through whole string
+                break
+            pos = m.end(0)
+            if m[1]:
+                # It's an actual non-HTML word or char
+                current_len += 1
+                if current_len == truncate_len:
+                    end_text_pos = pos
+                continue
+            # Check for tag
+            tag = re_tag.match(m[0])
+            if not tag or current_len >= truncate_len:
+                # Don't worry about non tags or tags after our truncate point
+                continue
+            closing_tag, tagname, self_closing = tag.groups()
+            # Element names are always case-insensitive
+            tagname = tagname.lower()
+            if self_closing or tagname in html4_singlets:
+                pass
+            elif closing_tag:
+                # Check for match in open tags list
+                try:
+                    i = open_tags.index(tagname)
+                except ValueError:
+                    pass
+                else:
+                    # SGML: An end tag closes, back to the matching start tag,
+                    # all unclosed intervening start tags with omitted end tags
+                    open_tags = open_tags[i + 1 :]
+            else:
+                # Add it to the start of the open tags list
+                open_tags.insert(0, tagname)
+
+        if current_len <= length:
+            return text
+        out = text[:end_text_pos]
+        truncate_text = self.add_truncation_text("", truncate)
+        if truncate_text:
+            out += truncate_text
+        # Close any tags still open
+        for tag in open_tags:
+            out += "</%s>" % tag
+        # Return string
+        return out
+
+
+@keep_lazy_text
+def get_valid_filename(name):
+    """
+    Return the given string converted to a string that can be used for a clean
+    filename. Remove leading and trailing spaces; convert other spaces to
+    underscores; and remove anything that is not an alphanumeric, dash,
+    underscore, or dot.
+    >>> get_valid_filename("john's portrait in 2004.jpg")
+    'johns_portrait_in_2004.jpg'
+    """
+    s = str(name).strip().replace(" ", "_")
+    s = re.sub(r"(?u)[^-\w.]", "", s)
+    if s in {"", ".", ".."}:
+        raise SuspiciousFileOperation("Could not derive file name from '%s'" % name)
+    return s
+
+
+@keep_lazy_text
+def get_text_list(list_, last_word="or"):
+    """
+    >>> get_text_list(['a', 'b', 'c', 'd'])
+    'a, b, c or d'
+    >>> get_text_list(['a', 'b', 'c'], 'and')
+    'a, b and c'
+    >>> get_text_list(['a', 'b'], 'and')
+    'a and b'
+    >>> get_text_list(['a'])
+    'a'
+    >>> get_text_list([])
+    ''
+    """
+    if not list_:
+        return ""
+    if len(list_) == 1:
+        return str(list_[0])
+    return "{} {} {}".format(
+        # Translators: This string is used as a separator between list elements
+        ", ".join(str(i) for i in list_[:-1]),
+        str(last_word),
+        str(list_[-1]),
+    )
+
+
+@keep_lazy_text
+def normalize_newlines(text):
+    """Normalize CRLF and CR newlines to just LF."""
+    return re_newlines.sub("\n", str(text))
+
+
+@keep_lazy_text
+def phone2numeric(phone):
+    """Convert a phone number with letters into its numeric equivalent."""
+    char2number = {
+        "a": "2",
+        "b": "2",
+        "c": "2",
+        "d": "3",
+        "e": "3",
+        "f": "3",
+        "g": "4",
+        "h": "4",
+        "i": "4",
+        "j": "5",
+        "k": "5",
+        "l": "5",
+        "m": "6",
+        "n": "6",
+        "o": "6",
+        "p": "7",
+        "q": "7",
+        "r": "7",
+        "s": "7",
+        "t": "8",
+        "u": "8",
+        "v": "8",
+        "w": "9",
+        "x": "9",
+        "y": "9",
+        "z": "9",
+    }
+    return "".join(char2number.get(c, c) for c in phone.lower())
+
+
+def _get_random_filename(max_random_bytes):
+    return b"a" * secrets.randbelow(max_random_bytes)
+
+
+def compress_string(s, *, max_random_bytes=None):
+    compressed_data = gzip_compress(s, compresslevel=6, mtime=0)
+
+    if not max_random_bytes:
+        return compressed_data
+
+    compressed_view = memoryview(compressed_data)
+    header = bytearray(compressed_view[:10])
+    header[3] = gzip.FNAME
+
+    filename = _get_random_filename(max_random_bytes) + b"\x00"
+
+    return bytes(header) + filename + compressed_view[10:]
+
+
+class StreamingBuffer(BytesIO):
+    def read(self):
+        ret = self.getvalue()
+        self.seek(0)
+        self.truncate()
+        return ret
+
+
+# Like compress_string, but for iterators of strings.
+def compress_sequence(sequence, *, max_random_bytes=None):
+    buf = StreamingBuffer()
+    filename = _get_random_filename(max_random_bytes) if max_random_bytes else None
+    with GzipFile(
+        filename=filename, mode="wb", compresslevel=6, fileobj=buf, mtime=0
+    ) as zfile:
+        # Output headers...
+        yield buf.read()
+        for item in sequence:
+            zfile.write(item)
+            data = buf.read()
+            if data:
+                yield data
+    yield buf.read()
+
+
+# Expression to match some_token and some_token="with spaces" (and similarly
+# for single-quoted strings).
+smart_split_re = _lazy_re_compile(
+    r"""
+    ((?:
+        [^\s'"]*
+        (?:
+            (?:"(?:[^"\\]|\\.)*" | '(?:[^'\\]|\\.)*')
+            [^\s'"]*
+        )+
+    ) | \S+)
+""",
+    re.VERBOSE,
+)
+
+
+def smart_split(text):
+    r"""
+    Generator that splits a string by spaces, leaving quoted phrases together.
+    Supports both single and double quotes, and supports escaping quotes with
+    backslashes. In the output, strings will keep their initial and trailing
+    quote marks and escaped quotes will remain escaped (the results can then
+    be further processed with unescape_string_literal()).
+
+    >>> list(smart_split(r'This is "a person\'s" test.'))
+    ['This', 'is', '"a person\\\'s"', 'test.']
+    >>> list(smart_split(r"Another 'person\'s' test."))
+    ['Another', "'person\\'s'", 'test.']
+    >>> list(smart_split(r'A "\"funky\" style" test.'))
+    ['A', '"\\"funky\\" style"', 'test.']
+    """
+    for bit in smart_split_re.finditer(str(text)):
+        yield bit[0]
+
+
+@keep_lazy_text
+def unescape_string_literal(s):
+    r"""
+    Convert quoted string literals to unquoted strings with escaped quotes and
+    backslashes unquoted::
+
+        >>> unescape_string_literal('"abc"')
+        'abc'
+        >>> unescape_string_literal("'abc'")
+        'abc'
+        >>> unescape_string_literal('"a \"bc\""')
+        'a "bc"'
+        >>> unescape_string_literal("'\'ab\' c'")
+        "'ab' c"
+    """
+    if not s or s[0] not in "\"'" or s[-1] != s[0]:
+        raise ValueError("Not a string literal: %r" % s)
+    quote = s[0]
+    return s[1:-1].replace(r"\%s" % quote, quote).replace(r"\\", "\\")
+
+
+@keep_lazy_text
+def slugify(value, allow_unicode=False):
+    """
+    Convert to ASCII if 'allow_unicode' is False. Convert spaces or repeated
+    dashes to single dashes. Remove characters that aren't alphanumerics,
+    underscores, or hyphens. Convert to lowercase. Also strip leading and
+    trailing whitespace, dashes, and underscores.
+    """
+    value = str(value)
+    if allow_unicode:
+        value = unicodedata.normalize("NFKC", value)
+    else:
+        value = (
+            unicodedata.normalize("NFKD", value)
+            .encode("ascii", "ignore")
+            .decode("ascii")
+        )
+    value = re.sub(r"[^\w\s-]", "", value.lower())
+    return re.sub(r"[-\s]+", "-", value).strip("-_")
+
+
+def camel_case_to_spaces(value):
+    """
+    Split CamelCase and convert to lowercase. Strip surrounding whitespace.
+    """
+    return re_camel_case.sub(r" \1", value).strip().lower()
+
+
+def _format_lazy(format_string, *args, **kwargs):
+    """
+    Apply str.format() on 'format_string' where format_string, args,
+    and/or kwargs might be lazy.
+    """
+    return format_string.format(*args, **kwargs)
+
+
+def pluralize(singular, plural, number):
+    if number == 1:
+        return singular
+    else:
+        return plural
+
+
+def pluralize_lazy(singular, plural, number):
+    def _lazy_number_unpickle(func, resultclass, number, kwargs):
+        return lazy_number(func, resultclass, number=number, **kwargs)
+
+    def lazy_number(func, resultclass, number=None, **kwargs):
+        if isinstance(number, int):
+            kwargs["number"] = number
+            proxy = lazy(func, resultclass)(**kwargs)
+        else:
+            original_kwargs = kwargs.copy()
+
+            class NumberAwareString(resultclass):
+                def __bool__(self):
+                    return bool(kwargs["singular"])
+
+                def _get_number_value(self, values):
+                    try:
+                        return values[number]
+                    except KeyError:
+                        raise KeyError(
+                            "Your dictionary lacks key '%s'. Please provide "
+                            "it, because it is required to determine whether "
+                            "string is singular or plural." % number
+                        )
+
+                def _translate(self, number_value):
+                    kwargs["number"] = number_value
+                    return func(**kwargs)
+
+                def format(self, *args, **kwargs):
+                    number_value = (
+                        self._get_number_value(kwargs) if kwargs and number else args[0]
+                    )
+                    return self._translate(number_value).format(*args, **kwargs)
+
+                def __mod__(self, rhs):
+                    if isinstance(rhs, dict) and number:
+                        number_value = self._get_number_value(rhs)
+                    else:
+                        number_value = rhs
+                    translated = self._translate(number_value)
+                    try:
+                        translated %= rhs
+                    except TypeError:
+                        # String doesn't contain a placeholder for the number.
+                        pass
+                    return translated
+
+            proxy = lazy(lambda **kwargs: NumberAwareString(), NumberAwareString)(
+                **kwargs
+            )
+            proxy.__reduce__ = lambda: (
+                _lazy_number_unpickle,
+                (func, resultclass, number, original_kwargs),
+            )
+        return proxy
+
+    return lazy_number(pluralize, str, singular=singular, plural=plural, number=number)
+
+
+format_lazy = lazy(_format_lazy, str)

plain/utils/timesince.py

@@ -0,0 +1,138 @@
+import datetime
+
+from plain.utils.html import avoid_wrapping
+from plain.utils.text import pluralize_lazy
+from plain.utils.timezone import is_aware
+
+TIME_STRINGS = {
+    "year": pluralize_lazy("%(num)d year", "%(num)d years", "num"),
+    "month": pluralize_lazy("%(num)d month", "%(num)d months", "num"),
+    "week": pluralize_lazy("%(num)d week", "%(num)d weeks", "num"),
+    "day": pluralize_lazy("%(num)d day", "%(num)d days", "num"),
+    "hour": pluralize_lazy("%(num)d hour", "%(num)d hours", "num"),
+    "minute": pluralize_lazy("%(num)d minute", "%(num)d minutes", "num"),
+}
+
+TIME_STRINGS_KEYS = list(TIME_STRINGS.keys())
+
+TIME_CHUNKS = [
+    60 * 60 * 24 * 7,  # week
+    60 * 60 * 24,  # day
+    60 * 60,  # hour
+    60,  # minute
+]
+
+MONTHS_DAYS = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+
+
+def timesince(d, now=None, reversed=False, time_strings=None, depth=2):
+    """
+    Take two datetime objects and return the time between d and now as a nicely
+    formatted string, e.g. "10 minutes". If d occurs after now, return
+    "0 minutes".
+
+    Units used are years, months, weeks, days, hours, and minutes.
+    Seconds and microseconds are ignored.
+
+    The algorithm takes into account the varying duration of years and months.
+    There is exactly "1 year, 1 month" between 2013/02/10 and 2014/03/10,
+    but also between 2007/08/10 and 2008/09/10 despite the delta being 393 days
+    in the former case and 397 in the latter.
+
+    Up to `depth` adjacent units will be displayed.  For example,
+    "2 weeks, 3 days" and "1 year, 3 months" are possible outputs, but
+    "2 weeks, 3 hours" and "1 year, 5 days" are not.
+
+    `time_strings` is an optional dict of strings to replace the default
+    TIME_STRINGS dict.
+
+    `depth` is an optional integer to control the number of adjacent time
+    units returned.
+
+    Originally adapted from
+    https://web.archive.org/web/20060617175230/http://blog.natbat.co.uk/archive/2003/Jun/14/time_since
+    Modified to improve results for years and months.
+    """
+    if time_strings is None:
+        time_strings = TIME_STRINGS
+    if depth <= 0:
+        raise ValueError("depth must be greater than 0.")
+    # Convert datetime.date to datetime.datetime for comparison.
+    if not isinstance(d, datetime.datetime):
+        d = datetime.datetime(d.year, d.month, d.day)
+    if now and not isinstance(now, datetime.datetime):
+        now = datetime.datetime(now.year, now.month, now.day)
+
+    now = now or datetime.datetime.now(datetime.timezone.utc if is_aware(d) else None)
+
+    if reversed:
+        d, now = now, d
+    delta = now - d
+
+    # Ignore microseconds.
+    since = delta.days * 24 * 60 * 60 + delta.seconds
+    if since <= 0:
+        # d is in the future compared to now, stop processing.
+        return avoid_wrapping(time_strings["minute"] % {"num": 0})
+
+    # Get years and months.
+    total_months = (now.year - d.year) * 12 + (now.month - d.month)
+    if d.day > now.day or (d.day == now.day and d.time() > now.time()):
+        total_months -= 1
+    years, months = divmod(total_months, 12)
+
+    # Calculate the remaining time.
+    # Create a "pivot" datetime shifted from d by years and months, then use
+    # that to determine the other parts.
+    if years or months:
+        pivot_year = d.year + years
+        pivot_month = d.month + months
+        if pivot_month > 12:
+            pivot_month -= 12
+            pivot_year += 1
+        pivot = datetime.datetime(
+            pivot_year,
+            pivot_month,
+            min(MONTHS_DAYS[pivot_month - 1], d.day),
+            d.hour,
+            d.minute,
+            d.second,
+            tzinfo=d.tzinfo,
+        )
+    else:
+        pivot = d
+    remaining_time = (now - pivot).total_seconds()
+    partials = [years, months]
+    for chunk in TIME_CHUNKS:
+        count = int(remaining_time // chunk)
+        partials.append(count)
+        remaining_time -= chunk * count
+
+    # Find the first non-zero part (if any) and then build the result, until
+    # depth.
+    i = 0
+    for i, value in enumerate(partials):
+        if value != 0:
+            break
+    else:
+        return avoid_wrapping(time_strings["minute"] % {"num": 0})
+
+    result = []
+    current_depth = 0
+    while i < len(TIME_STRINGS_KEYS) and current_depth < depth:
+        value = partials[i]
+        if value == 0:
+            break
+        name = TIME_STRINGS_KEYS[i]
+        result.append(avoid_wrapping(time_strings[name] % {"num": value}))
+        current_depth += 1
+        i += 1
+
+    return ", ".join(result)
+
+
+def timeuntil(d, now=None, time_strings=None, depth=2):
+    """
+    Like timesince, but return a string measuring the time until the given time.
+    """
+    return timesince(d, now, reversed=True, time_strings=time_strings, depth=depth)