Merge pull request #542 from dhermes/sphinx-document-all-public

Sphinx: document all public modules

docs/datastore-api.rst

@@ -23,8 +23,16 @@ Connections
   :undoc-members:
   :show-inheritance:
 
+Interacting with the API
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: gcloud.datastore.api
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
 Helper functions
 ~~~~~~~~~~~~~~~~
 
 .. automodule:: gcloud.datastore.helpers
-  :members:
+  :members:

docs/gcloud-api.rst

@@ -0,0 +1,30 @@
+.. toctree::
+  :maxdepth: 1
+  :hidden:
+
+GCloud Package
+--------------
+
+:mod:`gcloud`
+~~~~~~~~~~~~~
+
+.. automodule:: gcloud.__init__
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+Connections
+~~~~~~~~~~~
+
+.. automodule:: gcloud.connection
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+Credentials
+~~~~~~~~~~~
+
+.. automodule:: gcloud.credentials
+  :members:
+  :undoc-members:
+  :show-inheritance:

docs/index.rst

@@ -2,6 +2,7 @@
   :maxdepth: 0
   :hidden:
 
+  gcloud-api
   datastore-api
   datastore-entities
   datastore-keys

gcloud/credentials.py

@@ -26,11 +26,12 @@ def get_credentials():
       which uses this method under the hood.
 
     Checks environment in order of precedence:
-    - Google App Engine (production and testing)
-    - Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to
+
+    * Google App Engine (production and testing)
+    * Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to
       a file with stored credentials information.
-    - Stored "well known" file associated with ``gcloud`` command line tool.
-    - Google Compute Engine production environment.
+    * Stored "well known" file associated with ``gcloud`` command line tool.
+    * Google Compute Engine production environment.
 
     The file referred to in GOOGLE_APPLICATION_CREDENTIALS is expected to
     contain information about credentials that are ready to use. This means

gcloud/datastore/batch.py

@@ -21,7 +21,7 @@ class Local(object):
 
 from gcloud.datastore import _implicit_environ
 from gcloud.datastore import helpers
-from gcloud.datastore import datastore_v1_pb2 as datastore_pb
+from gcloud.datastore import _datastore_v1_pb2 as datastore_pb
 
 
 class _Batches(Local):
@@ -164,7 +164,7 @@ def mutation(self):
         This getter returns the Mutation protobuf that
         has been built-up so far.
 
