Source code for boxsdk.object.search

# coding: utf-8

from __future__ import unicode_literals, absolute_import

import json

from .base_endpoint import BaseEndpoint
from ..pagination.limit_offset_based_object_collection import LimitOffsetBasedObjectCollection
from ..util.api_call_decorator import api_call
from ..util.text_enum import TextEnum



[docs]class SearchScope(TextEnum):
    """Enum of possible serach scopes."""
    USER = 'user_content'
    ENTERPRISE = 'enterprise_content'




[docs]class TrashContent(TextEnum):
    """Enum of trash content values."""
    NONE = 'non_trashed_only'
    ONLY = 'trashed_only'




[docs]class MetadataSearchFilter(object):
    """
    Helper class to encapsulate a single search filter. A search filter can only search against one template,
    but can filter on many fields.
    See :class:`MetadataSearchFilters`.
    """
    def __init__(self, template_key, scope):
        """
        :param template_key:
            The key of the template to search on
        :type template_key:
            `unicode`
        :param scope:
            The scope of the template to search on
        :type scope:
            `unicode`
        """
        self._template_key = template_key
        self._scope = scope
        self._field_filters = {}


[docs]    def as_dict(self):
        """
        Returns a `dict` representation of this object

        :return:
            The `dict` representation
        :rtype:
            `dict`
        """
        return {
            'templateKey': self._template_key,
            'scope': self._scope,
            'filters': self._field_filters
        }



[docs]    def add_value_based_filter(self, field_key, value):
        """
        Add a value-based filter (used for token-based search on string fields, and exact match search on all other fields)

        :param field_key:
            The field key to filter on
        :type field_filter:
            `unicode`
        :param value:
            The value to use to filter
        :type value:
            `unicode`
        """
        self._field_filters.update({field_key: value})



[docs]    def add_range_filter(self, field_key, gt_value=None, lt_value=None):
        """
        Add a range filter (used for ranged searches on numbers and dates)

        :param field_key:
            The field key to filter on
        :type field_filter:
            `unicode`
        :param gt_value:
            The lower bound of the range filter (inclusive)
        :type gt_value:
            `unicode` or `int` or `float` or `long` or None
        :param lt_value:
            The upper bound of the range filter (inclusive)
        :type lt_value:
            `unicode` or `int` or `float` or `long` or None
        """
        range_part = {}
        if gt_value:
            range_part['gt'] = gt_value
        if lt_value:
            range_part['lt'] = lt_value
        if not range_part:
            raise ValueError('Should specify gt and/or lt')
        self._field_filters.update({field_key: range_part})




[docs]class MetadataSearchFilters(object):
    """
    Helper class to encapsulate a list of metadata search filter params (mdfilters API param)
    See https://developers.box.com/metadata-api/#search for more details
    """
    def __init__(self):
        self._filters = []


[docs]    def as_list(self):
        """
        Get a list of filters from this object to use as a parameter in the Search API

        :return:
            The list of filters
        :rtype:
            `list` of `dict`
        """
        return [metadata_filter.as_dict() for metadata_filter in self._filters]



[docs]    def add_filter(self, metadata_filter):
        """
        Add a filter to this object. Note that the API only supports one filter.

        :param metadata_filter:
            The filter to add
        :type metadata_filter:
            :class:`MetadataSearchFilter`
        """
        self._filters.append(metadata_filter)