plain 0.1.0__py3-none-any.whl

plain/utils/dateparse.py

@@ -0,0 +1,154 @@
+"""Functions to parse datetime objects."""
+
+# We're using regular expressions rather than time.strptime because:
+# - They provide both validation and parsing.
+# - They're more flexible for datetimes.
+# - The date/datetime/time constructors produce friendlier error messages.
+
+import datetime
+
+from plain.utils.regex_helper import _lazy_re_compile
+from plain.utils.timezone import get_fixed_timezone
+
+date_re = _lazy_re_compile(r"(?P<year>\d{4})-(?P<month>\d{1,2})-(?P<day>\d{1,2})$")
+
+time_re = _lazy_re_compile(
+    r"(?P<hour>\d{1,2}):(?P<minute>\d{1,2})"
+    r"(?::(?P<second>\d{1,2})(?:[\.,](?P<microsecond>\d{1,6})\d{0,6})?)?$"
+)
+
+datetime_re = _lazy_re_compile(
+    r"(?P<year>\d{4})-(?P<month>\d{1,2})-(?P<day>\d{1,2})"
+    r"[T ](?P<hour>\d{1,2}):(?P<minute>\d{1,2})"
+    r"(?::(?P<second>\d{1,2})(?:[\.,](?P<microsecond>\d{1,6})\d{0,6})?)?"
+    r"\s*(?P<tzinfo>Z|[+-]\d{2}(?::?\d{2})?)?$"
+)
+
+standard_duration_re = _lazy_re_compile(
+    r"^"
+    r"(?:(?P<days>-?\d+) (days?, )?)?"
+    r"(?P<sign>-?)"
+    r"((?:(?P<hours>\d+):)(?=\d+:\d+))?"
+    r"(?:(?P<minutes>\d+):)?"
+    r"(?P<seconds>\d+)"
+    r"(?:[\.,](?P<microseconds>\d{1,6})\d{0,6})?"
+    r"$"
+)
+
+# Support the sections of ISO 8601 date representation that are accepted by
+# timedelta
+iso8601_duration_re = _lazy_re_compile(
+    r"^(?P<sign>[-+]?)"
+    r"P"
+    r"(?:(?P<days>\d+([\.,]\d+)?)D)?"
+    r"(?:T"
+    r"(?:(?P<hours>\d+([\.,]\d+)?)H)?"
+    r"(?:(?P<minutes>\d+([\.,]\d+)?)M)?"
+    r"(?:(?P<seconds>\d+([\.,]\d+)?)S)?"
+    r")?"
+    r"$"
+)
+
+# Support PostgreSQL's day-time interval format, e.g. "3 days 04:05:06". The
+# year-month and mixed intervals cannot be converted to a timedelta and thus
+# aren't accepted.
+postgres_interval_re = _lazy_re_compile(
+    r"^"
+    r"(?:(?P<days>-?\d+) (days? ?))?"
+    r"(?:(?P<sign>[-+])?"
+    r"(?P<hours>\d+):"
+    r"(?P<minutes>\d\d):"
+    r"(?P<seconds>\d\d)"
+    r"(?:\.(?P<microseconds>\d{1,6}))?"
+    r")?$"
+)
+
+
+def parse_date(value):
+    """Parse a string and return a datetime.date.
+
+    Raise ValueError if the input is well formatted but not a valid date.
+    Return None if the input isn't well formatted.
+    """
+    try:
+        return datetime.date.fromisoformat(value)
+    except ValueError:
+        if match := date_re.match(value):
+            kw = {k: int(v) for k, v in match.groupdict().items()}
+            return datetime.date(**kw)
+
+
+def parse_time(value):
+    """Parse a string and return a datetime.time.
+
+    This function doesn't support time zone offsets.
+
+    Raise ValueError if the input is well formatted but not a valid time.
+    Return None if the input isn't well formatted, in particular if it
+    contains an offset.
+    """
+    try:
+        # The fromisoformat() method takes time zone info into account and
+        # returns a time with a tzinfo component, if possible. However, there
+        # are no circumstances where aware datetime.time objects make sense, so
+        # remove the time zone offset.
+        return datetime.time.fromisoformat(value).replace(tzinfo=None)
+    except ValueError:
+        if match := time_re.match(value):
+            kw = match.groupdict()
+            kw["microsecond"] = kw["microsecond"] and kw["microsecond"].ljust(6, "0")
+            kw = {k: int(v) for k, v in kw.items() if v is not None}
+            return datetime.time(**kw)
+
+
+def parse_datetime(value):
+    """Parse a string and return a datetime.datetime.
+
+    This function supports time zone offsets. When the input contains one,
+    the output uses a timezone with a fixed offset from UTC.
+
+    Raise ValueError if the input is well formatted but not a valid datetime.
+    Return None if the input isn't well formatted.
+    """
+    try:
+        return datetime.datetime.fromisoformat(value)
+    except ValueError:
+        if match := datetime_re.match(value):
+            kw = match.groupdict()
+            kw["microsecond"] = kw["microsecond"] and kw["microsecond"].ljust(6, "0")
+            tzinfo = kw.pop("tzinfo")
+            if tzinfo == "Z":
+                tzinfo = datetime.timezone.utc
+            elif tzinfo is not None:
+                offset_mins = int(tzinfo[-2:]) if len(tzinfo) > 3 else 0
+                offset = 60 * int(tzinfo[1:3]) + offset_mins
+                if tzinfo[0] == "-":
+                    offset = -offset
+                tzinfo = get_fixed_timezone(offset)
+            kw = {k: int(v) for k, v in kw.items() if v is not None}
+            return datetime.datetime(**kw, tzinfo=tzinfo)
+
+
+def parse_duration(value):
+    """Parse a duration string and return a datetime.timedelta.
+
+    The preferred format for durations in Plain is '%d %H:%M:%S.%f'.
+
+    Also supports ISO 8601 representation and PostgreSQL's day-time interval
+    format.
+    """
+    match = (
+        standard_duration_re.match(value)
+        or iso8601_duration_re.match(value)
+        or postgres_interval_re.match(value)
+    )
+    if match:
+        kw = match.groupdict()
+        sign = -1 if kw.pop("sign", "+") == "-" else 1
+        if kw.get("microseconds"):
+            kw["microseconds"] = kw["microseconds"].ljust(6, "0")
+        kw = {k: float(v.replace(",", ".")) for k, v in kw.items() if v is not None}
+        days = datetime.timedelta(kw.pop("days", 0.0) or 0.0)
+        if match.re == iso8601_duration_re:
+            days *= sign
+        return days + sign * datetime.timedelta(**kw)