-        :rtype: :class:`gcloud.datastore.datastore_v1_pb2.Mutation`
+        :rtype: :class:`gcloud.datastore._datastore_v1_pb2.Mutation`
         :returns: The Mutation protobuf to be sent in the commit request.
         """
         return self._mutation
@@ -286,7 +286,7 @@ def _assign_entity_to_mutation(mutation_pb, entity, auto_id_entities):
 
     Helper method for ``Batch.put``.
 
-    :type mutation_pb: :class:`gcloud.datastore.datastore_v1_pb2.Mutation`
+    :type mutation_pb: :class:`gcloud.datastore._datastore_v1_pb2.Mutation`
     :param mutation_pb; the Mutation protobuf for the batch / transaction.
 
     :type entity: :class:`gcloud.datastore.entity.Entity`

gcloud/datastore/connection.py

@@ -17,7 +17,7 @@
 import six
 
 from gcloud import connection
-from gcloud.datastore import datastore_v1_pb2 as datastore_pb
+from gcloud.datastore import _datastore_v1_pb2 as datastore_pb
 from gcloud.datastore import helpers
 
 
@@ -132,8 +132,8 @@ def lookup(self, dataset_id, key_pbs,
         Maps the ``DatastoreService.Lookup`` protobuf RPC.
 
         This method deals only with protobufs
-        (:class:`gcloud.datastore.datastore_v1_pb2.Key` and
-        :class:`gcloud.datastore.datastore_v1_pb2.Entity`) and is used
+        (:class:`gcloud.datastore._datastore_v1_pb2.Key` and
+        :class:`gcloud.datastore._datastore_v1_pb2.Entity`) and is used
         under the hood in :func:`gcloud.datastore.get`:
 
         >>> from gcloud import datastore
@@ -150,7 +150,7 @@ def lookup(self, dataset_id, key_pbs,
         :type dataset_id: string
         :param dataset_id: The ID of the dataset to look up the keys.
 
-        :type key_pbs: list of :class:`gcloud.datastore.datastore_v1_pb2.Key`
+        :type key_pbs: list of :class:`gcloud.datastore._datastore_v1_pb2.Key`
                        (or a single Key)
         :param key_pbs: The key (or keys) to retrieve from the datastore.
 
@@ -174,7 +174,7 @@ def lookup(self, dataset_id, key_pbs,
                                the given transaction.  Incompatible with
                                ``eventual==True``.
 
-        :rtype: list of :class:`gcloud.datastore.datastore_v1_pb2.Entity`
+        :rtype: list of :class:`gcloud.datastore._datastore_v1_pb2.Entity`
                 (or a single Entity)
         :returns: The entities corresponding to the keys provided.
                   If a single key was provided and no results matched,
@@ -257,7 +257,7 @@ def run_query(self, dataset_id, query_pb, namespace=None,
         :type dataset_id: string
         :param dataset_id: The ID of the dataset over which to run the query.
 
-        :type query_pb: :class:`gcloud.datastore.datastore_v1_pb2.Query`
+        :type query_pb: :class:`gcloud.datastore._datastore_v1_pb2.Query`
         :param query_pb: The Protobuf representing the query to run.
 
         :type namespace: string
@@ -302,7 +302,7 @@ def begin_transaction(self, dataset_id, serializable=False):
                              transaction should be SERIALIZABLE (True) or
                              SNAPSHOT (False).
 
-        :rtype: :class:`.datastore_v1_pb2.BeginTransactionResponse`
+        :rtype: :class:`._datastore_v1_pb2.BeginTransactionResponse`
         :returns': the result protobuf for the begin transaction request.
         """
         request = datastore_pb.BeginTransactionRequest()
@@ -327,15 +327,15 @@ def commit(self, dataset_id, mutation_pb, transaction_id=None):
         :type dataset_id: string
         :param dataset_id: The ID dataset to which the transaction applies.
 
-        :type mutation_pb: :class:`gcloud.datastore.datastore_v1_pb2.Mutation`.
+        :type mutation_pb: :class:`datastore_pb.Mutation`.
         :param mutation_pb: The protobuf for the mutations being saved.
 
         :type transaction_id: string
         :param transaction_id: The transaction ID returned from
                                :meth:`begin_transaction`.  If not passed, the
                                commit will be non-transactional.
 
-        :rtype: :class:`gcloud.datastore.datastore_v1_pb2.MutationResult`.
+        :rtype: :class:`gcloud.datastore._datastore_v1_pb2.MutationResult`.
         :returns': the result protobuf for the mutation.
         """
         request = datastore_pb.CommitRequest()
@@ -379,10 +379,10 @@ def allocate_ids(self, dataset_id, key_pbs):
         :param dataset_id: The ID of the dataset to which the transaction
                            belongs.
 
-        :type key_pbs: list of :class:`gcloud.datastore.datastore_v1_pb2.Key`
+        :type key_pbs: list of :class:`gcloud.datastore._datastore_v1_pb2.Key`
         :param key_pbs: The keys for which the backend should allocate IDs.
 
-        :rtype: list of :class:`gcloud.datastore.datastore_v1_pb2.Key`
+        :rtype: list of :class:`gcloud.datastore._datastore_v1_pb2.Key`
         :returns: An equal number of keys,  with IDs filled in by the backend.
         """
         request = datastore_pb.AllocateIdsRequest()

gcloud/datastore/helpers.py

@@ -25,7 +25,7 @@
 import pytz
 import six
 
