plain 0.1.0__py3-none-any.whl

plain/utils/timezone.py

@@ -0,0 +1,244 @@
+"""
+Timezone-related classes and functions.
+"""
+
+import functools
+import zoneinfo
+from contextlib import ContextDecorator
+from datetime import datetime, timedelta, timezone, tzinfo
+from threading import local
+
+from plain.runtime import settings
+
+__all__ = [
+    "get_fixed_timezone",
+    "get_default_timezone",
+    "get_default_timezone_name",
+    "get_current_timezone",
+    "get_current_timezone_name",
+    "activate",
+    "deactivate",
+    "override",
+    "localtime",
+    "now",
+    "is_aware",
+    "is_naive",
+    "make_aware",
+    "make_naive",
+]
+
+
+def get_fixed_timezone(offset):
+    """Return a tzinfo instance with a fixed offset from UTC."""
+    if isinstance(offset, timedelta):
+        offset = offset.total_seconds() // 60
+    sign = "-" if offset < 0 else "+"
+    hhmm = "%02d%02d" % divmod(abs(offset), 60)
+    name = sign + hhmm
+    return timezone(timedelta(minutes=offset), name)
+
+
+# In order to avoid accessing settings at compile time,
+# wrap the logic in a function and cache the result.
+@functools.lru_cache
+def get_default_timezone():
+    """
+    Return the default time zone as a tzinfo instance.
+
+    This is the time zone defined by settings.TIME_ZONE.
+    """
+    return zoneinfo.ZoneInfo(settings.TIME_ZONE)
+
+
+# This function exists for consistency with get_current_timezone_name
+def get_default_timezone_name():
+    """Return the name of the default time zone."""
+    return _get_timezone_name(get_default_timezone())
+
+
+_active = local()
+
+
+def get_current_timezone():
+    """Return the currently active time zone as a tzinfo instance."""
+    return getattr(_active, "value", get_default_timezone())
+
+
+def get_current_timezone_name():
+    """Return the name of the currently active time zone."""
+    return _get_timezone_name(get_current_timezone())
+
+
+def _get_timezone_name(timezone):
+    """
+    Return the offset for fixed offset timezones, or the name of timezone if
+    not set.
+    """
+    return timezone.tzname(None) or str(timezone)
+
+
+# Timezone selection functions.
+
+# These functions don't change os.environ['TZ'] and call time.tzset()
+# because it isn't thread safe.
+
+
+def activate(timezone):
+    """
+    Set the time zone for the current thread.
+
+    The ``timezone`` argument must be an instance of a tzinfo subclass or a
+    time zone name.
+    """
+    if isinstance(timezone, tzinfo):
+        _active.value = timezone
+    elif isinstance(timezone, str):
+        _active.value = zoneinfo.ZoneInfo(timezone)
+    else:
+        raise ValueError("Invalid timezone: %r" % timezone)
+
+
+def deactivate():
+    """
+    Unset the time zone for the current thread.
+
+    Plain will then use the time zone defined by settings.TIME_ZONE.
+    """
+    if hasattr(_active, "value"):
+        del _active.value
+
+
+class override(ContextDecorator):
+    """
+    Temporarily set the time zone for the current thread.
+
+    This is a context manager that uses plain.utils.timezone.activate()
+    to set the timezone on entry and restores the previously active timezone
+    on exit.
+
+    The ``timezone`` argument must be an instance of a ``tzinfo`` subclass, a
+    time zone name, or ``None``. If it is ``None``, Plain enables the default
+    time zone.
+    """
+
+    def __init__(self, timezone):
+        self.timezone = timezone
+
+    def __enter__(self):
+        self.old_timezone = getattr(_active, "value", None)
+        if self.timezone is None:
+            deactivate()
+        else:
+            activate(self.timezone)
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if self.old_timezone is None:
+            deactivate()
+        else:
+            _active.value = self.old_timezone
+
+
+# Templates
+
+
+def template_localtime(value, use_tz=None):
+    """
+    Check if value is a datetime and converts it to local time if necessary.
+
+    If use_tz is provided and is not None, that will force the value to
+    be converted (or not), overriding the value of settings.USE_TZ.
+
+    This function is designed for use by the template engine.
+    """
+    should_convert = (
+        isinstance(value, datetime)
+        and (settings.USE_TZ if use_tz is None else use_tz)
+        and not is_naive(value)
+        and getattr(value, "convert_to_local_time", True)
+    )
+    return localtime(value) if should_convert else value
+
+
+# Utilities
+
+
+def localtime(value=None, timezone=None):
+    """
+    Convert an aware datetime.datetime to local time.
+
+    Only aware datetimes are allowed. When value is omitted, it defaults to
+    now().
+
+    Local time is defined by the current time zone, unless another time zone
+    is specified.
+    """
+    if value is None:
+        value = now()
+    if timezone is None:
+        timezone = get_current_timezone()
+    # Emulate the behavior of astimezone() on Python < 3.6.
+    if is_naive(value):
+        raise ValueError("localtime() cannot be applied to a naive datetime")
+    return value.astimezone(timezone)
+
+
+def now():
+    """
+    Return an aware or naive datetime.datetime, depending on settings.USE_TZ.
+    """
+    return datetime.now(tz=timezone.utc if settings.USE_TZ else None)
+
+
+# By design, these four functions don't perform any checks on their arguments.
+# The caller should ensure that they don't receive an invalid value like None.
+
+
+def is_aware(value):
+    """
+    Determine if a given datetime.datetime is aware.
+
+    The concept is defined in Python's docs:
+    https://docs.python.org/library/datetime.html#datetime.tzinfo
+
+    Assuming value.tzinfo is either None or a proper datetime.tzinfo,
+    value.utcoffset() implements the appropriate logic.
+    """
+    return value.utcoffset() is not None
+
+
+def is_naive(value):
+    """
+    Determine if a given datetime.datetime is naive.
+
+    The concept is defined in Python's docs:
+    https://docs.python.org/library/datetime.html#datetime.tzinfo
+
+    Assuming value.tzinfo is either None or a proper datetime.tzinfo,
+    value.utcoffset() implements the appropriate logic.
+    """
+    return value.utcoffset() is None
+
+
+def make_aware(value, timezone=None):
+    """Make a naive datetime.datetime in a given time zone aware."""
+    if timezone is None:
+        timezone = get_current_timezone()
+    # Check that we won't overwrite the timezone of an aware datetime.
+    if is_aware(value):
+        raise ValueError("make_aware expects a naive datetime, got %s" % value)
+    # This may be wrong around DST changes!
+    return value.replace(tzinfo=timezone)
+
+
+def make_naive(value, timezone=None):
+    """Make an aware datetime.datetime naive in a given time zone."""
+    if timezone is None:
+        timezone = get_current_timezone()
+    # Emulate the behavior of astimezone() on Python < 3.6.
+    if is_naive(value):
+        raise ValueError("make_naive() cannot be applied to a naive datetime")
+    return value.astimezone(timezone).replace(tzinfo=None)
+
+
+def _datetime_ambiguous_or_imaginary(dt, tz):
+    return tz.utcoffset(dt.replace(fold=not dt.fold)) != tz.utcoffset(dt)

