plain 0.1.0__py3-none-any.whl

plain/utils/datastructures.py

@@ -0,0 +1,345 @@
+import copy
+from collections.abc import Mapping
+
+
+class OrderedSet:
+    """
+    A set which keeps the ordering of the inserted items.
+    """
+
+    def __init__(self, iterable=None):
+        self.dict = dict.fromkeys(iterable or ())
+
+    def add(self, item):
+        self.dict[item] = None
+
+    def remove(self, item):
+        del self.dict[item]
+
+    def discard(self, item):
+        try:
+            self.remove(item)
+        except KeyError:
+            pass
+
+    def __iter__(self):
+        return iter(self.dict)
+
+    def __reversed__(self):
+        return reversed(self.dict)
+
+    def __contains__(self, item):
+        return item in self.dict
+
+    def __bool__(self):
+        return bool(self.dict)
+
+    def __len__(self):
+        return len(self.dict)
+
+    def __repr__(self):
+        data = repr(list(self.dict)) if self.dict else ""
+        return f"{self.__class__.__qualname__}({data})"
+
+
+class MultiValueDictKeyError(KeyError):
+    pass
+
+
+class MultiValueDict(dict):
+    """
+    A subclass of dictionary customized to handle multiple values for the
+    same key.
+
+    >>> d = MultiValueDict({'name': ['Adrian', 'Simon'], 'position': ['Developer']})
+    >>> d['name']
+    'Simon'
+    >>> d.getlist('name')
+    ['Adrian', 'Simon']
+    >>> d.getlist('doesnotexist')
+    []
+    >>> d.getlist('doesnotexist', ['Adrian', 'Simon'])
+    ['Adrian', 'Simon']
+    >>> d.get('lastname', 'nonexistent')
+    'nonexistent'
+    >>> d.setlist('lastname', ['Holovaty', 'Willison'])
+
+    This class exists to solve the irritating problem raised by cgi.parse_qs,
+    which returns a list for every key, even though most web forms submit
+    single name-value pairs.
+    """
+
+    def __init__(self, key_to_list_mapping=()):
+        super().__init__(key_to_list_mapping)
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}: {super().__repr__()}>"
+
+    def __getitem__(self, key):
+        """
+        Return the last data value for this key, or [] if it's an empty list;
+        raise KeyError if not found.
+        """
+        try:
+            list_ = super().__getitem__(key)
+        except KeyError:
+            raise MultiValueDictKeyError(key)
+        try:
+            return list_[-1]
+        except IndexError:
+            return []
+
+    def __setitem__(self, key, value):
+        super().__setitem__(key, [value])
+
+    def __copy__(self):
+        return self.__class__([(k, v[:]) for k, v in self.lists()])
+
+    def __deepcopy__(self, memo):
+        result = self.__class__()
+        memo[id(self)] = result
+        for key, value in dict.items(self):
+            dict.__setitem__(
+                result, copy.deepcopy(key, memo), copy.deepcopy(value, memo)
+            )
+        return result
+
+    def __getstate__(self):
+        return {**self.__dict__, "_data": {k: self._getlist(k) for k in self}}
+
+    def __setstate__(self, obj_dict):
+        data = obj_dict.pop("_data", {})
+        for k, v in data.items():
+            self.setlist(k, v)
+        self.__dict__.update(obj_dict)
+
+    def get(self, key, default=None):
+        """
+        Return the last data value for the passed key. If key doesn't exist
+        or value is an empty list, return `default`.
+        """
+        try:
+            val = self[key]
+        except KeyError:
+            return default
+        if val == []:
+            return default
+        return val
+
+    def _getlist(self, key, default=None, force_list=False):
+        """
+        Return a list of values for the key.
+
+        Used internally to manipulate values list. If force_list is True,
+        return a new copy of values.
+        """
+        try:
+            values = super().__getitem__(key)
+        except KeyError:
+            if default is None:
+                return []
+            return default
+        else:
+            if force_list:
+                values = list(values) if values is not None else None
+            return values
+
+    def getlist(self, key, default=None):
+        """
+        Return the list of values for the key. If key doesn't exist, return a
+        default value.
+        """
+        return self._getlist(key, default, force_list=True)
+
+    def setlist(self, key, list_):
+        super().__setitem__(key, list_)
+
+    def setdefault(self, key, default=None):
+        if key not in self:
+            self[key] = default
+            # Do not return default here because __setitem__() may store
+            # another value -- QueryDict.__setitem__() does. Look it up.
+        return self[key]
+
+    def setlistdefault(self, key, default_list=None):
+        if key not in self:
+            if default_list is None:
+                default_list = []
+            self.setlist(key, default_list)
+            # Do not return default_list here because setlist() may store
+            # another value -- QueryDict.setlist() does. Look it up.
+        return self._getlist(key)
+
+    def appendlist(self, key, value):
+        """Append an item to the internal list associated with key."""
+        self.setlistdefault(key).append(value)
+
+    def items(self):
+        """
+        Yield (key, value) pairs, where value is the last item in the list
+        associated with the key.
+        """
+        for key in self:
+            yield key, self[key]
+
+    def lists(self):
+        """Yield (key, list) pairs."""
+        return iter(super().items())
+
+    def values(self):
+        """Yield the last value on every key list."""
+        for key in self:
+            yield self[key]
+
+    def copy(self):
+        """Return a shallow copy of this object."""
+        return copy.copy(self)
+
+    def update(self, *args, **kwargs):
+        """Extend rather than replace existing key lists."""
+        if len(args) > 1:
+            raise TypeError("update expected at most 1 argument, got %d" % len(args))
+        if args:
+            arg = args[0]
+            if isinstance(arg, MultiValueDict):
+                for key, value_list in arg.lists():
+                    self.setlistdefault(key).extend(value_list)
+            else:
+                if isinstance(arg, Mapping):
+                    arg = arg.items()
+                for key, value in arg:
+                    self.setlistdefault(key).append(value)
+        for key, value in kwargs.items():
+            self.setlistdefault(key).append(value)
+
+    def dict(self):
+        """Return current object as a dict with singular values."""
+        return {key: self[key] for key in self}
+
+
+class ImmutableList(tuple):
+    """
+    A tuple-like object that raises useful errors when it is asked to mutate.
+
+    Example::
+
+        >>> a = ImmutableList(range(5), warning="You cannot mutate this.")
+        >>> a[3] = '4'
+        Traceback (most recent call last):
+            ...
+        AttributeError: You cannot mutate this.
+    """
+
+    def __new__(cls, *args, warning="ImmutableList object is immutable.", **kwargs):
+        self = tuple.__new__(cls, *args, **kwargs)
+        self.warning = warning
+        return self
+
+    def complain(self, *args, **kwargs):
+        raise AttributeError(self.warning)
+
+    # All list mutation functions complain.
+    __delitem__ = complain
+    __delslice__ = complain
+    __iadd__ = complain
+    __imul__ = complain
+    __setitem__ = complain
+    __setslice__ = complain
+    append = complain
+    extend = complain
+    insert = complain
+    pop = complain
+    remove = complain
+    sort = complain
+    reverse = complain
+
+
+class DictWrapper(dict):
+    """
+    Wrap accesses to a dictionary so that certain values (those starting with
+    the specified prefix) are passed through a function before being returned.
+    The prefix is removed before looking up the real value.
+
+    Used by the SQL construction code to ensure that values are correctly
+    quoted before being used.
+    """
+
+    def __init__(self, data, func, prefix):
+        super().__init__(data)
+        self.func = func
+        self.prefix = prefix
+
+    def __getitem__(self, key):
+        """
+        Retrieve the real value after stripping the prefix string (if
+        present). If the prefix is present, pass the value through self.func
+        before returning, otherwise return the raw value.
+        """
+        use_func = key.startswith(self.prefix)
+        key = key.removeprefix(self.prefix)
+        value = super().__getitem__(key)
+        if use_func:
+            return self.func(value)
+        return value
+
+
+class CaseInsensitiveMapping(Mapping):
+    """
+    Mapping allowing case-insensitive key lookups. Original case of keys is
+    preserved for iteration and string representation.
+
+    Example::
+
+        >>> ci_map = CaseInsensitiveMapping({'name': 'Jane'})
+        >>> ci_map['Name']
+        Jane
+        >>> ci_map['NAME']
+        Jane
+        >>> ci_map['name']
+        Jane
+        >>> ci_map  # original case preserved
+        {'name': 'Jane'}
+    """
+
+    def __init__(self, data):
+        self._store = {k.lower(): (k, v) for k, v in self._unpack_items(data)}
+
+    def __getitem__(self, key):
+        return self._store[key.lower()][1]
+
+    def __len__(self):
+        return len(self._store)
+
+    def __eq__(self, other):
+        return isinstance(other, Mapping) and {
+            k.lower(): v for k, v in self.items()
+        } == {k.lower(): v for k, v in other.items()}
+
+    def __iter__(self):
+        return (original_key for original_key, value in self._store.values())
+
+    def __repr__(self):
+        return repr(dict(self._store.values()))
+
+    def copy(self):
+        return self
+
+    @staticmethod
+    def _unpack_items(data):
+        # Explicitly test for dict first as the common case for performance,
+        # avoiding abc's __instancecheck__ and _abc_instancecheck for the
+        # general Mapping case.
+        if isinstance(data, dict | Mapping):
+            yield from data.items()
+            return
+        for i, elem in enumerate(data):
+            if len(elem) != 2:
+                raise ValueError(
+                    f"dictionary update sequence element #{i} has length {len(elem)}; "
+                    "2 is required."
+                )
+            if not isinstance(elem[0], str):
+                raise ValueError(
+                    "Element key %r invalid, only strings are allowed" % elem[0]
+                )
+            yield elem

