/gdata/codesearch/service.py

  1# -*- coding: utf-8 -*-
  2#
  3# Copyright (c) 2007 Benoit Chesneau <benoitc@metavers.net>
  4#
  5# Permission to use, copy, modify, and distribute this software for any
  6# purpose with or without fee is hereby granted, provided that the above
  7# copyright notice and this permission notice appear in all copies.
  8#
  9# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 10# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 11# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 12# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 13# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 14# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 15# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 16
 17
 18"""CodesearchService extends GDataService to streamline Google Codesearch 
 19operations"""
 20
 21
 22__author__ = 'Benoit Chesneau'
 23
 24
 25import atom
 26import gdata.service
 27import gdata.codesearch
 28
 29
 30class CodesearchService(gdata.service.GDataService): 
 31    """Client extension for Google codesearch service"""
 32
 33    def __init__(self, email=None, password=None, source=None,
 34                 server='www.google.com',  additional_headers=None, **kwargs):
 35        """Creates a client for the Google codesearch service.
 36
 37        Args:
 38          email: string (optional) The user's email address, used for
 39              authentication.
 40          password: string (optional) The user's password.
 41          source: string (optional) The name of the user's application.
 42          server: string (optional) The name of the server to which a connection
 43              will be opened. Default value: 'www.google.com'.
 44          **kwargs: The other parameters to pass to gdata.service.GDataService
 45              constructor.
 46        """
 47        gdata.service.GDataService.__init__(
 48            self, email=email, password=password, service='codesearch',
 49            source=source, server=server, additional_headers=additional_headers,
 50            **kwargs)
 51
 52    def Query(self, uri, converter=gdata.codesearch.CodesearchFeedFromString):
 53        """Queries the Codesearch feed and returns the resulting feed of
 54           entries.
 55
 56        Args:
 57        uri: string The full URI to be queried. This can contain query
 58             parameters, a hostname, or simply the relative path to a Document
 59             List feed. The DocumentQuery object is useful when constructing
 60             query parameters.
 61        converter: func (optional) A function which will be executed on the
 62                   retrieved item, generally to render it into a Python object.
 63                   By default the CodesearchFeedFromString function is used to
 64                   return a CodesearchFeed object. This is because most feed
 65                   queries will result in a feed and not a single entry.
 66
 67        Returns :
 68            A CodesearchFeed objects representing the feed returned by the server
 69        """
 70        return self.Get(uri, converter=converter)
 71
 72    def GetSnippetsFeed(self, text_query=None):
 73        """Retrieve Codesearch feed for a keyword
 74
 75        Args:
 76            text_query : string (optional) The contents of the q query parameter. This
 77                         string is URL escaped upon conversion to a URI.
 78        Returns:
 79            A CodesearchFeed objects representing the feed returned by the server
 80        """
 81
 82        query=gdata.codesearch.service.CodesearchQuery(text_query=text_query)
 83        feed = self.Query(query.ToUri())
 84        return feed
 85
 86
 87class CodesearchQuery(gdata.service.Query):
 88    """Object used to construct the query to the Google Codesearch feed. here only as a shorcut"""
 89
 90    def __init__(self, feed='/codesearch/feeds/search', text_query=None, 
 91            params=None, categories=None):
 92        """Constructor for Codesearch Query.
 93
 94        Args:
 95            feed: string (optional) The path for the feed. (e.g. '/codesearch/feeds/search')
 96            text_query: string (optional) The contents of the q query parameter. This
 97                        string is URL escaped upon conversion to a URI.
 98            params: dict (optional) Parameter value string pairs which become URL
 99                    params when translated to a URI. These parameters are added to
100                    the query's items.
101            categories: list (optional) List of category strings which should be
102                        included as query categories. See gdata.service.Query for
103                        additional documentation.
104
105        Yelds:
106            A CodesearchQuery object to construct a URI based on Codesearch feed
107        """
108
109        gdata.service.Query.__init__(self, feed, text_query, params, categories)