Get filtered resources of the given resource class.

        This should be called on sub-classes only.

        The include argument allows relationship fetches to be
        optimized by including the target resources in the request of
        the containing resource. For example::

        .. code-block:: python

            org = Organization.singleton(session, include=[Sensor])
            org.sensors(use_included=True)

        Will fetch the sensors for the authorized organization as part
        of retrieving the organization. The ``use_included`` forces
        the use of included resources and avoids making a separate
        request to get the sensors for the organization.

        The metadata argument enables filtering on resources that
        support metadata filters. For example::

        .. code-block:: python

            sensors = Sensor.where(session, metadata={ 'asset_id': '23456' })

        Will fetch all sensors that match the given metadata attribute.

        The filter argument enables filtering the resulting resources
        based on a passed in function. For example::

        .. code-block::python

            sensors = Sensor.where(session, filter=lambda s: s.name.startswith("a"))

        Will fetch all sensors and apply the given filter to only
        return sensors who's name start with the given string.


        Args:

            session(Session): The session to look up the resources in

        Keyword Args:

            incldue(list): The resource classes to include in the
                request.

            metadata(dict or list): The metadata filter to apply

        Returns:

            iterable(Resource): An iterator over all found resources
                of this type

def where(cls, session, include=None, metadata=None, filter=None):
        """Get filtered resources of the given resource class.

        This should be called on sub-classes only.

        The include argument allows relationship fetches to be
        optimized by including the target resources in the request of
        the containing resource. For example::

        .. code-block:: python

            org = Organization.singleton(session, include=[Sensor])
            org.sensors(use_included=True)

        Will fetch the sensors for the authorized organization as part
        of retrieving the organization. The ``use_included`` forces
        the use of included resources and avoids making a separate
        request to get the sensors for the organization.

        The metadata argument enables filtering on resources that
        support metadata filters. For example::

        .. code-block:: python

            sensors = Sensor.where(session, metadata={ 'asset_id': '23456' })

        Will fetch all sensors that match the given metadata attribute.

        The filter argument enables filtering the resulting resources
        based on a passed in function. For example::

        .. code-block::python

            sensors = Sensor.where(session, filter=lambda s: s.name.startswith("a"))

        Will fetch all sensors and apply the given filter to only
        return sensors who's name start with the given string.


        Args:

            session(Session): The session to look up the resources in

        Keyword Args:

            incldue(list): The resource classes to include in the
                request.

            metadata(dict or list): The metadata filter to apply

        Returns:

            iterable(Resource): An iterator over all found resources
                of this type

        """
        url = session._build_url(cls._resource_path())
        params = build_request_include(include, None)
        if metadata is not None:
            params['filter[metadata]'] = to_json(metadata)
        process = cls._mk_many(session, include=include, filter=filter)
        return session.get(url, CB.json(200, process), params=params)