Fix #77 - Initialized cloud dns.

.travis.yml

@@ -0,0 +1,8 @@
+language: python
+python:
+ - "2.6"
+ - "2.7"
+# command to install dependencies
+install: "pip install . unittest2"
+# command to run tests
+script: nosetests

README.rst

@@ -1,28 +1,36 @@
-Google Cloud
-============
+Google Cloud Python Client
+==========================
 
-Official documentation
-----------------------
+The goal of this project is to make it really simple and Pythonic
+to use Google Cloud Platform services.
 
-If you just want to **use** the library
-(not contribute to it),
-check out the official documentation:
-http://GoogleCloudPlatform.github.io/gcloud-python/
+.. image:: https://travis-ci.org/GoogleCloudPlatform/gcloud-python.svg?branch=master
+ :target: https://travis-ci.org/GoogleCloudPlatform/gcloud-python
 
-Incredibly quick demo
----------------------
+Quickstart
+----------
 
-Start by cloning the repository::
+The library is ``pip``-installable::
 
- $ git clone git://github.com/GoogleCloudPlatform/gcloud-python.git
- $ cd gcloud
- $ python setup.py develop
+ $ pip install gcloud
+ $ python -m gcloud.storage.demo # Runs the storage demo!
+
+Documentation
+-------------
+
+- `gcloud docs (browse all services, quick-starts, walk-throughs) <http://GoogleCloudPlatform.github.io/gcloud-python/>`_
+- `gcloud.datastore API docs <http://googlecloudplatform.github.io/gcloud-python/datastore-api.html>`_
+- `gcloud.storage API docs <http://googlecloudplatform.github.io/gcloud-python/storage-api.html>`_
+- gcloud.bigquery API docs (*coming soon)*
+- gcloud.compute API docs *(coming soon)*
+- gcloud.dns API docs *(coming soon)*
+- gcloud.sql API docs *(coming soon)*
 
 I'm getting weird errors... Can you help?
 -----------------------------------------
 
-Chances are you have some dependency problems,
-if you're on Ubuntu,
+Chances are you have some dependency problems...
+If you're on Ubuntu,
 try installing the pre-compiled packages::
 
  $ sudo apt-get install python-crypto python-openssl libffi-dev
@@ -32,6 +40,7 @@ or try installing the development packages
 and then ``pip install`` the dependencies again::
 
  $ sudo apt-get install python-dev libssl-dev libffi-dev
+ $ pip install gcloud
 
 How do I build the docs?
 ------------------------
@@ -50,4 +59,23 @@ Make sure you have ``nose`` installed and::
 
  $ git clone git://github.com/GoogleCloudPlatform/gcloud-python.git
  $ pip install unittest2 nose
+ $ cd gcloud-python
  $ nosetests
+
+How can I contribute?
+---------------------
+
+Before we can accept any pull requests
+we have to jump through a couple of legal hurdles,
+primarily a Contributor License Agreement (CLA):
+
+- **If you are an individual writing original source code**
+ and you're sure you own the intellectual property,
+ then you'll need to sign an `individual CLA
+ <http://code.google.com/legal/individual-cla-v1.0.html>`_.
+- **If you work for a company that wants to allow you to contribute your work**,
+ then you'll need to sign a `corporate CLA
+ <http://code.google.com/legal/corporate-cla-v1.0.html>`_.
+
+You can sign these electronically (just scroll to the bottom).
+After that, we'll be able to accept your pull requests.

docs/index.rst

@@ -12,7 +12,7 @@ Google Cloud Python API
 
 .. warning::
  This library is **still under construction**
- and is **not** the official Google Python API client library.
+ and is **not** the official Google Cloud Python API client library.
 
 Getting started
 ---------------

docs/storage-getting-started.rst

@@ -217,10 +217,7 @@ otherwise you'll get an error.
 
 If you have a full bucket, you can delete it this way::
 
- >>> bucket = connection.get_bucket('my-bucket')
- >>> for key in bucket:
- ... key.delete()
- >>> bucket.delete()
+ >>> bucket = connection.get_bucket('my-bucket', force=True)
 
 Listing available buckets
 -------------------------

gcloud/connection.py

@@ -1,4 +1,8 @@
 import httplib2
+import json
+import urllib
+
+from gcloud import exceptions
 
 
 class Connection(object):
@@ -42,3 +46,83 @@ def http(self):
  self._http = self._credentials.authorize(self._http)
  return self._http
 
