Update batch.md
diff --git a/docs/batch.md b/docs/batch.md index 15e2ea6..b8b3105 100644 --- a/docs/batch.md +++ b/docs/batch.md
@@ -1,76 +1,57 @@ # Batch -<section> - <p> - Each HTTP connection that your application makes results in a certain amount of overhead. - This library supports batching, - to allow your application to put several API calls into a single HTTP request. - Examples of situations when you might want to use batching: - </p> - <ul> - <li> - You have many small requests to make and would like to minimize HTTP request overhead. - </li> - <li> - A user made changes to data while your application was offline, - so your application needs to synchronize its local data with the server - by sending a lot of updates and deletes. - </li> - </ul> - <p class="note"> - <strong>Note</strong>: You're limited to 1000 calls in a single batch request. - If you need to make more calls than that, use multiple batch requests. - </p> - <p class="note"> - <strong>Note</strong>: You cannot use a - <a href="/api-client-library/python/guide/media_upload">media upload</a> - object in a batch request. - </p> -</section> +Each HTTP connection that your application makes results in a certain amount of overhead. +This library supports batching, +to allow your application to put several API calls into a single HTTP request. +Examples of situations when you might want to use batching: +* You have many small requests to make and would like to minimize HTTP request overhead. +* A user made changes to data while your application was offline, + so your application needs to synchronize its local data with the server + by sending a lot of updates and deletes. + +**Note**: You're limited to 1000 calls in a single batch request. +If you need to make more calls than that, use multiple batch requests. -<section> - <h2>Details</h2> - <p> - You create batch requests by calling <code>new_batch_http_request()</code> on your service - object, which returns a - <a href="https://google.github.io/google-api-python-client/docs/epy/googleapiclient.http.BatchHttpRequest-class.html">BatchHttpRequest</a> - object, and then calling <code>add()</code> for each request you want to execute. - You may pass in a callback with each request that is called with the response to that request. - The callback function arguments are: - a unique request identifier for each API call, - a response object which contains the API call response, - and an exception object which may be set to an exception raised by the API call. - After you've added the requests, you call <code>execute()</code> to make the requests. - The <code>execute()</code> function blocks until all callbacks have been called. - </p> - <p> - In the following code snippet, - two API requests are batched to a single HTTP request, - and each API request is supplied a callback: - </p> +**Note**: You cannot use a +[media upload](/api-client-library/python/guide/media_upload) +object in a batch request. + +## Details +You create batch requests by calling `new_batch_http_request()` on your service +object, which returns a +[BatchHttpRequest](https://google.github.io/google-api-python-client/docs/epy/googleapiclient.http.BatchHttpRequest-class.html) +object, and then calling `add()` for each request you want to execute. +You may pass in a callback with each request that is called with the response to that request. +The callback function arguments are: +a unique request identifier for each API call, +a response object which contains the API call response, +and an exception object which may be set to an exception raised by the API call. +After you've added the requests, you call `execute()` to make the requests. +The `execute()` function blocks until all callbacks have been called. + +In the following code snippet, +two API requests are batched to a single HTTP request, +and each API request is supplied a callback: <pre class="prettyprint"> See below</pre> - <p> - You can also supply a single callback that gets called for each response: - </p> +You can also supply a single callback that gets called for each response: + <pre class="prettyprint">See below</pre> - <p> - The - <a href="https://google.github.io/google-api-python-client/docs/epy/googleapiclient.http.BatchHttpRequest-class.html#add">add()</a> - method also allows you to supply a <code>request_id</code> parameter for each request. - These IDs are provided to the callbacks. - If you don't supply one, the library creates one for you. - The IDs must be unique for each API request, - otherwise <code>add()</code> raises an exception. - </p> - <p> - If you supply a callback to both <code>new_batch_http_request()</code> and <code>add()</code>, they both get called. - </p> -</section> + +The +[add()](https://google.github.io/google-api-python-client/docs/epy/googleapiclient.http.BatchHttpRequest-class.html#add) +method also allows you to supply a <code>request_id</code> parameter for each request. +These IDs are provided to the callbacks. +If you don't supply one, the library creates one for you. +The IDs must be unique for each API request, +otherwise `add()` raises an exception. + +If you supply a callback to both `new_batch_http_request()` and `add()`, they both get called. + --- -```py +```python def list_animals(request_id, response, exception): if exception is not None: # Do something with the exception @@ -92,7 +73,7 @@ batch.execute(http=http) ``` -```py +```python def insert_animal(request_id, response, exception): if exception is not None: @@ -110,3 +91,4 @@ batch.add(service.animals().insert(name="pig")) batch.add(service.animals().insert(name="llama")) batch.execute(http=http) +```