autonomous-app 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

autonomous/db/queryset/field_list.py

@@ -0,0 +1,88 @@
+__all__ = ("QueryFieldList",)
+
+
+class QueryFieldList:
+    """Object that handles combinations of .only() and .exclude() calls"""
+
+    ONLY = 1
+    EXCLUDE = 0
+
+    def __init__(
+        self, fields=None, value=ONLY, always_include=None, _only_called=False
+    ):
+        """The QueryFieldList builder
+
+        :param fields: A list of fields used in `.only()` or `.exclude()`
+        :param value: How to handle the fields; either `ONLY` or `EXCLUDE`
+        :param always_include: Any fields to always_include eg `_cls`
+        :param _only_called: Has `.only()` been called?  If so its a set of fields
+           otherwise it performs a union.
+        """
+        self.value = value
+        self.fields = set(fields or [])
+        self.always_include = set(always_include or [])
+        self._id = None
+        self._only_called = _only_called
+        self.slice = {}
+
+    def __add__(self, f):
+        if isinstance(f.value, dict):
+            for field in f.fields:
+                self.slice[field] = f.value
+            if not self.fields:
+                self.fields = f.fields
+        elif not self.fields:
+            self.fields = f.fields
+            self.value = f.value
+            self.slice = {}
+        elif self.value is self.ONLY and f.value is self.ONLY:
+            self._clean_slice()
+            if self._only_called:
+                self.fields = self.fields.union(f.fields)
+            else:
+                self.fields = f.fields
+        elif self.value is self.EXCLUDE and f.value is self.EXCLUDE:
+            self.fields = self.fields.union(f.fields)
+            self._clean_slice()
+        elif self.value is self.ONLY and f.value is self.EXCLUDE:
+            self.fields -= f.fields
+            self._clean_slice()
+        elif self.value is self.EXCLUDE and f.value is self.ONLY:
+            self.value = self.ONLY
+            self.fields = f.fields - self.fields
+            self._clean_slice()
+
+        if "_id" in f.fields:
+            self._id = f.value
+
+        if self.always_include:
+            if self.value is self.ONLY and self.fields:
+                if sorted(self.slice.keys()) != sorted(self.fields):
+                    self.fields = self.fields.union(self.always_include)
+            else:
+                self.fields -= self.always_include
+
+        if getattr(f, "_only_called", False):
+            self._only_called = True
+        return self
+
+    def __bool__(self):
+        return bool(self.fields)
+
+    def as_dict(self):
+        field_list = {field: self.value for field in self.fields}
+        if self.slice:
+            field_list.update(self.slice)
+        if self._id is not None:
+            field_list["_id"] = self._id
+        return field_list
+
+    def reset(self):
+        self.fields = set()
+        self.slice = {}
+        self.value = self.ONLY
+
+    def _clean_slice(self):
+        if self.slice:
+            for field in set(self.slice.keys()) - self.fields:
+                del self.slice[field]

autonomous/db/queryset/manager.py

@@ -0,0 +1,58 @@
+from functools import partial
+
+from autonomous.db.queryset.queryset import QuerySet
+
+__all__ = ("queryset_manager", "QuerySetManager")
+
+
+class QuerySetManager:
+    """
+    The default QuerySet Manager.
+
+    Custom QuerySet Manager functions can extend this class and users can
+    add extra queryset functionality.  Any custom manager methods must accept a
+    :class:`~autonomous.db.Document` class as its first argument, and a
+    :class:`~autonomous.db.queryset.QuerySet` as its second argument.
+
+    The method function should return a :class:`~autonomous.db.queryset.QuerySet`
+    , probably the same one that was passed in, but modified in some way.
+    """
+
+    get_queryset = None
+    default = QuerySet
+
+    def __init__(self, queryset_func=None):
+        if queryset_func:
+            self.get_queryset = queryset_func
+
+    def __get__(self, instance, owner):
+        """Descriptor for instantiating a new QuerySet object when
+        Document.objects is accessed.
+        """
+        if instance is not None:
+            # Document object being used rather than a document class
+            return self
+
+        # owner is the document that contains the QuerySetManager
+        queryset_class = owner._meta.get("queryset_class", self.default)
+        queryset = queryset_class(owner, owner._get_collection())
+        if self.get_queryset:
+            arg_count = self.get_queryset.__code__.co_argcount
+            if arg_count == 1:
+                queryset = self.get_queryset(queryset)
+            elif arg_count == 2:
+                queryset = self.get_queryset(owner, queryset)
+            else:
+                queryset = partial(self.get_queryset, owner, queryset)
+        return queryset
+
+
+def queryset_manager(func):
+    """Decorator that allows you to define custom QuerySet managers on
+    :class:`~autonomous.db.Document` classes. The manager must be a function that
+    accepts a :class:`~autonomous.db.Document` class as its first argument, and a
+    :class:`~autonomous.db.queryset.QuerySet` as its second argument. The method
+    function should return a :class:`~autonomous.db.queryset.QuerySet`, probably
+    the same one that was passed in, but modified in some way.
+    """
+    return QuerySetManager(func)

autonomous/db/queryset/queryset.py