+
+class JsonConnection(Connection):
+
+ API_BASE_URL = 'https://www.googleapis.com'
+ """The base of the API call URL."""
+
+ _EMPTY = object()
+ """A pointer to represent an empty value for default arguments."""
+
+ def __init__(self, project=None, *args, **kwargs):
+
+ super(JsonConnection, self).__init__(*args, **kwargs)
+
+ self.project = project
+
+ def build_api_url(self, path, query_params=None, api_base_url=None,
+ api_version=None):
+
+ url = self.API_URL_TEMPLATE.format(
+ api_base_url=(api_base_url or self.API_BASE_URL),
+ api_version=(api_version or self.API_VERSION),
+ path=path)
+
+ query_params = query_params or {}
+ query_params.update({'project': self.project})
+ url += '?' + urllib.urlencode(query_params)
+
+ return url
+
+ def make_request(self, method, url, data=None, content_type=None,
+ headers=None):
+
+ headers = headers or {}
+ headers['Accept-Encoding'] = 'gzip'
+
+ if data:
+ content_length = len(str(data))
+ else:
+ content_length = 0
+
+ headers['Content-Length'] = content_length
+
+ if content_type:
+ headers['Content-Type'] = content_type
+
+ return self.http.request(uri=url, method=method, headers=headers,
+ body=data)
+
+ def api_request(self, method, path=None, query_params=None,
+ data=None, content_type=None,
+ api_base_url=None, api_version=None,
+ expect_json=True):
+
+ url = self.build_api_url(path=path, query_params=query_params,
+ api_base_url=api_base_url,
+ api_version=api_version)
+
+ # Making the executive decision that any dictionary
+ # data will be sent properly as JSON.
+ if data and isinstance(data, dict):
+ data = json.dumps(data)
+ content_type = 'application/json'
+
+ response, content = self.make_request(
+ method=method, url=url, data=data, content_type=content_type)
+
+ # TODO: Add better error handling.
+ if response.status == 404:
+ raise exceptions.NotFoundError(response, content)
+ elif not 200 <= response.status < 300:
+ raise exceptions.ConnectionError(response, content)
+
+ if content and expect_json:
+ # TODO: Better checking on this header for JSON.
+ content_type = response.get('content-type', '')
+ if not content_type.startswith('application/json'):
+ raise TypeError('Expected JSON, got %s' % content_type)
+ return json.loads(content)
+
+ return content

gcloud/datastore/query.py

@@ -3,6 +3,7 @@
 from gcloud.datastore import datastore_v1_pb2 as datastore_pb
 from gcloud.datastore import helpers
 from gcloud.datastore.entity import Entity
+from gcloud.datastore.key import Key
 
 
 # TODO: Figure out how to properly handle namespaces.
@@ -132,6 +133,72 @@ def filter(self, expression, value):
  setattr(property_filter.value, attr_name, pb_value)
  return clone
 
