Update advanced patterns documentation

Author: ppolewicz

doc/source/advanced.rst

@@ -2,10 +2,14 @@
 Advanced usage patterns
 #########################################
 
-B2 server API allows for creation of an object from existing objects. This allows to avoid transferring data from the source machine if the desired outcome can be (at least partially) constructed from what is already on the server.
+B2 server API allows for creation of an object from existing objects. This allows a client application to avoid transferring data from the source machine if the desired outcome can be (at least partially) constructed from what is already on the server.
 
 The way **b2sdk** exposes this functonality is through a few functions that allow the user to express the desired outcome and then the library takes care of planning and executing the work. Please refer to the table below to compare the support of object creation methods for various usage patterns.
 
+.. warning::
+  Those functions are not available in the current release of **b2sdk**. The documentation is provided as a preview of what is now being in the last stages of development, so stay tuned and follow progress of `Github issue #77 <https://github.com/Backblaze/b2-sdk-python/issues/77>`_.
+
+
 *****************
 Available methods
 *****************
@@ -41,7 +45,7 @@ Some methods support overlapping ranges between local and remote files. **b2sdk*
 Streaming interface
 ===================
 
-Some object creation methods start writing data before reading the whole input (iterator). This can be used to write objects that do not have fully known contents without writing them first locally, so that they could be copied. Such usage pattern can be relevant to small devices which stream data to B2 from an external NAS, where caching large files such as media files or virtual machine images is not an option.
+Some object creation methods start writing data before reading the whole input (iterator). This can be used to write objects that do not have fully known contents without writing them first locally, so that they could be uploaded. Such usage pattern is common on small devices which stream data to B2 from an external NAS, where temporary storage on the device is very limited.
 
 Please see :ref:`advanced method support table <advanced_methods_support_table>` to see where streaming interface is supported. 
 
@@ -75,7 +79,7 @@ Concatenate files of known size
     >>> bucket.concatenate(input_sources, remote_name, file_info)
     <b2sdk.file_version.FileVersionInfo at 0x7fc8cd560551>
 
-If one of remote source has length smaller than :term:`absoluteMinimumPartSize` then it cannot be copied into large file part. Such remote source would be downloaded and concatenated locally with local source or with other downloaded remote source.
+If one of remote source has length smaller than :term:`absoluteMinimumPartSize` then it cannot be (server-side) copied into large file part. Such remote source would be downloaded and concatenated with local source or with other downloaded remote source.
 
 Please note that this method only allows checksum verification for local upload sources. Checksum verification for remote sources is available only when local copy is available. In such case :meth:`b2sdk.v1.Bucket.create_file` can be used with overalapping ranges in input.
 
@@ -85,7 +89,7 @@ For more information about ``concatenate`` please see :meth:`b2sdk.v1.Bucket.con
 Concatenate files of known size (streamed version)
 ==================================================
 
-:meth:`b2sdk.v1.Bucket.concatenate` accepts an iterable of upload sources (either local or remote). The operation would not be planned ahead so it supports very large output objects, but continuation is only possible for local only sources and provided unfinished large file id. See more about continuation in :meth:`b2sdk.v1.Bucket.create_file` paragraph about continuation.
+:meth:`b2sdk.v1.Bucket.concatenate` accepts an iterable of upload sources (either local or remote). The operation is not be planned ahead, so it supports very large output objects, but continuation is only possible for local only sources or when ``large_file_id`` is provided as an argument. See more notes on continuation :ref:`here <continuation>`
 
 .. code-block:: python
 
@@ -104,28 +108,29 @@ Concatenate files of known size (streamed version)
 Concatenate files of unknown size
 =================================
 
-While it is supported by B2 server, this pattern is currently not supported by **b2sdk**.
+While it is supported by B2 server, this pattern is currently not supported by **b2sdk**. If you think there is a good reason why **b2sdk** should support it, please `open a github issue <https://github.com/Backblaze/b2-sdk-python/issues/new>`_ and describe your use case.
 
 
 *********************
 Synthethize an object
 *********************
 
