Add optional 'connection' parameter for any method that hits the wire

[jgeewax]

From #796

@dhermes, @jgeewax could we make every API-triggering method take an optional connection argument, which would override the bound / default connection for only that call? Seems like that would be a useful pattern across all services; it would also help mark those methods as being API/latency relevant.

[dhermes]

Thanks for filing. That's the goal. Mentioned this in #728 and #632 but it's not really spelled out.

[tseaver]

datastore

Free API functions

• api.get
• api.put
• api.delete
• api.allocate_ids

batch.Batch methods

(note that Batch.__init__ takes a connection, handles fallback)

• Batch.commit No real usecase for an explicit connection, given that Batch exists purely as a wrapper/proxy for an existing connection.

dataset.Dataset methods

(note that Dataset.__init__ takes a connection, defaulting to None).

• Dataset.get (wraps api.get) (#825: Allow passing explicit connection to dataset API methods. #858)
• Dataset.put (wraps api.put) (#825: Allow passing explicit connection to dataset API methods. #858)
• Dataset.delete (wraps api.delete) (#825: Allow passing explicit connection to dataset API methods. #858)
• Dataset.batch (Batch instance holds connection) (#825: Allow passing explicit connection to dataset API methods. #858)
• Dataset.transaction (Transaction instance holds connection) (#825: Allow passing explicit connection to dataset API methods. #858)

query.Query methods

• Query.fetch (handles fallback, passes connection to Iterator)

transaction.Transaction methods

No real usecase for an explicit connection, given that Batch exists purely as a wrapper/proxy for an existing connection.

(note that Transaction.__init__ takes a connection, handles fallback via Batch.__init__)

• Transaction.begin
• Transaction.rollback
• Transaction.commit (delegates to Batch.commit)

pubsub

Free API functions

• api.list_topics
• api.list_subscriptions

subscription.Subscription methods

• Subscription.from_api_repr
• Subscription.create (uses self.topic.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Subscription.exists (uses self.topic.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Subscription.reload (uses self.topic.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Subscription.modify_push_configuration (uses self.topic.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Subscription.pull (uses self.topic.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Subscription.acknowledge (uses self.topic.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Subscription.modify_ack_deadline (uses self.topic.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Subscription.delete (uses self.topic.connection) (#825: Allow passing explicit connection to pubsub API methods #859)

topic.Topic methods:

(note that Topic.__init__ takes a connection, handles fallback)

• Topic.from_api_repr
• Topic.create (uses self.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Topic.exists (uses self.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Topic.publish (uses self.connection) (#825: Allow passing explicit connection to pubsub API methods #859)
• Topic.batch (delegates to _Batch instance) (#825: Allow passing explicit connection to pubsub API methods #859)
• Topic.delete (uses self.connection) (#825: Allow passing explicit connection to pubsub API methods #859)

topic._Batch methods:

• _Batch.commit (uses self.topic.connection, called from __exit__ when batch used as a context manager) (#825: Allow passing explicit connection to pubsub API methods #859)

storage

_helpers._PropertyMixin methods (inherited by Blob / Bucket)

• _PropertyMixin.reload (#825: Allow passing explicit connection to '_PropertyMixin.{reload,patch}'. #852)
• _PropertyMixin.patch (#825: Allow passing explicit connection to '_PropertyMixin.{reload,patch}'. #852)

acl.ACL methods

• ACL.reload (#825: Allow passing explicit connection to ACL.{reload,save} #853)
• ACL.save (#825: Allow passing explicit connection to ACL.{reload,save} #853)
• ACL.clear (#825: Allow passing explicit connection to ACL.{reload,save} #853)

acl.BucketACL methods

• BucketACL.reload (#825: Allow passing explicit connection to ACL.{reload,save} #853)
• BucketACL.save (#825: Allow passing explicit connection to ACL.{reload,save} #853)
• BucketACL.clear (#825: Allow passing explicit connection to ACL.{reload,save} #853)

acl.BlobACL methods

• BlobACL.reload (#825: Allow passing explicit connection to ACL.{reload,save} #853)
• BlobACL.save (#825: Allow passing explicit connection to ACL.{reload,save} #853)
• BlobACL.clear (#825: Allow passing explicit connection to ACL.{reload,save} #853)

Free API functions

• api.lookup_bucket
• api.list_buckets (handles fallback, passes connection to _BucketIterator)
• api.get_bucket
• api.create_bucket

batch.Batch methods

No real usecase for an explicit connection, given that Batch exists purely as a wrapper/proxy for an existing connection.
(note that Batch.__init__ takes a connection, handles fallback)

• Batch._do_request (uses self._connection)
• Batch.finish (delegates to _do_request; called in __exit__ when batch used as a context manager).

blob.Blob methods

• Blob.connection property (delegates to self.bucket.connection) (Remove 'Blob.connection' property. #873)
• Blob.generate_signed_url
• Blob.exists
• Blob.rename (delegates to self.bucket.copy_blob, #825: Allow passing explicit connection to 'Blob.{rename,delete}'. #854)
• Blob.delete (delegates to self.bucket.delete_blob, #825: Allow passing explicit connection to 'Blob.{rename,delete}'. #854)
• Blob.download_to_file
• Blob.download_to_filename
• Blob.download_as_string
• Blob.upload_from_file
• Blob.upload_from_filename
• Blob.upload_from_string
• Blob.make_public (#825: Allow passing explicit connection to 'Blob.make_public' #855)

bucket.Bucket methods

(note that Bucket.__init__ takes a connection, does not handle fallback)

• Bucket.connection property (Remove 'Bucket.connection' property #876)
• Bucket.exists (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.create (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.get_blob (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.delete (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.list_blobs (#825: Allow passing explicit connection to 'Bucket.{list_blobs,make public}' #856)
• Bucket.delete_blob (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.delete_blobs (delegates to delete_blob) (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.copy_blob (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.upload_file (should die?) (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.upload_file_object (should die?) (Removing most remaining uses of self.connection in Bucket #843)
• Bucket.make_public (#825: Allow passing explicit connection to 'Bucket.{list_blobs,make public}' #856)