-from gcloud.datastore import datastore_v1_pb2 as datastore_pb
+from gcloud.datastore import _datastore_v1_pb2 as datastore_pb
 from gcloud.datastore.entity import Entity
 from gcloud.datastore.key import Key
 
@@ -38,7 +38,7 @@ def entity_from_protobuf(pb):
     The protobuf should be one returned from the Cloud Datastore
     Protobuf API.
 
-    :type pb: :class:`gcloud.datastore.datastore_v1_pb2.Entity`
+    :type pb: :class:`gcloud.datastore._datastore_v1_pb2.Entity`
     :param pb: The Protobuf representing the entity.
 
     :rtype: :class:`gcloud.datastore.entity.Entity`
@@ -60,7 +60,7 @@ def key_from_protobuf(pb):
     The protobuf should be one returned from the Cloud Datastore
     Protobuf API.
 
-    :type pb: :class:`gcloud.datastore.datastore_v1_pb2.Key`
+    :type pb: :class:`gcloud.datastore._datastore_v1_pb2.Key`
     :param pb: The Protobuf representing the key.
 
     :rtype: :class:`gcloud.datastore.key.Key`
@@ -161,7 +161,7 @@ def _get_value_from_value_pb(value_pb):
     Some work is done to coerce the return value into a more useful type
     (particularly in the case of a timestamp value, or a key value).
 
-    :type value_pb: :class:`gcloud.datastore.datastore_v1_pb2.Value`
+    :type value_pb: :class:`gcloud.datastore._datastore_v1_pb2.Value`
     :param value_pb: The Value Protobuf.
 
     :returns: The value provided by the Protobuf.
@@ -210,7 +210,7 @@ def _get_value_from_property_pb(property_pb):
     Some work is done to coerce the return value into a more useful type
     (particularly in the case of a timestamp value, or a key value).
 
-    :type property_pb: :class:`gcloud.datastore.datastore_v1_pb2.Property`
+    :type property_pb: :class:`gcloud.datastore._datastore_v1_pb2.Property`
     :param property_pb: The Property Protobuf.
 
     :returns: The value provided by the Protobuf.
@@ -227,7 +227,7 @@ def _set_protobuf_value(value_pb, val):
     Some value types (entities, keys, lists) cannot be directly
     assigned; this function handles them correctly.
 
-    :type value_pb: :class:`gcloud.datastore.datastore_v1_pb2.Value`
+    :type value_pb: :class:`gcloud.datastore._datastore_v1_pb2.Value`
     :param value_pb: The value protobuf to which the value is being assigned.
 
     :type val: `datetime.datetime`, boolean, float, integer, string,
@@ -264,10 +264,10 @@ def _set_protobuf_value(value_pb, val):
 def _prepare_key_for_request(key_pb):
     """Add protobuf keys to a request object.
 
-    :type key_pb: :class:`gcloud.datastore.datastore_v1_pb2.Key`
+    :type key_pb: :class:`gcloud.datastore._datastore_v1_pb2.Key`
     :param key_pb: A key to be added to a request.
 
-    :rtype: :class:`gcloud.datastore.datastore_v1_pb2.Key`
+    :rtype: :class:`gcloud.datastore._datastore_v1_pb2.Key`
     :returns: A key which will be added to a request. It will be the
               original if nothing needs to be changed.
     """
@@ -294,7 +294,7 @@ def _add_keys_to_request(request_field_pb, key_pbs):
     :type request_field_pb: `RepeatedCompositeFieldContainer`
     :param request_field_pb: A repeated proto field that contains keys.
 