-Using methods described below an object can be created from both local and remote sources while avoiding downloading small ranges when such range is already present on a local drive.
+Using methods described below an object can be created from both local and remote sources while avoiding downloading small ranges (caused by :term:`absoluteMinimumPartSize` limitation) when such range is already present on a local drive.
+
 
 Update a file efficiently
 ====================================
 
 :meth:`b2sdk.v1.Bucket.create_file` accepts an iterable which *can contain overlapping destination ranges*.
 
 .. note::
-  Following examples *create* new file - data in bucket is immutable, but **b2sdk** can create a new file version with the same name and updated content
+  Following examples *create* new files - data in bucket is immutable, but **b2sdk** can create a new file version with the same name and updated content
 
 
 Append to the end of a file
 ---------------------------
 
-The assumption here is that the file has been appended to since it was last uploaded to. This assumption is verified by **b2sdk** when possible by recalculating checksums of the overlapping remote and local ranges. If copied remote part sha does not match with locally available source, file creation process would be interrupted and an exception would be raised.
+The assumption here is that the local file has been appended to since it was last uploaded. This assumption is verified by **b2sdk** when possible by recalculating checksums of the overlapping remote and local ranges. If copied remote part checksum does not match the locally available source, file creation process is interrupted and an exception is raised.
 
 .. code-block:: python
 
@@ -148,7 +153,9 @@ The assumption here is that the file has been appended to since it was last uplo
     >>> bucket.create_file(input_sources, remote_name, file_info)
     <b2sdk.file_version.FileVersionInfo at 0x7fc8cd560552>
 
-`LocalUploadSource` has the size determined automatically in this case. This is more efficient than :meth:`b2sdk.v1.Bucket.concatenate`, as it can use the overlapping ranges when a remote part is smaller than :term:`absoluteMinimumPartSize` to prevent downloading a range (when concatenating, local source would have destination offset at the end of remote source)
+`LocalFileUploadSource` has the size determined automatically in this case.
+
+This is more efficient than :meth:`b2sdk.v1.Bucket.concatenate`. Here **b2sdk** can use the overlapping ranges when a remote part is smaller than :term:`absoluteMinimumPartSize` to avoid downloading a small range.
 
 For more information see :meth:`b2sdk.v1.Bucket.create_file`.
 
@@ -177,7 +184,9 @@ Change the middle of the remote file
     >>> bucket.create_file(input_sources, remote_name, file_info)
     <b2sdk.file_version.FileVersionInfo at 0x7fc8cd560552>
 
-`LocalUploadSource` has the size determined automatically in this case. This is more efficient than :meth:`b2sdk.v1.Bucket.concatenate`, as it can use the overlapping ranges when a remote part is smaller than :term:`absoluteMinimumPartSize` to prevent downloading a range.
+`LocalFileUploadSource` has the size determined automatically in this case.
+
+This is more efficient than :meth:`b2sdk.v1.Bucket.concatenate`. Here **b2sdk** can use the overlapping ranges when a remote part is smaller than :term:`absoluteMinimumPartSize` to avoid downloading a small range.
 
 For more information see :meth:`b2sdk.v1.Bucket.create_file`.
 
@@ -245,7 +254,7 @@ For more information see :meth:`b2sdk.v1.Bucket.create_file`.
 Prioritize remote or local sources
 ----------------------------------
 
-:meth:`b2sdk.v1.Bucket.create_file` and :meth:`b2sdk.v1.Bucket.create_file_stream` support source/origin prioritization, so that planner would know which sources should be used for overlapping ranges. Supported values are: `local`, `remote` and `local_verification`.
+:meth:`b2sdk.v1.Bucket.create_file` and :meth:`b2sdk.v1.Bucket.create_file_stream` support source prioritization, so that planner would know which sources should be used for overlapping ranges. Supported values are: `local`, `remote` and `local_verification`.
 
 .. code-block::
 