+ def ancestor(self, ancestor):
+ """Filter the query based on an ancestor.
+
+ This will return a clone of the current :class:`Query`
+ filtered by the ancestor provided.
+
+ For example::
+
+ >>> parent_key = Key.from_path('Person', '1')
+ >>> query = dataset.query('Person')
+ >>> filtered_query = query.ancestor(parent_key)
+
+ If you don't have a :class:`gcloud.datastore.key.Key` but just
+ know the path, you can provide that as well::
+
+ >>> query = dataset.query('Person')
+ >>> filtered_query = query.ancestor(['Person', '1'])
+
+ Each call to ``.ancestor()`` returns a cloned :class:`Query:,
+ however a query may only have one ancestor at a time.
+
+ :type ancestor: :class:`gcloud.datastore.key.Key` or list
+ :param ancestor: Either a Key or a path of the form
+ ``['Kind', 'id or name', 'Kind', 'id or name', ...]``.
+
+ :rtype: :class:`Query`
+ :returns: A Query filtered by the ancestor provided.
+ """
+
+ clone = self._clone()
+
+ # If an ancestor filter already exists, remove it.
+ for i, filter in enumerate(clone._pb.filter.composite_filter.filter):
+ property_filter = filter.property_filter
+ if property_filter.operator == datastore_pb.PropertyFilter.HAS_ANCESTOR:
+ del clone._pb.filter.composite_filter.filter[i]
+
+ # If we just deleted the last item, make sure to clear out the filter
+ # property all together.
+ if not clone._pb.filter.composite_filter.filter:
+ clone._pb.ClearField('filter')
+
+ # If the ancestor is None, just return (we already removed the filter).
+ if not ancestor:
+ return clone
+
+ # If a list was provided, turn it into a Key.
+ if isinstance(ancestor, list):
+ ancestor = Key.from_path(*ancestor)
+
+ # If we don't have a Key value by now, something is wrong.
+ if not isinstance(ancestor, Key):
+ raise TypeError('Expected list or Key, got %s.' % type(ancestor))
+
+ # Get the composite filter and add a new property filter.
+ composite_filter = clone._pb.filter.composite_filter
+ composite_filter.operator = datastore_pb.CompositeFilter.AND
+
+ # Filter on __key__ HAS_ANCESTOR == ancestor.
+ ancestor_filter = composite_filter.filter.add().property_filter
+ ancestor_filter.property.name = '__key__'
+ ancestor_filter.operator = datastore_pb.PropertyFilter.HAS_ANCESTOR
+ ancestor_filter.value.key_value.CopyFrom(ancestor.to_protobuf())
+
+ return clone
+
  def kind(self, *kinds):
  """Get or set the Kind of the Query.
 
@@ -244,4 +311,5 @@ def fetch(self, limit=None):
  entity_pbs = self.dataset().connection().run_query(
  query_pb=clone.to_protobuf(), dataset_id=self.dataset().id())
 
- return [Entity.from_protobuf(entity) for entity in entity_pbs]
+ return [Entity.from_protobuf(entity, dataset=self.dataset())
+ for entity in entity_pbs]

gcloud/dns/__init__.py

@@ -0,0 +1,92 @@
+"""Shortcut methods for getting set up with Google Cloud DNS.
+
+You'll typically use these to get started with the API:
+
+>>> import gcloud.dns
+>>> zone = gcloud.dns.get_zone('zone-name-here',
+ 'long-email@googleapis.com',
+ '/path/to/private.key')
+
+The main concepts with this API are:
+
+- :class:`gcloud.dns.connection.Connection`
+ which represents a connection between your machine
+ and the Cloud DNS API.
+
+- :class:`gcloud.dns.zone.Zone`
+ which represents a particular zone.
+"""
+
+
+__version__ = '0.1'
+
+# TODO: Allow specific scopes and authorization levels.
+SCOPE = ('https://www.googleapis.com/auth/cloud-platform',
+ 'https://www.googleapis.com/auth/ndev.clouddns.readonly',
+ 'https://www.googleapis.com/auth/ndev.clouddns.readwrite')
+"""The scope required for authenticating as a Cloud DNS consumer."""
+
+
+def get_connection(project, client_email, private_key_path):
+ """Shortcut method to establish a connection to Cloud DNS.
+
+ Use this if you are going to access several zones
+ with the same set of credentials:
+
+ >>> from gcloud import dns
+ >>> connection = dns.get_connection(project, email, key_path)
+ >>> zone1 = connection.get_zone('zone1')
+ >>> zone2 = connection.get_zone('zone2')
+
+ :type project: string
+ :param project: The name of the project to connect to.
+
+ :type client_email: string
+ :param client_email: The e-mail attached to the service account.
+
+ :type private_key_path: string
+ :param private_key_path: The path to a private key file (this file was
+ given to you when you created the service
+ account).
+
+ :rtype: :class:`gcloud.dns.connection.Connection`
+ :returns: A connection defined with the proper credentials.
+ """
+
+ from gcloud.credentials import Credentials
+ from gcloud.dns.connection import Connection
+
+ credentials = Credentials.get_for_service_account(
+ client_email, private_key_path, scope=SCOPE)
+ return Connection(project=project, credentials=credentials)
+
+
+def get_zone(zone, project, client_email, private_key_path):
+ """Shortcut method to establish a connection to a particular zone.
+
+ You'll generally use this as the first call to working with the API:
+
+ >>> from gcloud import dns
+ >>> zone = dns.get_zone(zone, project, email, key_path)
+
+ :type zone: string
+ :param zone: The id of the zone you want to use.
+ This is akin to a disk name on a file system.
+
+ :type project: string
+ :param project: The name of the project to connect to.
+
+ :type client_email: string
+ :param client_email: The e-mail attached to the service account.
+
+ :type private_key_path: string
+ :param private_key_path: The path to a private key file (this file was
+ given to you when you created the service
+ account).
+
+ :rtype: :class:`gcloud.dns.zone.Zone`
+ :returns: A zone with a connection using the provided credentials.
+ """
+
+ connection = get_connection(project, client_email, private_key_path)
+ return connection.get_zone(zone)