Initial commit of Cloud Search API

docs/_static/js/main.js

@@ -16,7 +16,7 @@ $('.headerlink').parent().each(function() {
 $('.side-nav').children('ul:nth-child(2)').children().each(function() {
   var itemName = $(this).text();
     if (itemName !== 'Datastore' && itemName !== 'Storage' &&
-        itemName !== 'Pub/Sub') {
+        itemName !== 'Pub/Sub' && itemName !== 'Search') {
       $(this).css('padding-left','2em');
   }
 });

docs/index.rst

@@ -10,6 +10,8 @@
   datastore-transactions
   datastore-batches
   datastore-dataset
+  search-api
+  search-usage
   storage-api
   storage-blobs
   storage-buckets

docs/search-api.rst

@@ -0,0 +1,6 @@
+.. toctree::
+  :maxdepth: 1
+  :hidden:
+
+Search
+------

docs/search-usage.rst

@@ -0,0 +1,314 @@
+Using the API
+=============
+
+Connection / Authorization
+--------------------------
+
+Implicitly use the default client:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> # The search module has the same methods as a client, using the default.
+  >>> search.list_indexes()  # API request
+  []
+
+Configure the default client:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> search.set_project_id('project-id')
+  >>> search.set_credentials(credentials)
+  >>> search.list_indexes()  # API request
+  []
+
+Explicitly use the default client:
+
+.. doctest::
+
+  >>> from gcloud.search import default_client as client
+  >>> # The default_client is equivalent to search.Client()
+  >>> client.list_indexes()  # API request
+  []
+
+Explicitly configure a client:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client(project_id='project-id', credentials=credentials)
+  >>> client.list_indexes()  # API request
+  []
+
+Manage indexes for a project
+----------------------------
+
+Create a new index:
+
+.. doctest::
+
+   >>> from gcloud import search
+   >>> client = search.Client()
+   >>> index = client.create_index('index_id')  # API request
+   >>> index.id
+   'index_id'
+
+Create a new index with a name:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.create_index('index_id', name='Name')  # API request
+  >>> index.name
+  'Name'
+
+Get or create an index:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_or_create_index('index_id')  # API request
+  >>> index.id
+  'index_id'
+
+List the indexes:
+
+.. doctest::
+
+   >>> from gcloud import search
+   >>> client = search.Client()
+   >>> [index.id for index in client.list_indexes()]  # API request
+   ['index_id']
+
+Retrieve an index:
+
+.. doctest::
+
+   >>> from gcloud import search
+   >>> client = search.Client()
+   >>> index = client.get_index('missing_index_id')  # API request
+   >>> index is None
+   True
+   >>> index = client.get_index('index_id')  # API request
+   >>> index.id
+   'index_id'
+
+Get an index without making an API request
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id', check=False)
+  >>> index.id
+  'index_id'
+
+Update an index:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id')  # API request
+  >>> index.name = 'Name'
+  >>> client.update_index(index)
+
+Delete an index by ID:
+
+.. doctest::
+
+   >>> from gcloud import search
+   >>> client = search.Client()
+   >>> client.delete_index('index_id')  # API request
+
+Delete an index:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id')  # API request
+  >>> index.id
+  'index_id'
+  >>> client.delete_index(index)  # API request
+
+Manage documents and fields
+---------------------------
+
+Create a document
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> document = search.Document('document_id', rank=0)
+  >>> document.id
+  'document_id'
+
+Add a field to a document
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> document = search.Document('document_id')
+  >>> document.add_field(search.Field('fieldname'))
+
+Add values to a field
+
+.. doctest::
+
+  >>> from datetime import datetime
+  >>> from gcloud import search
+  >>> field = search.Field('fieldname')
+  >>> field.add_value('string')
+  >>> # Tokenization field ignored for non-string values.
+  >>> field.add_value('<h1>string</h1>', tokenization='html')
+  >>> field.add_value('string', tokenization='atom')
+  >>> field.add_value('string', tokenization='text')
+  >>> field.add_value(1234)
+  >>> field.add_value(datetime.now())
+  >>> len(field.values)
+  9
+
+Add values to a field at initialization time
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> field = search.Field('fieldname', values=[
+          'string',
+          search.Value('<h1>string2</h1>', tokenization='html')
+          search.Value('string', tokenization='atom')])
+
+Add a single document to an index:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id')  # API request
+  >>> document = search.Document('document_id', rank=0)
+  >>> index.add_document(document)  # API request
+
+Add multiple documents to an index:
+
+.. doctest::
+
+   >>> from gcloud import search
+   >>> client = search.Client()
+   >>> index = client.get_index('index_id')  # API request
+   >>> documents = [search.Document('document_id')]
+   >>> index.add_documents(documents)  # API request
+
+Get a single document by ID:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id')  # API request
+  >>> document = index.get_document('missing_document_id')  # API request
+  >>> document is None
+  True
+  >>> document = index.get_document('document_id')  # API request
+  >>> document.fields
+  []
+
+Delete a document by ID:
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id')  # API request
+  >>> index.delete_document('document_id')  # API request
+  >>> index.delete_document('missing_document_id')  # API request
+
+Searching
+---------
+
+Create a query
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> query = search.Query('query text here')
+  >>> query.query
+  'query text here'
+
+Specify the fields to return in a query
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> query = search.Query('query text here', fields=['field1', 'field2'])
+  >>> query.fields
+  ['field1', 'field2']
+
+Set the sort order of a query
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> query = search.Query('query text here', order_by='field1')
+  >>> query.order_by
+  'field1'
+  >>> query2 = search.Query('query text here', order_by=['field2', 'field3'])
+  >>> query2.order_by
+  ['field2', 'field3']
+  >>> # Order descending by field1 and ascending by field2
+  >>> query4 = search.Query('query text here', order_by=['-field1', 'field2'])
+  >>> query3.order_by
+  ['-field1', 'field2']
+
+Set custom field expressions on a query
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> query = search.Query('query text here')
+  >>> query.add_field_expression('total_price', '(price + tax)')
+  >>> # We don't do any checks on the expression. These are checked at query time.
+  >>> query.add_field_expression('invalid', 'is_prime(num)')
+  >>> query.add_field_expression('bad_field', '(missing_field + tax)')
+
+Set custom field expressions at initialization time
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> query = search.Query('query text here', field_expressions={
+          'total_price': '(price + tax)'})
+
+Search an index
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id')  # API request
+  >>> matching = index.search(search.Query('query text here'))  # API request
+  >>> for document in matching:
+  ...   print document.id
+
+Search an index with a limit on number of results
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id')  # API request
+  >>> matching = index.search(search.Query('query text here'),
+  ...                         limit=42)  # API request
+
+Search an index with a custom page size (advanced)
+
+.. doctest::
+
+  >>> from gcloud import search
+  >>> client = search.Client()
+  >>> index = client.get_index('index_id')  # API request
+  >>> matching = index.search(search.Query('query text here'),
+  ...                         page_size=20)  # API request

gcloud/search/__init__.py

@@ -0,0 +1,27 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Search API wrapper.
+
+The main concepts with this API are:
+
+- :class:`gcloud.pubsub.topic.Topic` represents an endpoint to which messages
+  can be published using the Cloud Storage Pubsub API.
+
+- :class:`gcloud.pubsub.subscription.Subscription` represents a named
+  subscription (either pull or push) to a topic.
+"""
+
+from gcloud.search.client import Client
+from gcloud.search.connection import SCOPE