@@ -267,33 +276,36 @@ Prioritize remote or local sources
     |    |     |   |               |
     A    B     C   D               E
 
-    A=0, B=50M, C=80M, D=100M, E=200
+    A=0, B=50M, C=80M, D=100M, E=200MB
 
 .. code-block:: python
 
-    >>> bucket.create_file(input_sources, remote_name, file_info, prioritize='local')
-    # planner parts: cloud[A, B], local[B, C], remote[C, D], local[D, E]
+    >>> bucket.create_file(input_sources, remote_name, file_info, prioritize='remote')
+    # planner parts: remote[A, D], local[D, E]
 
-Here the planner has only used a remote source where remote range was not available, minimizing downloads.
+Here the planner has only used a local source where remote range was not available, minimizing uploads.
 
 .. code-block:: python
 
-    >>> planner.create_file(input_sources, remote_name, file_info, prioritize='remote')
-    # planner parts: cloud[A, D], local[D, E]
+    >>> bucket.create_file(input_sources, remote_name, file_info, prioritize='local')
+    # planner parts: remote[A, B], local[B, C], remote[C, D], local[D, E]
 
-Here the planner has only used a local source where remote range was not available, minimizing uploads.
+Here the planner has only used a remote source where local range was not available.
+
+.. TODO::
+   why do we even support this? Is there any legitimate reason to ever use it?
 
 .. code-block:: python
 
     >>> bucket.create_file(input_sources, remote_name, file_info)
     # or
     >>> bucket.create_file(input_sources, remote_name, file_info, prioritize='local_verification')
-    # planner parts: cloud[A, B], cloud[B, C], cloud[C, D], local[D, E]
+    # planner parts: remote[A, B], remote[B, C], remote[C, D], local[D, E]
 
 In `local_verification` mode the remote range was artificially split into three parts to allow for checksum verification against matching local ranges.
 
 .. note::
-  `prioritize` is just a planner setting - remote parts are always verified if matching local parts exists.
+  `prioritize` is just a planner setting - remote parts are always verified if matching local parts exist
 
 .. TODO::
   prioritization should accept enum, not string
@@ -308,18 +320,13 @@ Continuation
 Continuation of upload
 ======================
 
-In order to continue a simple upload session, **b2sdk** checks for any available sessions with of the same ``file name``, ``file_info`` and ``media type``, verifying the size of an object as much as possible.
+In order to continue a simple upload session, **b2sdk** checks for any available sessions with of the same ``file name``, ``file_info`` and ``media_type``, verifying the size of an object as much as possible.
 
 To support automatic continuation, some advanced methods create a plan before starting copy/upload operations, saving the hash of that plan in ``file_info`` for increased reliability.
 
-If that is not available, ``large_file_id`` can be extracted via callback during the operation start. It can then be passed into the subsequent call to continue the same task, though the responsibility for passing the exact same input is then on the user of the function. Please see :ref:`advanced method support table <advanced_methods_support_table>` to see where automatic continuation is supported. ``large_file_id`` can also be passed if automatic continuation is available in order to avoid issues where multiple matchin upload sessions are matching the transfer.
+If that is not available, ``large_file_id`` can be extracted via callback during the operation start. It can then be passed into the subsequent call to continue the same task, though the responsibility for passing the exact same input is then on the user of the function. Please see :ref:`advanced method support table <advanced_methods_support_table>` to see where automatic continuation is supported. ``large_file_id`` can also be passed if automatic continuation is available in order to avoid issues where multiple upload sessions are matching the transfer.
 
 
-Continuation of create/concantenate
-===================================
-
-:meth:`b2sdk.v1.Bucket.create_file` supports automatic continuation or manual continuation. :meth:`b2sdk.v1.Bucket.create_file_stream` supports only manual continuation for local-only inputs. The situation looks the same for :meth:`b2sdk.v1.Bucket.concatenate` and :meth:`b2sdk.v1.Bucket.concatenate_stream` (streamed version supports only manual continuation of local sources). Also :meth:`b2sdk.v1.Bucket.upload` and :meth:`b2sdk.v2.Bucket.copy` support both automatic and manual continuation.
-
 Manual continuation
 -------------------
 