plain/utils/tree.py

@@ -0,0 +1,126 @@
+"""
+A class for storing a tree graph. Primarily used for filter constructs in the
+ORM.
+"""
+
+import copy
+
+from plain.utils.hashable import make_hashable
+
+
+class Node:
+    """
+    A single internal node in the tree graph. A Node should be viewed as a
+    connection (the root) with the children being either leaf nodes or other
+    Node instances.
+    """
+
+    # Standard connector type. Clients usually won't use this at all and
+    # subclasses will usually override the value.
+    default = "DEFAULT"
+
+    def __init__(self, children=None, connector=None, negated=False):
+        """Construct a new Node. If no connector is given, use the default."""
+        self.children = children[:] if children else []
+        self.connector = connector or self.default
+        self.negated = negated
+
+    @classmethod
+    def create(cls, children=None, connector=None, negated=False):
+        """
+        Create a new instance using Node() instead of __init__() as some
+        subclasses, e.g. plain.models.query_utils.Q, may implement a custom
+        __init__() with a signature that conflicts with the one defined in
+        Node.__init__().
+        """
+        obj = Node(children, connector or cls.default, negated)
+        obj.__class__ = cls
+        return obj
+
+    def __str__(self):
+        template = "(NOT (%s: %s))" if self.negated else "(%s: %s)"
+        return template % (self.connector, ", ".join(str(c) for c in self.children))
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}: {self}>"
+
+    def __copy__(self):
+        obj = self.create(connector=self.connector, negated=self.negated)
+        obj.children = self.children  # Don't [:] as .__init__() via .create() does.
+        return obj
+
+    copy = __copy__
+
+    def __deepcopy__(self, memodict):
+        obj = self.create(connector=self.connector, negated=self.negated)
+        obj.children = copy.deepcopy(self.children, memodict)
+        return obj
+
+    def __len__(self):
+        """Return the number of children this node has."""
+        return len(self.children)
+
+    def __bool__(self):
+        """Return whether or not this node has children."""
+        return bool(self.children)
+
+    def __contains__(self, other):
+        """Return True if 'other' is a direct child of this instance."""
+        return other in self.children
+
+    def __eq__(self, other):
+        return (
+            self.__class__ == other.__class__
+            and self.connector == other.connector
+            and self.negated == other.negated
+            and self.children == other.children
+        )
+
+    def __hash__(self):
+        return hash(
+            (
+                self.__class__,
+                self.connector,
+                self.negated,
+                *make_hashable(self.children),
+            )
+        )
+
+    def add(self, data, conn_type):
+        """
+        Combine this tree and the data represented by data using the
+        connector conn_type. The combine is done by squashing the node other
+        away if possible.
+
+        This tree (self) will never be pushed to a child node of the
+        combined tree, nor will the connector or negated properties change.
+
+        Return a node which can be used in place of data regardless if the
+        node other got squashed or not.
+        """
+        if self.connector != conn_type:
+            obj = self.copy()
+            self.connector = conn_type
+            self.children = [obj, data]
+            return data
+        elif (
+            isinstance(data, Node)
+            and not data.negated
+            and (data.connector == conn_type or len(data) == 1)
+        ):
+            # We can squash the other node's children directly into this node.
+            # We are just doing (AB)(CD) == (ABCD) here, with the addition that
+            # if the length of the other node is 1 the connector doesn't
+            # matter. However, for the len(self) == 1 case we don't want to do
+            # the squashing, as it would alter self.connector.
+            self.children.extend(data.children)
+            return self
+        else:
+            # We could use perhaps additional logic here to see if some
+            # children could be used for pushdown here.
+            self.children.append(data)
+            return data
+
+    def negate(self):
+        """Negate the sense of the root connector."""
+        self.negated = not self.negated