plain/utils/dates.py

@@ -0,0 +1,76 @@
+"Commonly-used date structures"
+
+WEEKDAYS = {
+    0: "Monday",
+    1: "Tuesday",
+    2: "Wednesday",
+    3: "Thursday",
+    4: "Friday",
+    5: "Saturday",
+    6: "Sunday",
+}
+WEEKDAYS_ABBR = {
+    0: "Mon",
+    1: "Tue",
+    2: "Wed",
+    3: "Thu",
+    4: "Fri",
+    5: "Sat",
+    6: "Sun",
+}
+MONTHS = {
+    1: "January",
+    2: "February",
+    3: "March",
+    4: "April",
+    5: "May",
+    6: "June",
+    7: "July",
+    8: "August",
+    9: "September",
+    10: "October",
+    11: "November",
+    12: "December",
+}
+MONTHS_3 = {
+    1: "jan",
+    2: "feb",
+    3: "mar",
+    4: "apr",
+    5: "may",
+    6: "jun",
+    7: "jul",
+    8: "aug",
+    9: "sep",
+    10: "oct",
+    11: "nov",
+    12: "dec",
+}
+MONTHS_AP = {  # month names in Associated Press style
+    1: "Jan.",
+    2: "Feb.",
+    3: "March",
+    4: "April",
+    5: "May",
+    6: "June",
+    7: "July",
+    8: "Aug.",
+    9: "Sept.",
+    10: "Oct.",
+    11: "Nov.",
+    12: "Dec.",
+}
+MONTHS_ALT = {  # required for long date representation by some locales
+    1: "January",
+    2: "February",
+    3: "March",
+    4: "April",
+    5: "May",
+    6: "June",
+    7: "July",
+    8: "August",
+    9: "September",
+    10: "October",
+    11: "November",
+    12: "December",
+}

