sensu-plugins-mongodb-mrtrotl 1.4.0

data/lib/pymongo/operations.py

@@ -0,0 +1,507 @@
+# Copyright 2015-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Operation class definitions."""
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+
+from pymongo import helpers
+from pymongo.collation import validate_collation_or_none
+from pymongo.common import validate_boolean, validate_is_mapping, validate_list
+from pymongo.helpers import _gen_index_name, _index_document, _index_list
+from pymongo.typings import _CollationIn, _DocumentIn, _Pipeline
+
+
+class InsertOne(object):
+    """Represents an insert_one operation."""
+
+    __slots__ = ("_doc",)
+
+    def __init__(self, document: _DocumentIn) -> None:
+        """Create an InsertOne instance.
+
+        For use with :meth:`~pymongo.collection.Collection.bulk_write`.
+
+        :Parameters:
+          - `document`: The document to insert. If the document is missing an
+            _id field one will be added.
+        """
+        self._doc = document
+
+    def _add_to_bulk(self, bulkobj):
+        """Add this operation to the _Bulk instance `bulkobj`."""
+        bulkobj.add_insert(self._doc)
+
+    def __repr__(self):
+        return "InsertOne(%r)" % (self._doc,)
+
+    def __eq__(self, other: Any) -> bool:
+        if type(other) == type(self):
+            return other._doc == self._doc
+        return NotImplemented
+
+    def __ne__(self, other: Any) -> bool:
+        return not self == other
+
+
+_IndexList = Sequence[Tuple[str, Union[int, str, Mapping[str, Any]]]]
+_IndexKeyHint = Union[str, _IndexList]
+
+
+class DeleteOne(object):
+    """Represents a delete_one operation."""
+
+    __slots__ = ("_filter", "_collation", "_hint")
+
+    def __init__(
+        self,
+        filter: Mapping[str, Any],
+        collation: Optional[_CollationIn] = None,
+        hint: Optional[_IndexKeyHint] = None,
+    ) -> None:
+        """Create a DeleteOne instance.
+
+        For use with :meth:`~pymongo.collection.Collection.bulk_write`.
+
+        :Parameters:
+          - `filter`: A query that matches the document to delete.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`.
+          - `hint` (optional): An index to use to support the query
+            predicate specified either by its string name, or in the same
+            format as passed to
+            :meth:`~pymongo.collection.Collection.create_index` (e.g.
+            ``[('field', ASCENDING)]``). This option is only supported on
+            MongoDB 4.4 and above.
+
+        .. versionchanged:: 3.11
+           Added the ``hint`` option.
+        .. versionchanged:: 3.5
+           Added the `collation` option.
+        """
+        if filter is not None:
+            validate_is_mapping("filter", filter)
+        if hint is not None:
+            if not isinstance(hint, str):
+                hint = helpers._index_document(hint)
+        self._filter = filter
+        self._collation = collation
+        self._hint = hint
+
+    def _add_to_bulk(self, bulkobj):
+        """Add this operation to the _Bulk instance `bulkobj`."""
+        bulkobj.add_delete(self._filter, 1, collation=self._collation, hint=self._hint)
+
+    def __repr__(self):
+        return "DeleteOne(%r, %r)" % (self._filter, self._collation)
+
+    def __eq__(self, other: Any) -> bool:
+        if type(other) == type(self):
+            return (other._filter, other._collation) == (self._filter, self._collation)
+        return NotImplemented
+
+    def __ne__(self, other: Any) -> bool:
+        return not self == other
+
+
+class DeleteMany(object):
+    """Represents a delete_many operation."""
+
+    __slots__ = ("_filter", "_collation", "_hint")
+
+    def __init__(
+        self,
+        filter: Mapping[str, Any],
+        collation: Optional[_CollationIn] = None,
+        hint: Optional[_IndexKeyHint] = None,
+    ) -> None:
+        """Create a DeleteMany instance.
+
+        For use with :meth:`~pymongo.collection.Collection.bulk_write`.
+
+        :Parameters:
+          - `filter`: A query that matches the documents to delete.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`.
+          - `hint` (optional): An index to use to support the query
+            predicate specified either by its string name, or in the same
+            format as passed to
+            :meth:`~pymongo.collection.Collection.create_index` (e.g.
+            ``[('field', ASCENDING)]``). This option is only supported on
+            MongoDB 4.4 and above.
+
+        .. versionchanged:: 3.11
+           Added the ``hint`` option.
+        .. versionchanged:: 3.5
+           Added the `collation` option.
+        """
+        if filter is not None:
+            validate_is_mapping("filter", filter)
+        if hint is not None:
+            if not isinstance(hint, str):
+                hint = helpers._index_document(hint)
+        self._filter = filter
+        self._collation = collation
+        self._hint = hint
+
+    def _add_to_bulk(self, bulkobj):
+        """Add this operation to the _Bulk instance `bulkobj`."""
+        bulkobj.add_delete(self._filter, 0, collation=self._collation, hint=self._hint)
+
+    def __repr__(self):
+        return "DeleteMany(%r, %r)" % (self._filter, self._collation)
+
+    def __eq__(self, other: Any) -> bool:
+        if type(other) == type(self):
+            return (other._filter, other._collation) == (self._filter, self._collation)
+        return NotImplemented
+
+    def __ne__(self, other: Any) -> bool:
+        return not self == other
+
+
+class ReplaceOne(object):
+    """Represents a replace_one operation."""
+
+    __slots__ = ("_filter", "_doc", "_upsert", "_collation", "_hint")
+
+    def __init__(
+        self,
+        filter: Mapping[str, Any],
+        replacement: Mapping[str, Any],
+        upsert: bool = False,
+        collation: Optional[_CollationIn] = None,
+        hint: Optional[_IndexKeyHint] = None,
+    ) -> None:
+        """Create a ReplaceOne instance.
+
+        For use with :meth:`~pymongo.collection.Collection.bulk_write`.
+
+        :Parameters:
+          - `filter`: A query that matches the document to replace.
+          - `replacement`: The new document.
+          - `upsert` (optional): If ``True``, perform an insert if no documents
+            match the filter.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`.
+          - `hint` (optional): An index to use to support the query
+            predicate specified either by its string name, or in the same
+            format as passed to
+            :meth:`~pymongo.collection.Collection.create_index` (e.g.
+            ``[('field', ASCENDING)]``). This option is only supported on
+            MongoDB 4.2 and above.
+
+        .. versionchanged:: 3.11
+           Added the ``hint`` option.
+        .. versionchanged:: 3.5
+           Added the ``collation`` option.
+        """
+        if filter is not None:
+            validate_is_mapping("filter", filter)
+        if upsert is not None:
+            validate_boolean("upsert", upsert)
+        if hint is not None:
+            if not isinstance(hint, str):
+                hint = helpers._index_document(hint)
+
+        self._filter = filter
+        self._doc = replacement
+        self._upsert = upsert
+        self._collation = collation
+        self._hint = hint
+
+    def _add_to_bulk(self, bulkobj):
+        """Add this operation to the _Bulk instance `bulkobj`."""
+        bulkobj.add_replace(
+            self._filter, self._doc, self._upsert, collation=self._collation, hint=self._hint
+        )
+
+    def __eq__(self, other: Any) -> bool:
+        if type(other) == type(self):
+            return (other._filter, other._doc, other._upsert, other._collation, other._hint) == (
+                self._filter,
+                self._doc,
+                self._upsert,
+                self._collation,
+                other._hint,
+            )
+        return NotImplemented
+
+    def __ne__(self, other: Any) -> bool:
+        return not self == other
+
+    def __repr__(self):
+        return "%s(%r, %r, %r, %r, %r)" % (
+            self.__class__.__name__,
+            self._filter,
+            self._doc,
+            self._upsert,
+            self._collation,
+            self._hint,
+        )
+
+
+class _UpdateOp(object):
+    """Private base class for update operations."""
+
+    __slots__ = ("_filter", "_doc", "_upsert", "_collation", "_array_filters", "_hint")
+
+    def __init__(self, filter, doc, upsert, collation, array_filters, hint):
+        if filter is not None:
+            validate_is_mapping("filter", filter)
+        if upsert is not None:
+            validate_boolean("upsert", upsert)
+        if array_filters is not None:
+            validate_list("array_filters", array_filters)
+        if hint is not None:
+            if not isinstance(hint, str):
+                hint = helpers._index_document(hint)
+
+        self._filter = filter
+        self._doc = doc
+        self._upsert = upsert
+        self._collation = collation
+        self._array_filters = array_filters
+        self._hint = hint
+
+    def __eq__(self, other):
+        if type(other) == type(self):
+            return (
+                other._filter,
+                other._doc,
+                other._upsert,
+                other._collation,
+                other._array_filters,
+                other._hint,
+            ) == (
+                self._filter,
+                self._doc,
+                self._upsert,
+                self._collation,
+                self._array_filters,
+                self._hint,
+            )
+        return NotImplemented
+
+    def __ne__(self, other):
+        return not self == other
+
+    def __repr__(self):
+        return "%s(%r, %r, %r, %r, %r, %r)" % (
+            self.__class__.__name__,
+            self._filter,
+            self._doc,
+            self._upsert,
+            self._collation,
+            self._array_filters,
+            self._hint,
+        )
+
+
+class UpdateOne(_UpdateOp):
+    """Represents an update_one operation."""
+
+    __slots__ = ()
+
+    def __init__(
+        self,
+        filter: Mapping[str, Any],
+        update: Union[Mapping[str, Any], _Pipeline],
+        upsert: bool = False,
+        collation: Optional[_CollationIn] = None,
+        array_filters: Optional[List[Mapping[str, Any]]] = None,
+        hint: Optional[_IndexKeyHint] = None,
+    ) -> None:
+        """Represents an update_one operation.
+
+        For use with :meth:`~pymongo.collection.Collection.bulk_write`.
+
+        :Parameters:
+          - `filter`: A query that matches the document to update.
+          - `update`: The modifications to apply.
+          - `upsert` (optional): If ``True``, perform an insert if no documents
+            match the filter.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`.
+          - `array_filters` (optional): A list of filters specifying which
+            array elements an update should apply.
+          - `hint` (optional): An index to use to support the query
+            predicate specified either by its string name, or in the same
+            format as passed to
+            :meth:`~pymongo.collection.Collection.create_index` (e.g.
+            ``[('field', ASCENDING)]``). This option is only supported on
+            MongoDB 4.2 and above.
+
+        .. versionchanged:: 3.11
+           Added the `hint` option.
+        .. versionchanged:: 3.9
+           Added the ability to accept a pipeline as the `update`.
+        .. versionchanged:: 3.6
+           Added the `array_filters` option.
+        .. versionchanged:: 3.5
+           Added the `collation` option.
+        """
+        super(UpdateOne, self).__init__(filter, update, upsert, collation, array_filters, hint)
+
+    def _add_to_bulk(self, bulkobj):
+        """Add this operation to the _Bulk instance `bulkobj`."""
+        bulkobj.add_update(
+            self._filter,
+            self._doc,
+            False,
+            self._upsert,
+            collation=self._collation,
+            array_filters=self._array_filters,
+            hint=self._hint,
+        )
+
+
+class UpdateMany(_UpdateOp):
+    """Represents an update_many operation."""
+
+    __slots__ = ()
+
+    def __init__(
+        self,
+        filter: Mapping[str, Any],
+        update: Union[Mapping[str, Any], _Pipeline],
+        upsert: bool = False,
+        collation: Optional[_CollationIn] = None,
+        array_filters: Optional[List[Mapping[str, Any]]] = None,
+        hint: Optional[_IndexKeyHint] = None,
+    ) -> None:
+        """Create an UpdateMany instance.
+
+        For use with :meth:`~pymongo.collection.Collection.bulk_write`.
+
+        :Parameters:
+          - `filter`: A query that matches the documents to update.
+          - `update`: The modifications to apply.
+          - `upsert` (optional): If ``True``, perform an insert if no documents
+            match the filter.
+          - `collation` (optional): An instance of
+            :class:`~pymongo.collation.Collation`.
+          - `array_filters` (optional): A list of filters specifying which
+            array elements an update should apply.
+          - `hint` (optional): An index to use to support the query
+            predicate specified either by its string name, or in the same
+            format as passed to
+            :meth:`~pymongo.collection.Collection.create_index` (e.g.
+            ``[('field', ASCENDING)]``). This option is only supported on
+            MongoDB 4.2 and above.
+
+        .. versionchanged:: 3.11
+           Added the `hint` option.
+        .. versionchanged:: 3.9
+           Added the ability to accept a pipeline as the `update`.
+        .. versionchanged:: 3.6
+           Added the `array_filters` option.
+        .. versionchanged:: 3.5
+           Added the `collation` option.
+        """
+        super(UpdateMany, self).__init__(filter, update, upsert, collation, array_filters, hint)
+
+    def _add_to_bulk(self, bulkobj):
+        """Add this operation to the _Bulk instance `bulkobj`."""
+        bulkobj.add_update(
+            self._filter,
+            self._doc,
+            True,
+            self._upsert,
+            collation=self._collation,
+            array_filters=self._array_filters,
+            hint=self._hint,
+        )
+
+
+class IndexModel(object):
+    """Represents an index to create."""
+
+    __slots__ = ("__document",)
+
+    def __init__(self, keys: _IndexKeyHint, **kwargs: Any) -> None:
+        """Create an Index instance.
+
+        For use with :meth:`~pymongo.collection.Collection.create_indexes`.
+
+        Takes either a single key or a list of (key, direction) pairs.
+        The key(s) must be an instance of :class:`basestring`
+        (:class:`str` in python 3), and the direction(s) must be one of
+        (:data:`~pymongo.ASCENDING`, :data:`~pymongo.DESCENDING`,
+        :data:`~pymongo.GEO2D`, :data:`~pymongo.GEOSPHERE`,
+        :data:`~pymongo.HASHED`, :data:`~pymongo.TEXT`).
+
+        Valid options include, but are not limited to:
+
+          - `name`: custom name to use for this index - if none is
+            given, a name will be generated.
+          - `unique`: if ``True``, creates a uniqueness constraint on the index.
+          - `background`: if ``True``, this index should be created in the
+            background.
+          - `sparse`: if ``True``, omit from the index any documents that lack
+            the indexed field.
+          - `bucketSize`: for use with geoHaystack indexes.
+            Number of documents to group together within a certain proximity
+            to a given longitude and latitude.
+          - `min`: minimum value for keys in a :data:`~pymongo.GEO2D`
+            index.
+          - `max`: maximum value for keys in a :data:`~pymongo.GEO2D`
+            index.
+          - `expireAfterSeconds`: <int> Used to create an expiring (TTL)
+            collection. MongoDB will automatically delete documents from
+            this collection after <int> seconds. The indexed field must
+            be a UTC datetime or the data will not expire.
+          - `partialFilterExpression`: A document that specifies a filter for
+            a partial index.
+          - `collation`: An instance of :class:`~pymongo.collation.Collation`
+            that specifies the collation to use.
+          - `wildcardProjection`: Allows users to include or exclude specific
+            field paths from a `wildcard index`_ using the { "$**" : 1} key
+            pattern. Requires MongoDB >= 4.2.
+          - `hidden`: if ``True``, this index will be hidden from the query
+            planner and will not be evaluated as part of query plan
+            selection. Requires MongoDB >= 4.4.
+
+        See the MongoDB documentation for a full list of supported options by
+        server version.
+
+        :Parameters:
+          - `keys`: a single key or a list of (key, direction)
+            pairs specifying the index to create
+          - `**kwargs` (optional): any additional index creation
+            options (see the above list) should be passed as keyword
+            arguments
+
+        .. versionchanged:: 3.11
+           Added the ``hidden`` option.
+        .. versionchanged:: 3.2
+           Added the ``partialFilterExpression`` option to support partial
+           indexes.
+
+        .. _wildcard index: https://mongodb.com/docs/master/core/index-wildcard/
+        """
+        keys = _index_list(keys)
+        if "name" not in kwargs:
+            kwargs["name"] = _gen_index_name(keys)
+        kwargs["key"] = _index_document(keys)
+        collation = validate_collation_or_none(kwargs.pop("collation", None))
+        self.__document = kwargs
+        if collation is not None:
+            self.__document["collation"] = collation
+
+    @property
+    def document(self) -> Dict[str, Any]:
+        """An index document suitable for passing to the createIndexes
+        command.
+        """
+        return self.__document