@@ -0,0 +1,189 @@
+from autonomous.db.errors import OperationError
+from autonomous.db.queryset.base import (
+    CASCADE,
+    DENY,
+    DO_NOTHING,
+    NULLIFY,
+    PULL,
+    BaseQuerySet,
+)
+
+__all__ = (
+    "QuerySet",
+    "QuerySetNoCache",
+    "DO_NOTHING",
+    "NULLIFY",
+    "CASCADE",
+    "DENY",
+    "PULL",
+)
+
+# The maximum number of items to display in a QuerySet.__repr__
+REPR_OUTPUT_SIZE = 20
+ITER_CHUNK_SIZE = 100
+
+
+class QuerySet(BaseQuerySet):
+    """The default queryset, that builds queries and handles a set of results
+    returned from a query.
+
+    Wraps a MongoDB cursor, providing :class:`~autonomous.db.Document` objects as
+    the results.
+    """
+
+    _has_more = True
+    _len = None
+    _result_cache = None
+
+    def __iter__(self):
+        """Iteration utilises a results cache which iterates the cursor
+        in batches of ``ITER_CHUNK_SIZE``.
+
+        If ``self._has_more`` the cursor hasn't been exhausted so cache then
+        batch. Otherwise iterate the result_cache.
+        """
+        self._iter = True
+
+        if self._has_more:
+            return self._iter_results()
+
+        # iterating over the cache.
+        return iter(self._result_cache)
+
+    def __len__(self):
+        """Since __len__ is called quite frequently (for example, as part of
+        list(qs)), we populate the result cache and cache the length.
+        """
+        if self._len is not None:
+            return self._len
+
+        # Populate the result cache with *all* of the docs in the cursor
+        if self._has_more:
+            list(self._iter_results())
+
+        # Cache the length of the complete result cache and return it
+        self._len = len(self._result_cache)
+        return self._len
+
+    def __repr__(self):
+        """Provide a string representation of the QuerySet"""
+        if self._iter:
+            return ".. queryset mid-iteration .."
+
+        self._populate_cache()
+        data = self._result_cache[: REPR_OUTPUT_SIZE + 1]
+        if len(data) > REPR_OUTPUT_SIZE:
+            data[-1] = "...(remaining elements truncated)..."
+        return repr(data)
+
+    def _iter_results(self):
+        """A generator for iterating over the result cache.
+
+        Also populates the cache if there are more possible results to
+        yield. Raises StopIteration when there are no more results.
+        """
+        if self._result_cache is None:
+            self._result_cache = []
+
+        pos = 0
+        while True:
+            # For all positions lower than the length of the current result
+            # cache, serve the docs straight from the cache w/o hitting the
+            # database.
+            # XXX it's VERY important to compute the len within the `while`
+            # condition because the result cache might expand mid-iteration
+            # (e.g. if we call len(qs) inside a loop that iterates over the
+            # queryset). Fortunately len(list) is O(1) in Python, so this
+            # doesn't cause performance issues.
+            while pos < len(self._result_cache):
+                yield self._result_cache[pos]
+                pos += 1
+
+            # return if we already established there were no more
+            # docs in the db cursor.
+            if not self._has_more:
+                return
+
+            # Otherwise, populate more of the cache and repeat.
+            if len(self._result_cache) <= pos:
+                self._populate_cache()
+
+    def _populate_cache(self):
+        """
+        Populates the result cache with ``ITER_CHUNK_SIZE`` more entries
+        (until the cursor is exhausted).
+        """
+        if self._result_cache is None:
+            self._result_cache = []
+
+        # Skip populating the cache if we already established there are no
+        # more docs to pull from the database.
+        if not self._has_more:
+            return
+
+        # Pull in ITER_CHUNK_SIZE docs from the database and store them in
+        # the result cache.
+        try:
+            for _ in range(ITER_CHUNK_SIZE):
+                self._result_cache.append(next(self))
+        except StopIteration:
+            # Getting this exception means there are no more docs in the
+            # db cursor. Set _has_more to False so that we can use that
+            # information in other places.
+            self._has_more = False
+
+    def count(self, with_limit_and_skip=False):
+        """Count the selected elements in the query.
+
+        :param with_limit_and_skip (optional): take any :meth:`limit` or
+            :meth:`skip` that has been applied to this cursor into account when
+            getting the count
+        """
+        if with_limit_and_skip is False:
+            return super().count(with_limit_and_skip)
+
+        if self._len is None:
+            # cache the length
+            self._len = super().count(with_limit_and_skip)
+
+        return self._len
+
+    def no_cache(self):
+        """Convert to a non-caching queryset"""
+        if self._result_cache is not None:
+            raise OperationError("QuerySet already cached")
+
+        return self._clone_into(QuerySetNoCache(self._document, self._collection))
+
+
+class QuerySetNoCache(BaseQuerySet):
+    """A non caching QuerySet"""
+
+    def cache(self):
+        """Convert to a caching queryset"""
+        return self._clone_into(QuerySet(self._document, self._collection))
+
+    def __repr__(self):
+        """Provides the string representation of the QuerySet"""
+        if self._iter:
+            return ".. queryset mid-iteration .."
+
+        data = []
+        for _ in range(REPR_OUTPUT_SIZE + 1):
+            try:
+                data.append(next(self))
+            except StopIteration:
+                break
+
+        if len(data) > REPR_OUTPUT_SIZE:
+            data[-1] = "...(remaining elements truncated)..."
+
+        self.rewind()
+        return repr(data)
+
+    def __iter__(self):
+        queryset = self
+        if queryset._iter:
+            queryset = self.clone()
+        queryset.rewind()
+        return queryset