xtquant.xtbson.bson36.regex

  1# Copyright 2013-present MongoDB, Inc.
  2#
  3# Licensed under the Apache License, Version 2.0 (the "License");
  4# you may not use this file except in compliance with the License.
  5# You may obtain a copy of the License at
  6#
  7# http://www.apache.org/licenses/LICENSE-2.0
  8#
  9# Unless required by applicable law or agreed to in writing, software
 10# distributed under the License is distributed on an "AS IS" BASIS,
 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 12# See the License for the specific language governing permissions and
 13# limitations under the License.
 14
 15"""Tools for representing MongoDB regular expressions.
 16"""
 17
 18import re
 19
 20from ._helpers import _getstate_slots, _setstate_slots
 21from .son import RE_TYPE
 22
 23
 24def str_flags_to_int(str_flags):
 25    flags = 0
 26    if "i" in str_flags:
 27        flags |= re.IGNORECASE
 28    if "l" in str_flags:
 29        flags |= re.LOCALE
 30    if "m" in str_flags:
 31        flags |= re.MULTILINE
 32    if "s" in str_flags:
 33        flags |= re.DOTALL
 34    if "u" in str_flags:
 35        flags |= re.UNICODE
 36    if "x" in str_flags:
 37        flags |= re.VERBOSE
 38
 39    return flags
 40
 41
 42class Regex(object):
 43    """BSON regular expression data."""
 44
 45    __slots__ = ("pattern", "flags")
 46
 47    __getstate__ = _getstate_slots
 48    __setstate__ = _setstate_slots
 49
 50    _type_marker = 11
 51
 52    @classmethod
 53    def from_native(cls, regex):
 54        """Convert a Python regular expression into a ``Regex`` instance.
 55
 56        Note that in Python 3, a regular expression compiled from a
 57        :class:`str` has the ``re.UNICODE`` flag set. If it is undesirable
 58        to store this flag in a BSON regular expression, unset it first::
 59
 60          >>> pattern = re.compile('.*')
 61          >>> regex = Regex.from_native(pattern)
 62          >>> regex.flags ^= re.UNICODE
 63          >>> db.collection.insert_one({'pattern': regex})
 64
 65        :Parameters:
 66          - `regex`: A regular expression object from ``re.compile()``.
 67
 68        .. warning::
 69           Python regular expressions use a different syntax and different
 70           set of flags than MongoDB, which uses `PCRE`_. A regular
 71           expression retrieved from the server may not compile in
 72           Python, or may match a different set of strings in Python than
 73           when used in a MongoDB query.
 74
 75        .. _PCRE: http://www.pcre.org/
 76        """
 77        if not isinstance(regex, RE_TYPE):
 78            raise TypeError("regex must be a compiled regular expression, not %s" % type(regex))
 79
 80        return Regex(regex.pattern, regex.flags)
 81
 82    def __init__(self, pattern, flags=0):
 83        """BSON regular expression data.
 84
 85        This class is useful to store and retrieve regular expressions that are
 86        incompatible with Python's regular expression dialect.
 87
 88        :Parameters:
 89          - `pattern`: string
 90          - `flags`: (optional) an integer bitmask, or a string of flag
 91            characters like "im" for IGNORECASE and MULTILINE
 92        """
 93        if not isinstance(pattern, (str, bytes)):
 94            raise TypeError("pattern must be a string, not %s" % type(pattern))
 95        self.pattern = pattern
 96
 97        if isinstance(flags, str):
 98            self.flags = str_flags_to_int(flags)
 99        elif isinstance(flags, int):
100            self.flags = flags
101        else:
102            raise TypeError("flags must be a string or int, not %s" % type(flags))
103
104    def __eq__(self, other):
105        if isinstance(other, Regex):
106            return self.pattern == other.pattern and self.flags == other.flags
107        else:
108            return NotImplemented
109
110    __hash__ = None
111
112    def __ne__(self, other):
113        return not self == other
114
115    def __repr__(self):
116        return "Regex(%r, %r)" % (self.pattern, self.flags)
117
118    def try_compile(self):
119        """Compile this :class:`Regex` as a Python regular expression.
120
121        .. warning::
122           Python regular expressions use a different syntax and different
123           set of flags than MongoDB, which uses `PCRE`_. A regular
124           expression retrieved from the server may not compile in
125           Python, or may match a different set of strings in Python than
126           when used in a MongoDB query. :meth:`try_compile()` may raise
127           :exc:`re.error`.
128
129        .. _PCRE: http://www.pcre.org/
130        """
131        return re.compile(self.pattern, self.flags)