-    :type key_pbs: list of :class:`gcloud.datastore.datastore_v1_pb2.Key`
+    :type key_pbs: list of :class:`gcloud.datastore._datastore_v1_pb2.Key`
     :param key_pbs: The keys to add to a request.
     """
     for key_pb in key_pbs:

gcloud/datastore/key.py

@@ -19,7 +19,7 @@
 import six
 
 from gcloud.datastore import _implicit_environ
-from gcloud.datastore import datastore_v1_pb2 as datastore_pb
+from gcloud.datastore import _datastore_v1_pb2 as datastore_pb
 
 
 class Key(object):
@@ -197,7 +197,7 @@ def completed_key(self, id_or_name):
     def to_protobuf(self):
         """Return a protobuf corresponding to the key.
 
-        :rtype: :class:`gcloud.datastore.datastore_v1_pb2.Key`
+        :rtype: :class:`gcloud.datastore._datastore_v1_pb2.Key`
         :returns: The protobuf representing the key.
         """
         key = datastore_pb.Key()

gcloud/datastore/query.py

@@ -17,7 +17,7 @@
 import base64
 
 from gcloud.datastore import _implicit_environ
-from gcloud.datastore import datastore_v1_pb2 as datastore_pb
+from gcloud.datastore import _datastore_v1_pb2 as datastore_pb
 from gcloud.datastore import helpers
 from gcloud.datastore.key import Key
 from gcloud.datastore.transaction import Transaction
@@ -432,7 +432,7 @@ def _pb_from_query(query):
     :type query: :class:`Query`
     :param query: The source query.
 
-    :rtype: :class:`gcloud.datastore.datastore_v1_pb2.Query`
+    :rtype: :class:`gcloud.datastore._datastore_v1_pb2.Query`
     :returns: A protobuf that can be sent to the protobuf API.  N.b. that
               it does not contain "in-flight" fields for ongoing query
               executions (cursors, offset, limit).

gcloud/datastore/test_api.py

@@ -143,7 +143,7 @@ def test_miss(self):
         self.assertEqual(results, [])
 
     def test_miss_w_missing(self):
-        from gcloud.datastore import datastore_v1_pb2 as datastore_pb
+        from gcloud.datastore import _datastore_v1_pb2 as datastore_pb
         from gcloud.datastore.key import Key
         from gcloud.datastore.test_connection import _Connection
 
@@ -189,7 +189,7 @@ def test_miss_w_deferred(self):
 
     def _make_entity_pb(self, dataset_id, kind, integer_id,
                         name=None, str_val=None):
-        from gcloud.datastore import datastore_v1_pb2 as datastore_pb
+        from gcloud.datastore import _datastore_v1_pb2 as datastore_pb
 
         entity_pb = datastore_pb.Entity()
         entity_pb.key.partition_id.dataset_id = dataset_id

gcloud/datastore/test_batch.py

@@ -66,7 +66,7 @@ def test_ctor_missing_required(self):
             self.assertRaises(ValueError, self._makeOne, connection=object())
 
     def test_ctor_explicit(self):
-        from gcloud.datastore.datastore_v1_pb2 import Mutation
+        from gcloud.datastore._datastore_v1_pb2 import Mutation
         _DATASET = 'DATASET'
         connection = _Connection()
         batch = self._makeOne(dataset_id=_DATASET, connection=connection)
@@ -79,7 +79,7 @@ def test_ctor_explicit(self):
     def test_ctor_implicit(self):
         from gcloud._testing import _Monkey
         from gcloud.datastore import _implicit_environ
-        from gcloud.datastore.datastore_v1_pb2 import Mutation
+        from gcloud.datastore._datastore_v1_pb2 import Mutation
         DATASET_ID = 'DATASET'
         CONNECTION = _Connection()
 
@@ -398,8 +398,8 @@ def is_partial(self):
         return self._id is None
 
     def to_protobuf(self):
-        from gcloud.datastore import datastore_v1_pb2
-        key = self._key = datastore_v1_pb2.Key()
+        from gcloud.datastore import _datastore_v1_pb2
+        key = self._key = _datastore_v1_pb2.Key()
         # Don't assign it, because it will just get ripped out
         # key.partition_id.dataset_id = self.dataset_id