# Source code for sunlight.services.capitolwords

    # Copyright (c) Sunlight Labs, 2012 under the terms and conditions
    # of the LICENSE file.

    from sunlight.errors import InvalidRequestException, BadRequestException

    import sunlight.service
    import json

    service_url = "http://capitolwords.org/api"

    class capitolwords(sunlight.service.Service):
        """
        Bindings into the `CapitolWords project <http://capitolwords.org>`_.
        Keep in mind, as you use this wrapper, that this is a very thin translation
        layer from the API into Python. There's no object magic, so the docs on the
        API it's self will be as useful as any of these docstrings.

        Feel free to read up on the CapitolWords API in the
        `docs <http://capitolwords.org/api/>`_.

        If a request goes through and gets a normal response code, but the requested
        action is for whatever reason errorful, a
        :class:`sunlight.errors.InvalidRequestException` will be thrown with the
        error string.
        """

        def dates(self, phrase, **kwargs):
            """
            Retrieve information regarding the popularity of a phrase over a
            period of time.

            For a list of optional arguments see `Capitol Words' dates.json
            endpoint <http://capitolwords.org/api/#dates.json>`_.
            """
            kwargs['phrase'] = phrase
            return self.get( "dates", **kwargs )

        def phrases(self, entity_type, entity_value, **kwargs):
            """
            Retrieve information on the top phrases for an facet.

            A facet can be any date, month, state or legislator.

            For a list of arguments see `Capitol Words' phrases.json
            endpoint <http://capitolwords.org/api/#phrases.json>`_.
            """
            kwargs['entity_type']  = entity_type
            kwargs['entity_value'] = entity_value

            return self.get( "phrases", **kwargs )

        def phrases_by_entity(self, entity_type, **kwargs):
            """
            Get listing of top facets for a given phrase.

            A facet can be any date, month, state or legislator.

            For a list of arguments see `Capitol Words' phrases/entity.json
            endpoint <http://capitolwords.org/api/#phrases/entity.json>`_.
            """
            lss = "%s/%s" % ("phrases", entity_type)
            return self.get( lss, **kwargs )

        def text( self, phrase=None, title=None, **kwargs ):
            """
            Full text-search against Capitol Words data.

            Neither ``phrase`` nor ``title`` are required, but one or the other
            must be used. If both are omitted, a
            :class:`sunlight.errors.BadRequestException` will be thrown.

            ``phrase`` will do a full-text search on that phrase, whereas
            ``title`` will doa  full-text search on the title of each CR
            (Congressional Record) document.

            For a list of arguments see `Capitol Words' text.json
            endpoint <http://capitolwords.org/api/#text.json>`_.
            """
            if not phrase and not title:
                raise BadRequestException(
                    "You must provide one of phrase or title to this method.")

            if phrase:
                kwargs['phrase'] = phrase

            if title:
                kwargs['title']  = title

            return self.get( "text", **kwargs )

        # API impl methods below

        def _get_url( self, obj, apikey, **kwargs ):
            ret = "%s/%s.json?apikey=%s&%s" % (
                service_url,
                obj,
                apikey,
                sunlight.service.safe_encode(kwargs)
            )
            return ret

        def _decode_response( self, response ):
            ret = json.loads( response )
            if "error" in ret:
                ex = InvalidRequestException( ret['error'] )
                ex.response = ret
                raise ex
            if "results" in ret:
                return ret['results']
                # XXX: Verify this is actually
                #      what we want.
            return ret