From f0f29c07a71a22c73442d576d48395e58d0100c8 Mon Sep 17 00:00:00 2001 From: larkee Date: Thu, 4 Jun 2020 15:17:29 +1000 Subject: [PATCH 1/3] docs: update batch-usage reflect the correct usage --- docs/batch-usage.rst | 91 +++++++++++++++++++------------------------- 1 file changed, 39 insertions(+), 52 deletions(-) diff --git a/docs/batch-usage.rst b/docs/batch-usage.rst index 419ca106e6..3eab02648d 100644 --- a/docs/batch-usage.rst +++ b/docs/batch-usage.rst @@ -10,27 +10,52 @@ modification operations to be performed on tables in a database. Use of a no changes are propagated to the back-end. -Starting a Batch ----------------- +Use Batch via BatchCheckout +-------------------------------- -Construct a :class:`~google.cloud.spanner.batch.Batch` object from a :class:`~google.cloud.spanner.database.Database` object: +:meth:`Database.batch` creates a :class:`BatchCheckout` instance to use as a context manager to handle creating and +committing a :class:`Batch`. The :class:`BatchCheckout` will automatically call :meth:`~google.cloud.spanner.batch.Batch.commit` +if the ``with`` block exits without raising an exception. .. code:: python - from google.cloud import spanner + from google.cloud.spanner import KeySet client = spanner.Client() instance = client.instance(INSTANCE_NAME) database = instance.database(DATABASE_NAME) - batch = database.batch() + to_delete = KeySet(keys=[ + ('bharney@example.com',) + ('nonesuch@example.com',) + ]) + + with database.batch() as batch: + + batch.insert( + 'citizens', columns=['email', 'first_name', 'last_name', 'age'], + values=[ + ['phred@exammple.com', 'Phred', 'Phlyntstone', 32], + ['bharney@example.com', 'Bharney', 'Rhubble', 31], + ]) + + batch.update( + 'citizens', columns=['email', 'age'], + values=[ + ['phred@exammple.com', 33], + ['bharney@example.com', 32], + ]) + + ... + + batch.delete('citizens', to_delete) Inserting records using a Batch ------------------------------- -:meth:`Batch.insert` adds one or more new records to a table. Fails if -any of the records already exists. +:meth:`Batch.insert` adds one or more new records to a table. This fails if +any of the records already exist. .. code:: python @@ -53,8 +78,8 @@ any of the records already exists. Update records using a Batch ------------------------------- -:meth:`Batch.update` updates one or more existing records in a table. Fails -if any of the records does not already exist. +:meth:`Batch.update` updates one or more existing records in a table. This fails +if any of the records do not already exist. .. code:: python @@ -127,8 +152,8 @@ column values are set to null. Delete records using a Batch ---------------------------- -:meth:`Batch.delete` removes one or more records from a table. Non-existent -rows do not cause errors. +:meth:`Batch.delete` removes one or more records from a table. Attempting to delete +rows that do not exist will not cause errors. .. code:: python @@ -151,50 +176,12 @@ After describing the modifications to be made to table data via the the back-end by calling :meth:`Batch.commit`, which makes the ``Commit`` API call. -.. code:: python - - batch.commit() - - -Use a Batch as a Context Manager --------------------------------- - -Rather than calling :meth:`Batch.commit` manually, you can use the -:class:`Batch` instance as a context manager, and have it called automatically -if the ``with`` block exits without raising an exception. +Yu do not need to call this yourself as :class:`BatchCheckout` will call +this method automatically upon exiting the ``with`` block. .. code:: python - from google.cloud.spanner import KeySet - - client = spanner.Client() - instance = client.instance(INSTANCE_NAME) - database = instance.database(DATABASE_NAME) - - to_delete = KeySet(keys=[ - ('bharney@example.com',) - ('nonesuch@example.com',) - ]) - - with database.batch() as batch: - - batch.insert( - 'citizens', columns=['email', 'first_name', 'last_name', 'age'], - values=[ - ['phred@exammple.com', 'Phred', 'Phlyntstone', 32], - ['bharney@example.com', 'Bharney', 'Rhubble', 31], - ]) - - batch.update( - 'citizens', columns=['email', 'age'], - values=[ - ['phred@exammple.com', 33], - ['bharney@example.com', 32], - ]) - - ... - - batch.delete('citizens', to_delete) + batch.commit() Next Step From c29bef553e0c2a9999d641e2db19c3335b050fb6 Mon Sep 17 00:00:00 2001 From: larkee Date: Thu, 4 Jun 2020 16:25:08 +1000 Subject: [PATCH 2/3] fix typo --- docs/batch-usage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/batch-usage.rst b/docs/batch-usage.rst index 3eab02648d..95afb016a4 100644 --- a/docs/batch-usage.rst +++ b/docs/batch-usage.rst @@ -176,7 +176,7 @@ After describing the modifications to be made to table data via the the back-end by calling :meth:`Batch.commit`, which makes the ``Commit`` API call. -Yu do not need to call this yourself as :class:`BatchCheckout` will call +You do not need to call this yourself as :class:`BatchCheckout` will call this method automatically upon exiting the ``with`` block. .. code:: python From 3778094a7d2b684ad0a91a42b1348d5cbcd2b48b Mon Sep 17 00:00:00 2001 From: larkee Date: Thu, 4 Jun 2020 20:16:51 +1000 Subject: [PATCH 3/3] fix doc links --- docs/batch-usage.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/batch-usage.rst b/docs/batch-usage.rst index 95afb016a4..0da1086779 100644 --- a/docs/batch-usage.rst +++ b/docs/batch-usage.rst @@ -1,21 +1,24 @@ Batching Modifications ###################### -A :class:`~google.cloud.spanner.batch.Batch` represents a set of data +A :class:`~google.cloud.spanner_v1.batch.Batch` represents a set of data modification operations to be performed on tables in a database. Use of a ``Batch`` does not require creating an explicit -:class:`~google.cloud.spanner.snapshot.Snapshot` or -:class:`~google.cloud.spanner.transaction.Transaction`. Until -:meth:`~google.cloud.spanner.batch.Batch.commit` is called on a ``Batch``, +:class:`~google.cloud.spanner_v1.snapshot.Snapshot` or +:class:`~google.cloud.spanner_v1.transaction.Transaction`. Until +:meth:`~google.cloud.spanner_v1.batch.Batch.commit` is called on a ``Batch``, no changes are propagated to the back-end. Use Batch via BatchCheckout -------------------------------- -:meth:`Database.batch` creates a :class:`BatchCheckout` instance to use as a context manager to handle creating and -committing a :class:`Batch`. The :class:`BatchCheckout` will automatically call :meth:`~google.cloud.spanner.batch.Batch.commit` -if the ``with`` block exits without raising an exception. +:meth:`Database.batch` creates a :class:`~google.cloud.spanner_v1.database.BatchCheckout` +instance to use as a context manager to handle creating and committing a +:class:`~google.cloud.spanner_v1.batch.Batch`. The +:class:`BatchCheckout` will automatically call +:meth:`~google.cloud.spanner_v1.batch.Batch.commit` if the ``with`` block exits +without raising an exception. .. code:: python @@ -176,7 +179,8 @@ After describing the modifications to be made to table data via the the back-end by calling :meth:`Batch.commit`, which makes the ``Commit`` API call. -You do not need to call this yourself as :class:`BatchCheckout` will call +You do not need to call this yourself as +:class:`~google.cloud.spanner_v1.database.BatchCheckout` will call this method automatically upon exiting the ``with`` block. .. code:: python