plain/utils/deconstruct.py

@@ -0,0 +1,54 @@
+from importlib import import_module
+
+
+def deconstructible(*args, path=None):
+    """
+    Class decorator that allows the decorated class to be serialized
+    by the migrations subsystem.
+
+    The `path` kwarg specifies the import path.
+    """
+
+    def decorator(klass):
+        def __new__(cls, *args, **kwargs):
+            # We capture the arguments to make returning them trivial
+            obj = super(klass, cls).__new__(cls)
+            obj._constructor_args = (args, kwargs)
+            return obj
+
+        def deconstruct(obj):
+            """
+            Return a 3-tuple of class import path, positional arguments,
+            and keyword arguments.
+            """
+            # Fallback version
+            if path and type(obj) is klass:
+                module_name, _, name = path.rpartition(".")
+            else:
+                module_name = obj.__module__
+                name = obj.__class__.__name__
+            # Make sure it's actually there and not an inner class
+            module = import_module(module_name)
+            if not hasattr(module, name):
+                raise ValueError(
+                    f"Could not find object {name} in {module_name}.\n"
+                    "Please note that you cannot serialize things like inner "
+                    "classes. Please move the object into the main module "
+                    "body to use migrations."
+                )
+            return (
+                path
+                if path and type(obj) is klass
+                else f"{obj.__class__.__module__}.{name}",
+                obj._constructor_args[0],
+                obj._constructor_args[1],
+            )
+
+        klass.__new__ = staticmethod(__new__)
+        klass.deconstruct = deconstruct
+
+        return klass
+
+    if not args:
+        return decorator
+    return decorator(*args)

plain/utils/decorators.py

@@ -0,0 +1,90 @@
+"Functions that help with dynamically creating decorators for views."
+
+from functools import partial, update_wrapper, wraps
+
+
+class classonlymethod(classmethod):
+    def __get__(self, instance, cls=None):
+        if instance is not None:
+            raise AttributeError(
+                "This method is available only on the class, not on instances."
+            )
+        return super().__get__(instance, cls)
+
+
+def _update_method_wrapper(_wrapper, decorator):
+    # _multi_decorate()'s bound_method isn't available in this scope. Cheat by
+    # using it on a dummy function.
+    @decorator
+    def dummy(*args, **kwargs):
+        pass
+
+    update_wrapper(_wrapper, dummy)
+
+
+def _multi_decorate(decorators, method):
+    """
+    Decorate `method` with one or more function decorators. `decorators` can be
+    a single decorator or an iterable of decorators.
+    """
+    if hasattr(decorators, "__iter__"):
+        # Apply a list/tuple of decorators if 'decorators' is one. Decorator
+        # functions are applied so that the call order is the same as the
+        # order in which they appear in the iterable.
+        decorators = decorators[::-1]
+    else:
+        decorators = [decorators]
+
+    def _wrapper(self, *args, **kwargs):
+        # bound_method has the signature that 'decorator' expects i.e. no
+        # 'self' argument, but it's a closure over self so it can call
+        # 'func'. Also, wrap method.__get__() in a function because new
+        # attributes can't be set on bound method objects, only on functions.
+        bound_method = wraps(method)(partial(method.__get__(self, type(self))))
+        for dec in decorators:
+            bound_method = dec(bound_method)
+        return bound_method(*args, **kwargs)
+
+    # Copy any attributes that a decorator adds to the function it decorates.
+    for dec in decorators:
+        _update_method_wrapper(_wrapper, dec)
+    # Preserve any existing attributes of 'method', including the name.
+    update_wrapper(_wrapper, method)
+    return _wrapper
+
+
+def method_decorator(decorator, name=""):
+    """
+    Convert a function decorator into a method decorator
+    """
+
+    # 'obj' can be a class or a function. If 'obj' is a function at the time it
+    # is passed to _dec,  it will eventually be a method of the class it is
+    # defined on. If 'obj' is a class, the 'name' is required to be the name
+    # of the method that will be decorated.
+    def _dec(obj):
+        if not isinstance(obj, type):
+            return _multi_decorate(decorator, obj)
+        if not (name and hasattr(obj, name)):
+            raise ValueError(
+                "The keyword argument `name` must be the name of a method "
+                f"of the decorated class: {obj}. Got '{name}' instead."
+            )
+        method = getattr(obj, name)
+        if not callable(method):
+            raise TypeError(
+                f"Cannot decorate '{name}' as it isn't a callable attribute of "
+                f"{obj} ({method})."
+            )
+        _wrapper = _multi_decorate(decorator, method)
+        setattr(obj, name, _wrapper)
+        return obj
+
+    # Don't worry about making _dec look similar to a list/tuple as it's rather
+    # meaningless.
+    if not hasattr(decorator, "__iter__"):
+        update_wrapper(_dec, decorator)
+    # Change the name to aid debugging.
+    obj = decorator if hasattr(decorator, "__name__") else decorator.__class__
+    _dec.__name__ = "method_decorator(%s)" % obj.__name__
+    return _dec