data/lib/pymongo/periodic_executor.py

@@ -0,0 +1,183 @@
+# Copyright 2014-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you
+# may not use this file except in compliance with the License.  You
+# may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.  See the License for the specific language governing
+# permissions and limitations under the License.
+
+"""Run a target function on a background thread."""
+
+import threading
+import time
+import weakref
+from typing import Any, Optional
+
+
+class PeriodicExecutor(object):
+    def __init__(self, interval, min_interval, target, name=None):
+        """ "Run a target function periodically on a background thread.
+
+        If the target's return value is false, the executor stops.
+
+        :Parameters:
+          - `interval`: Seconds between calls to `target`.
+          - `min_interval`: Minimum seconds between calls if `wake` is
+            called very often.
+          - `target`: A function.
+          - `name`: A name to give the underlying thread.
+        """
+        # threading.Event and its internal condition variable are expensive
+        # in Python 2, see PYTHON-983. Use a boolean to know when to wake.
+        # The executor's design is constrained by several Python issues, see
+        # "periodic_executor.rst" in this repository.
+        self._event = False
+        self._interval = interval
+        self._min_interval = min_interval
+        self._target = target
+        self._stopped = False
+        self._thread: Optional[threading.Thread] = None
+        self._name = name
+        self._skip_sleep = False
+
+        self._thread_will_exit = False
+        self._lock = threading.Lock()
+
+    def __repr__(self):
+        return "<%s(name=%s) object at 0x%x>" % (self.__class__.__name__, self._name, id(self))
+
+    def open(self) -> None:
+        """Start. Multiple calls have no effect.
+
+        Not safe to call from multiple threads at once.
+        """
+        with self._lock:
+            if self._thread_will_exit:
+                # If the background thread has read self._stopped as True
+                # there is a chance that it has not yet exited. The call to
+                # join should not block indefinitely because there is no
+                # other work done outside the while loop in self._run.
+                try:
+                    assert self._thread is not None
+                    self._thread.join()
+                except ReferenceError:
+                    # Thread terminated.
+                    pass
+            self._thread_will_exit = False
+            self._stopped = False
+        started: Any = False
+        try:
+            started = self._thread and self._thread.is_alive()
+        except ReferenceError:
+            # Thread terminated.
+            pass
+
+        if not started:
+            thread = threading.Thread(target=self._run, name=self._name)
+            thread.daemon = True
+            self._thread = weakref.proxy(thread)
+            _register_executor(self)
+            thread.start()
+
+    def close(self, dummy: Any = None) -> None:
+        """Stop. To restart, call open().
+
+        The dummy parameter allows an executor's close method to be a weakref
+        callback; see monitor.py.
+        """
+        self._stopped = True
+
+    def join(self, timeout: Optional[int] = None) -> None:
+        if self._thread is not None:
+            try:
+                self._thread.join(timeout)
+            except (ReferenceError, RuntimeError):
+                # Thread already terminated, or not yet started.
+                pass
+
+    def wake(self) -> None:
+        """Execute the target function soon."""
+        self._event = True
+
+    def update_interval(self, new_interval: int) -> None:
+        self._interval = new_interval
+
+    def skip_sleep(self) -> None:
+        self._skip_sleep = True
+
+    def __should_stop(self):
+        with self._lock:
+            if self._stopped:
+                self._thread_will_exit = True
+                return True
+            return False
+
+    def _run(self):
+        while not self.__should_stop():
+            try:
+                if not self._target():
+                    self._stopped = True
+                    break
+            except BaseException:
+                with self._lock:
+                    self._stopped = True
+                    self._thread_will_exit = True
+
+                raise
+
+            if self._skip_sleep:
+                self._skip_sleep = False
+            else:
+                deadline = time.monotonic() + self._interval
+                while not self._stopped and time.monotonic() < deadline:
+                    time.sleep(self._min_interval)
+                    if self._event:
+                        break  # Early wake.
+
+            self._event = False
+
+
+# _EXECUTORS has a weakref to each running PeriodicExecutor. Once started,
+# an executor is kept alive by a strong reference from its thread and perhaps
+# from other objects. When the thread dies and all other referrers are freed,
+# the executor is freed and removed from _EXECUTORS. If any threads are
+# running when the interpreter begins to shut down, we try to halt and join
+# them to avoid spurious errors.
+_EXECUTORS = set()
+
+
+def _register_executor(executor):
+    ref = weakref.ref(executor, _on_executor_deleted)
+    _EXECUTORS.add(ref)
+
+
+def _on_executor_deleted(ref):
+    _EXECUTORS.remove(ref)
+
+
+def _shutdown_executors():
+    if _EXECUTORS is None:
+        return
+
+    # Copy the set. Stopping threads has the side effect of removing executors.
+    executors = list(_EXECUTORS)
+
+    # First signal all executors to close...
+    for ref in executors:
+        executor = ref()
+        if executor:
+            executor.close()
+
+    # ...then try to join them.
+    for ref in executors:
+        executor = ref()
+        if executor:
+            executor.join(1)
+
+    executor = None