@@ -347,7 +354,7 @@ Manual continuation (streamed version)
     >>> large_file_id = storage.query({'name': remote_name})[0]['large_file_id']
     >>> bucket.create_file_stream(input_sources, remote_name, file_info, large_file_id=large_file_id)
 
-Streams that contains remote sources cannot be continued with :meth:`b2sdk.v1.Bucket.create_file` - internally :meth:`b2sdk.v1.Bucket.create_file` stores plan information in file info for such inputs, and verifies it before any copy/upload and :meth:`b2sdk.v1.Bucket.create_file_stream` cannot store this information. Local source only inputs can be safely continued with :meth:`b2sdk.v1.Bucket.create_file` in auto continue mode or manual continue mode (because plan information is not stored in file info in such case).
+Streams that contain remote sources cannot be continued with :meth:`b2sdk.v1.Bucket.create_file` - internally :meth:`b2sdk.v1.Bucket.create_file` stores plan information in ``file_info`` for such inputs and verifies it before any copy/upload and :meth:`b2sdk.v1.Bucket.create_file_stream` cannot store this information. Local source only inputs can be safely continued with :meth:`b2sdk.v1.Bucket.create_file` in auto continue mode or manual continue mode (because plan information is not stored in ``file_info`` in such case).
 
 Auto continuation
 -----------------
@@ -356,17 +363,19 @@ Auto continuation
 
     >>> bucket.create_file(input_sources, remote_name, file_info)
 
-For local source only input, :meth:`b2sdk.v1.Bucket.create_file` would try to find matching unfinished large file. It will verify uploaded parts checksums with local sources - the most completed, having all uploaded parts matched candidate would be automatically selected as file to continue. If there is no matching candidate (even if there are unfinished files for the same file name) new large file would be started.
+For local source only input, :meth:`b2sdk.v1.Bucket.create_file` would try to find matching unfinished large file. It will verify uploaded parts checksums with local sources - the most completed, having all uploaded parts matched candidate would be automatically selected as a session to continue. If there is no matching candidate (even if there are unfinished files for the same file name) new large file would be started.
 
-In other cases plan information would be generated and :meth:`b2sdk.v1.Bucket.create_file` would try to find unfinished large file with matching plan info in its file info. If there is one or more such unfinished large files, :meth:`b2sdk.v1.Bucket.create_file` would verify checksums for all locally available parts and choose any matching candidate. If all candidates fails on uploaded parts checksums verification, process is interrupted and error raises. In such case corrupted unfinished large files should be cancelled manullay and :meth:`b2sdk.v1.Bucket.create_file` should be retried, or auto continuation should be turned off with `auto_continue=False`
+In other cases, plan information would be generated and :meth:`b2sdk.v1.Bucket.create_file` would try to find unfinished large file with matching plan info in its ``file_info``. If there is one or more such unfinished large files, :meth:`b2sdk.v1.Bucket.create_file` would verify checksums for all locally available parts and choose a matching candidate. If all candidates fail uploaded parts checksums verification, a new session is created. In such case corrupted unfinished large files could be cancelled manually to prevent the verification taking time until the corrupted session expire.
 
 
 No continuation
 ---------------
 
+Auto continuation can be turned off with ``auto_continue=False``, for example:
+
 .. code-block:: python
 
     >>> bucket.create_file(input_sources, remote_name, file_info, auto_continue=False)
 
+Please note that this only forces a start of a new large file session and does not delete old sessions, so it is still possible to continue the existing sessions with either auto or manual modes. See :meth:`b2sdk.v1.Bucket.list_unfinished_large_files` and :meth:`b2sdk.v1.Bucket.cancel_large_file` to learn how to find and remove unwanted sessions.
 
-Note, that this only forces start of a new large file - it is still possible to continue the process with either auto or manual modes.