plain/utils/deprecation.py

@@ -0,0 +1,6 @@
+class RemovedInDjango51Warning(DeprecationWarning):
+    pass
+
+
+class RemovedInDjango60Warning(PendingDeprecationWarning):
+    pass

plain/utils/duration.py

@@ -0,0 +1,44 @@
+import datetime
+
+
+def _get_duration_components(duration):
+    days = duration.days
+    seconds = duration.seconds
+    microseconds = duration.microseconds
+
+    minutes = seconds // 60
+    seconds %= 60
+
+    hours = minutes // 60
+    minutes %= 60
+
+    return days, hours, minutes, seconds, microseconds
+
+
+def duration_string(duration):
+    """Version of str(timedelta) which is not English specific."""
+    days, hours, minutes, seconds, microseconds = _get_duration_components(duration)
+
+    string = f"{hours:02d}:{minutes:02d}:{seconds:02d}"
+    if days:
+        string = f"{days} " + string
+    if microseconds:
+        string += f".{microseconds:06d}"
+
+    return string
+
+
+def duration_iso_string(duration):
+    if duration < datetime.timedelta(0):
+        sign = "-"
+        duration *= -1
+    else:
+        sign = ""
+
+    days, hours, minutes, seconds, microseconds = _get_duration_components(duration)
+    ms = f".{microseconds:06d}" if microseconds else ""
+    return f"{sign}P{days}DT{hours:02d}H{minutes:02d}M{seconds:02d}{ms}S"
+
+
+def duration_microseconds(delta):
+    return (24 * 60 * 60 * delta.days + delta.seconds) * 1000000 + delta.microseconds

plain/utils/email.py

@@ -0,0 +1,12 @@
+def normalize_email(email):
+    """
+    Normalize the email address by lowercasing the domain part of it.
+    """
+    email = email or ""
+    try:
+        email_name, domain_part = email.strip().rsplit("@", 1)
+    except ValueError:
+        pass
+    else:
+        email = email_name + "@" + domain_part.lower()
+    return email

plain/utils/encoding.py