plain/utils/dateformat.py

@@ -0,0 +1,329 @@
+"""
+PHP date() style date formatting
+See https://www.php.net/date for format strings
+
+Usage:
+>>> from datetime import datetime
+>>> d = datetime.now()
+>>> df = DateFormat(d)
+>>> print(df.format('jS F Y H:i'))
+7th October 2003 11:39
+>>>
+"""
+import calendar
+from datetime import date, datetime, time
+from email.utils import format_datetime as format_datetime_rfc5322
+
+from plain.utils.dates import (
+    MONTHS,
+    MONTHS_3,
+    MONTHS_ALT,
+    MONTHS_AP,
+    WEEKDAYS,
+    WEEKDAYS_ABBR,
+)
+from plain.utils.regex_helper import _lazy_re_compile
+from plain.utils.timezone import (
+    _datetime_ambiguous_or_imaginary,
+    get_default_timezone,
+    is_naive,
+    make_aware,
+)
+
+re_formatchars = _lazy_re_compile(r"(?<!\\)([aAbcdDeEfFgGhHiIjlLmMnNoOPrsStTUuwWyYzZ])")
+re_escaped = _lazy_re_compile(r"\\(.)")
+
+
+class Formatter:
+    def format(self, formatstr):
+        pieces = []
+        for i, piece in enumerate(re_formatchars.split(str(formatstr))):
+            if i % 2:
+                if type(self.data) is date and hasattr(TimeFormat, piece):
+                    raise TypeError(
+                        "The format for date objects may not contain "
+                        "time-related format specifiers (found '%s')." % piece
+                    )
+                pieces.append(str(getattr(self, piece)()))
+            elif piece:
+                pieces.append(re_escaped.sub(r"\1", piece))
+        return "".join(pieces)
+
+
+class TimeFormat(Formatter):
+    def __init__(self, obj):
+        self.data = obj
+        self.timezone = None
+
+        if isinstance(obj, datetime):
+            # Timezone is only supported when formatting datetime objects, not
+            # date objects (timezone information not appropriate), or time
+            # objects (against established Plain policy).
+            if is_naive(obj):
+                timezone = get_default_timezone()
+            else:
+                timezone = obj.tzinfo
+            if not _datetime_ambiguous_or_imaginary(obj, timezone):
+                self.timezone = timezone
+
+    def a(self):
+        "'a.m.' or 'p.m.'"
+        if self.data.hour > 11:
+            return "p.m."
+        return "a.m."
+
+    def A(self):
+        "'AM' or 'PM'"
+        if self.data.hour > 11:
+            return "PM"
+        return "AM"
+
+    def e(self):
+        """
+        Timezone name.
+
+        If timezone information is not available, return an empty string.
+        """
+        if not self.timezone:
+            return ""
+
+        try:
+            if getattr(self.data, "tzinfo", None):
+                return self.data.tzname() or ""
+        except NotImplementedError:
+            pass
+        return ""
+
+    def f(self):
+        """
+        Time, in 12-hour hours and minutes, with minutes left off if they're
+        zero.
+        Examples: '1', '1:30', '2:05', '2'
+        Proprietary extension.
+        """
+        hour = self.data.hour % 12 or 12
+        minute = self.data.minute
+        return "%d:%02d" % (hour, minute) if minute else hour
+
+    def g(self):
+        "Hour, 12-hour format without leading zeros; i.e. '1' to '12'"
+        return self.data.hour % 12 or 12
+
+    def G(self):
+        "Hour, 24-hour format without leading zeros; i.e. '0' to '23'"
+        return self.data.hour
+
+    def h(self):
+        "Hour, 12-hour format; i.e. '01' to '12'"
+        return "%02d" % (self.data.hour % 12 or 12)
+
+    def H(self):
+        "Hour, 24-hour format; i.e. '00' to '23'"
+        return "%02d" % self.data.hour
+
+    def i(self):
+        "Minutes; i.e. '00' to '59'"
+        return "%02d" % self.data.minute
+
+    def O(self):  # NOQA: E743, E741
+        """
+        Difference to Greenwich time in hours; e.g. '+0200', '-0430'.
+
+        If timezone information is not available, return an empty string.
+        """
+        if self.timezone is None:
+            return ""
+
+        offset = self.timezone.utcoffset(self.data)
+        seconds = offset.days * 86400 + offset.seconds
+        sign = "-" if seconds < 0 else "+"
+        seconds = abs(seconds)
+        return "%s%02d%02d" % (sign, seconds // 3600, (seconds // 60) % 60)
+
+    def P(self):
+        """
+        Time, in 12-hour hours, minutes and 'a.m.'/'p.m.', with minutes left off
+        if they're zero and the strings 'midnight' and 'noon' if appropriate.
+        Examples: '1 a.m.', '1:30 p.m.', 'midnight', 'noon', '12:30 p.m.'
+        Proprietary extension.
+        """
+        if self.data.minute == 0 and self.data.hour == 0:
+            return "midnight"
+        if self.data.minute == 0 and self.data.hour == 12:
+            return "noon"
+        return f"{self.f()} {self.a()}"
+
+    def s(self):
+        "Seconds; i.e. '00' to '59'"
+        return "%02d" % self.data.second
+
+    def T(self):
+        """
+        Time zone of this machine; e.g. 'EST' or 'MDT'.
+
+        If timezone information is not available, return an empty string.
+        """
+        if self.timezone is None:
+            return ""
+
+        return str(self.timezone.tzname(self.data))
+
+    def u(self):
+        "Microseconds; i.e. '000000' to '999999'"
+        return "%06d" % self.data.microsecond
+
+    def Z(self):
+        """
+        Time zone offset in seconds (i.e. '-43200' to '43200'). The offset for
+        timezones west of UTC is always negative, and for those east of UTC is
+        always positive.
+
+        If timezone information is not available, return an empty string.
+        """
+        if self.timezone is None:
+            return ""
+
+        offset = self.timezone.utcoffset(self.data)
+
+        # `offset` is a datetime.timedelta. For negative values (to the west of
+        # UTC) only days can be negative (days=-1) and seconds are always
+        # positive. e.g. UTC-1 -> timedelta(days=-1, seconds=82800, microseconds=0)
+        # Positive offsets have days=0
+        return offset.days * 86400 + offset.seconds
+
+
+class DateFormat(TimeFormat):
+    def b(self):
+        "Month, textual, 3 letters, lowercase; e.g. 'jan'"
+        return MONTHS_3[self.data.month]
+
+    def c(self):
+        """
+        ISO 8601 Format
+        Example : '2008-01-02T10:30:00.000123'
+        """
+        return self.data.isoformat()
+
+    def d(self):
+        "Day of the month, 2 digits with leading zeros; i.e. '01' to '31'"
+        return "%02d" % self.data.day
+
+    def D(self):
+        "Day of the week, textual, 3 letters; e.g. 'Fri'"
+        return WEEKDAYS_ABBR[self.data.weekday()]
+
+    def E(self):
+        "Alternative month names as required by some locales. Proprietary extension."
+        return MONTHS_ALT[self.data.month]
+
+    def F(self):
+        "Month, textual, long; e.g. 'January'"
+        return MONTHS[self.data.month]
+
+    def I(self):  # NOQA: E743, E741
+        "'1' if daylight saving time, '0' otherwise."
+        if self.timezone is None:
+            return ""
+        return "1" if self.timezone.dst(self.data) else "0"
+
+    def j(self):
+        "Day of the month without leading zeros; i.e. '1' to '31'"
+        return self.data.day
+
+    def l(self):  # NOQA: E743, E741
+        "Day of the week, textual, long; e.g. 'Friday'"
+        return WEEKDAYS[self.data.weekday()]
+
+    def L(self):
+        "Boolean for whether it is a leap year; i.e. True or False"
+        return calendar.isleap(self.data.year)
+
+    def m(self):
+        "Month; i.e. '01' to '12'"
+        return "%02d" % self.data.month
+
+    def M(self):
+        "Month, textual, 3 letters; e.g. 'Jan'"
+        return MONTHS_3[self.data.month].title()
+
+    def n(self):
+        "Month without leading zeros; i.e. '1' to '12'"
+        return self.data.month
+
+    def N(self):
+        "Month abbreviation in Associated Press style. Proprietary extension."
+        return MONTHS_AP[self.data.month]
+
+    def o(self):
+        "ISO 8601 year number matching the ISO week number (W)"
+        return self.data.isocalendar().year
+
+    def r(self):
+        "RFC 5322 formatted date; e.g. 'Thu, 21 Dec 2000 16:01:07 +0200'"
+        value = self.data
+        if not isinstance(value, datetime):
+            # Assume midnight in default timezone if datetime.date provided.
+            default_timezone = get_default_timezone()
+            value = datetime.combine(value, time.min).replace(tzinfo=default_timezone)
+        elif is_naive(value):
+            value = make_aware(value, timezone=self.timezone)
+        return format_datetime_rfc5322(value)
+
+    def S(self):
+        """
+        English ordinal suffix for the day of the month, 2 characters; i.e.
+        'st', 'nd', 'rd' or 'th'.
+        """
+        if self.data.day in (11, 12, 13):  # Special case
+            return "th"
+        last = self.data.day % 10
+        if last == 1:
+            return "st"
+        if last == 2:
+            return "nd"
+        if last == 3:
+            return "rd"
+        return "th"
+
+    def t(self):
+        "Number of days in the given month; i.e. '28' to '31'"
+        return calendar.monthrange(self.data.year, self.data.month)[1]
+
+    def U(self):
+        "Seconds since the Unix epoch (January 1 1970 00:00:00 GMT)"
+        value = self.data
+        if not isinstance(value, datetime):
+            value = datetime.combine(value, time.min)
+        return int(value.timestamp())
+
+    def w(self):
+        "Day of the week, numeric, i.e. '0' (Sunday) to '6' (Saturday)"
+        return (self.data.weekday() + 1) % 7
+
+    def W(self):
+        "ISO-8601 week number of year, weeks starting on Monday"
+        return self.data.isocalendar().week
+
+    def y(self):
+        """Year, 2 digits with leading zeros; e.g. '99'."""
+        return "%02d" % (self.data.year % 100)
+
+    def Y(self):
+        """Year, 4 digits with leading zeros; e.g. '1999'."""
+        return "%04d" % self.data.year
+
+    def z(self):
+        """Day of the year, i.e. 1 to 366."""
+        return self.data.timetuple().tm_yday
+
+
+def format(value, format_string):
+    "Convenience function"
+    df = DateFormat(value)
+    return df.format(format_string)
+
+
+def time_format(value, format_string):
+    "Convenience function"
+    tf = TimeFormat(value)
+    return tf.format(format_string)