@@ -0,0 +1,235 @@
+import codecs
+import datetime
+import locale
+from decimal import Decimal
+from types import NoneType
+from urllib.parse import quote
+
+from plain.utils.functional import Promise
+
+
+class PlainUnicodeDecodeError(UnicodeDecodeError):
+    def __init__(self, obj, *args):
+        self.obj = obj
+        super().__init__(*args)
+
+    def __str__(self):
+        return f"{super().__str__()}. You passed in {self.obj!r} ({type(self.obj)})"
+
+
+_PROTECTED_TYPES = (
+    NoneType,
+    int,
+    float,
+    Decimal,
+    datetime.datetime,
+    datetime.date,
+    datetime.time,
+)
+
+
+def is_protected_type(obj):
+    """Determine if the object instance is of a protected type.
+
+    Objects of protected types are preserved as-is when passed to
+    force_str(strings_only=True).
+    """
+    return isinstance(obj, _PROTECTED_TYPES)
+
+
+def force_str(s, encoding="utf-8", strings_only=False, errors="strict"):
+    """
+    Similar to smart_str(), except that lazy instances are resolved to
+    strings, rather than kept as lazy objects.
+
+    If strings_only is True, don't convert (some) non-string-like objects.
+    """
+    # Handle the common case first for performance reasons.
+    if issubclass(type(s), str):
+        return s
+    if strings_only and is_protected_type(s):
+        return s
+    try:
+        if isinstance(s, bytes):
+            s = str(s, encoding, errors)
+        else:
+            s = str(s)
+    except UnicodeDecodeError as e:
+        raise PlainUnicodeDecodeError(s, *e.args)
+    return s
+
+
+def force_bytes(s, encoding="utf-8", strings_only=False, errors="strict"):
+    """
+    Similar to smart_bytes, except that lazy instances are resolved to
+    strings, rather than kept as lazy objects.
+
+    If strings_only is True, don't convert (some) non-string-like objects.
+    """
+    # Handle the common case first for performance reasons.
+    if isinstance(s, bytes):
+        if encoding == "utf-8":
+            return s
+        else:
+            return s.decode("utf-8", errors).encode(encoding, errors)
+    if strings_only and is_protected_type(s):
+        return s
+    if isinstance(s, memoryview):
+        return bytes(s)
+    return str(s).encode(encoding, errors)
+
+
+def iri_to_uri(iri):
+    """
+    Convert an Internationalized Resource Identifier (IRI) portion to a URI
+    portion that is suitable for inclusion in a URL.
+
+    This is the algorithm from RFC 3987 Section 3.1, slightly simplified since
+    the input is assumed to be a string rather than an arbitrary byte stream.
+
+    Take an IRI (string or UTF-8 bytes, e.g. '/I ♥ Plain/' or
+    b'/I \xe2\x99\xa5 Plain/') and return a string containing the encoded
+    result with ASCII chars only (e.g. '/I%20%E2%99%A5%20Plain/').
+    """
+    # The list of safe characters here is constructed from the "reserved" and
+    # "unreserved" characters specified in RFC 3986 Sections 2.2 and 2.3:
+    #     reserved    = gen-delims / sub-delims
+    #     gen-delims  = ":" / "/" / "?" / "#" / "[" / "]" / "@"
+    #     sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
+    #                   / "*" / "+" / "," / ";" / "="
+    #     unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
+    # Of the unreserved characters, urllib.parse.quote() already considers all
+    # but the ~ safe.
+    # The % character is also added to the list of safe characters here, as the
+    # end of RFC 3987 Section 3.1 specifically mentions that % must not be
+    # converted.
+    if iri is None:
+        return iri
+    elif isinstance(iri, Promise):
+        iri = str(iri)
+    return quote(iri, safe="/#%[]=:;$&()+,!?*@'~")
+
+
+# List of byte values that uri_to_iri() decodes from percent encoding.
+# First, the unreserved characters from RFC 3986:
+_ascii_ranges = [[45, 46, 95, 126], range(65, 91), range(97, 123)]
+_hextobyte = {
+    (fmt % char).encode(): bytes((char,))
+    for ascii_range in _ascii_ranges
+    for char in ascii_range
+    for fmt in ["%02x", "%02X"]
+}
+# And then everything above 128, because bytes ≥ 128 are part of multibyte
+# Unicode characters.
+_hexdig = "0123456789ABCDEFabcdef"
+_hextobyte.update(
+    {(a + b).encode(): bytes.fromhex(a + b) for a in _hexdig[8:] for b in _hexdig}
+)
+
+
+def uri_to_iri(uri):
+    """
+    Convert a Uniform Resource Identifier(URI) into an Internationalized
+    Resource Identifier(IRI).
+
+    This is the algorithm from RFC 3987 Section 3.2, excluding step 4.
+
+    Take an URI in ASCII bytes (e.g. '/I%20%E2%99%A5%20Plain/') and return
+    a string containing the encoded result (e.g. '/I%20♥%20Plain/').
+    """
+    if uri is None:
+        return uri
+    uri = force_bytes(uri)
+    # Fast selective unquote: First, split on '%' and then starting with the
+    # second block, decode the first 2 bytes if they represent a hex code to
+    # decode. The rest of the block is the part after '%AB', not containing
+    # any '%'. Add that to the output without further processing.
+    bits = uri.split(b"%")
+    if len(bits) == 1:
+        iri = uri
+    else:
+        parts = [bits[0]]
+        append = parts.append
+        hextobyte = _hextobyte
+        for item in bits[1:]:
+            hex = item[:2]
+            if hex in hextobyte:
+                append(hextobyte[item[:2]])
+                append(item[2:])
+            else:
+                append(b"%")
+                append(item)
+        iri = b"".join(parts)
+    return repercent_broken_unicode(iri).decode()
+
+
+def escape_uri_path(path):
+    """
+    Escape the unsafe characters from the path portion of a Uniform Resource
+    Identifier (URI).
+    """
+    # These are the "reserved" and "unreserved" characters specified in RFC
+    # 3986 Sections 2.2 and 2.3:
+    #   reserved    = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | ","
+    #   unreserved  = alphanum | mark
+    #   mark        = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"
+    # The list of safe characters here is constructed subtracting ";", "=",
+    # and "?" according to RFC 3986 Section 3.3.
+    # The reason for not subtracting and escaping "/" is that we are escaping
+    # the entire path, not a path segment.
+    return quote(path, safe="/:@&+$,-_.!~*'()")
+
+
+def punycode(domain):
+    """Return the Punycode of the given domain if it's non-ASCII."""
+    return domain.encode("idna").decode("ascii")
+
+
+def repercent_broken_unicode(path):
+    """
+    As per RFC 3987 Section 3.2, step three of converting a URI into an IRI,
+    repercent-encode any octet produced that is not part of a strictly legal
+    UTF-8 octet sequence.
+    """
+    while True:
+        try:
+            path.decode()
+        except UnicodeDecodeError as e:
+            # CVE-2019-14235: A recursion shouldn't be used since the exception
+            # handling uses massive amounts of memory
+            repercent = quote(path[e.start : e.end], safe=b"/#%[]=:;$&()+,!?*@'~")
+            path = path[: e.start] + repercent.encode() + path[e.end :]
+        else:
+            return path
+
+
+def filepath_to_uri(path):
+    """Convert a file system path to a URI portion that is suitable for
+    inclusion in a URL.
+
+    Encode certain chars that would normally be recognized as special chars
+    for URIs. Do not encode the ' character, as it is a valid character
+    within URIs. See the encodeURIComponent() JavaScript function for details.
+    """
+    if path is None:
+        return path
+    # I know about `os.sep` and `os.altsep` but I want to leave
+    # some flexibility for hardcoding separators.
+    return quote(str(path).replace("\\", "/"), safe="/~!*()'")
+
+
+def get_system_encoding():
+    """
+    The encoding for the character type functions. Fallback to 'ascii' if the
+    #encoding is unsupported by Python or could not be determined. See tickets
+    #10335 and #5846.
+    """
+    try:
+        encoding = locale.getlocale()[1] or "ascii"
+        codecs.lookup(encoding)
+    except Exception:
+        encoding = "ascii"
+    return encoding
+
+
+DEFAULT_LOCALE_ENCODING = get_system_encoding()