Merge pull request #618 from Blosc/containers-tutorial

Containers tutorial

Author: FrancescAlted

doc/getting_started/tutorials.rst

@@ -17,4 +17,6 @@ Tutorials
    tutorials/09.ucodecs-ufilters
    tutorials/10.prefilters
    tutorials/11.vlarray
+   tutorials/12.batcharray
+   tutorials/13.containers
    tutorials/14.indexing-arrays

…ng_started/tutorials/12.batchstore.ipynb …ng_started/tutorials/12.batcharray.ipynbdoc/getting_started/tutorials/12.batchstore.ipynb renamed to doc/getting_started/tutorials/12.batcharray.ipynb doc/getting_started/tutorials/12.batchstore.ipynb renamed to doc/getting_started/tutorials/12.batcharray.ipynb

@@ -5,11 +5,11 @@
    "id": "2c822501cae3b91d",
    "metadata": {},
    "source": [
-    "# Working with BatchStore\n",
+    "# Working with BatchArray\n",
     "\n",
-    "A `BatchStore` is a batch-oriented container for variable-length Python items backed by a single `SChunk`. Each batch is stored in one compressed chunk, and each chunk may contain one or more internal variable-length blocks.\n",
+    "A `BatchArray` is a batch-oriented container for variable-length Python items backed by a single `SChunk`. Each batch is stored in one compressed chunk, and each chunk may contain one or more internal variable-length blocks.\n",
     "\n",
-    "This makes `BatchStore` a good fit when data arrives naturally in batches and you want efficient batch append/update operations together with occasional item-level access inside each batch."
+    "This makes `BatchArray` a good fit when data arrives naturally in batches and you want efficient batch append/update operations together with occasional item-level access inside each batch."
    ]
   },
   {
@@ -37,8 +37,8 @@
     "    print(f\"{label}: {value}\")\n",
     "\n",
     "\n",
-    "urlpath = \"batchstore_tutorial.b2b\"\n",
-    "copy_path = \"batchstore_tutorial_copy.b2b\"\n",
+    "urlpath = \"batcharray_tutorial.b2b\"\n",
+    "copy_path = \"batcharray_tutorial_copy.b2b\"\n",
     "blosc2.remove_urlpath(urlpath)\n",
     "blosc2.remove_urlpath(copy_path)"
    ]
@@ -48,9 +48,9 @@
    "id": "dda38c56e3e63ec1",
    "metadata": {},
    "source": [
-    "## Creating and populating a BatchStore\n",
+    "## Creating and populating a BatchArray\n",
     "\n",
-    "A `BatchStore` is indexed by batch. Batches can be appended one by one with `append()` or in bulk with `extend()`. Here we set a small `max_blocksize` just so the internal block structure is easy to observe in `.info`."
+    "A `BatchArray` is indexed by batch. Batches can be appended one by one with `append()` or in bulk with `extend()`. Here we set a small `items_per_block` just so the internal block structure is easy to observe in `.info`."
    ]
   },
   {
@@ -80,7 +80,7 @@
     }
    ],
    "source": [
-    "store = blosc2.BatchStore(urlpath=urlpath, mode=\"w\", contiguous=True, max_blocksize=2)\n",
+    "store = blosc2.BatchArray(urlpath=urlpath, mode=\"w\", contiguous=True, items_per_block=2)\n",
     "store.append(\n",
     "    [\n",
     "        {\"name\": \"alpha\", \"count\": 1},\n",
@@ -212,7 +212,7 @@
    "source": [
     "## Iteration and summary info\n",
     "\n",
-    "Iterating a `BatchStore` yields batches. The `.info` summary reports both batch-level and internal block-level statistics."
+    "Iterating a `BatchArray` yields batches. The `.info` summary reports both batch-level and internal block-level statistics."
    ]
   },
   {
@@ -237,7 +237,7 @@
      "output_type": "stream",
      "text": [
       "Batches via iteration: [[{'name': 'alpha*', 'count': 10}, {'name': 'beta*', 'count': 20}], [{'name': 'delta*', 'count': 40}, {'name': 'epsilon*', 'count': 50}], [{'name': 'between-a', 'count': 99}, {'name': 'between-b', 'count': 100}], [{'name': 'eta', 'count': 7}, {'name': 'theta', 'count': 8}], [{'name': 'iota', 'count': 9}, {'name': 'kappa', 'count': 10}, {'name': 'lambda', 'count': 11}]]\n",
-      "type       : BatchStore\n",
+      "type       : BatchArray\n",
       "serializer : msgpack\n",
       "nbatches   : 5 (items per batch: mean=2.20, max=3, min=2)\n",
       "nblocks    : 6 (items per block: mean=1.83, max=2, min=1)\n",
@@ -267,7 +267,7 @@
    "source": [
     "## Copying and changing storage settings\n",
     "\n",
-    "Like other Blosc2 containers, `BatchStore.copy()` can write a new persistent store while changing storage or compression settings."
+    "Like other Blosc2 containers, `BatchArray.copy()` can write a new persistent store while changing storage or compression settings."
    ]
   },
   {
@@ -316,7 +316,7 @@
    "source": [
     "## Round-tripping through cframes and reopening from disk\n",
     "\n",
-    "Tagged persistent stores automatically reopen as `BatchStore`, and a serialized cframe buffer does too."
+    "Tagged persistent stores automatically reopen as `BatchArray`, and a serialized cframe buffer does too."
    ]
   },
   {
@@ -340,9 +340,9 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "from_cframe type: BatchStore\n",
+      "from_cframe type: BatchArray\n",
       "from_cframe batches: [[{'name': 'alpha*', 'count': 10}, {'name': 'beta*', 'count': 20}], [{'name': 'delta*', 'count': 40}, {'name': 'epsilon*', 'count': 50}], [{'name': 'between-a', 'count': 99}, {'name': 'between-b', 'count': 100}], [{'name': 'eta', 'count': 7}, {'name': 'theta', 'count': 8}], [{'name': 'iota', 'count': 9}, {'name': 'kappa', 'count': 10}, {'name': 'lambda', 'count': 11}]]\n",
-      "Reopened type: BatchStore\n",
+      "Reopened type: BatchArray\n",
       "Reopened batches: [[{'name': 'alpha*', 'count': 10}, {'name': 'beta*', 'count': 20}], [{'name': 'delta*', 'count': 40}, {'name': 'epsilon*', 'count': 50}], [{'name': 'between-a', 'count': 99}, {'name': 'between-b', 'count': 100}], [{'name': 'eta', 'count': 7}, {'name': 'theta', 'count': 8}], [{'name': 'iota', 'count': 9}, {'name': 'kappa', 'count': 10}, {'name': 'lambda', 'count': 11}]]\n"
      ]
     }
@@ -412,7 +412,7 @@
    "source": [
     "## Flat item access with `.items`\n",
     "\n",
-    "The main `BatchStore` API remains batch-oriented, but the `.items` accessor offers a read-only flat view across all items. Integer indexing returns one item and slicing returns a Python list."
+    "The main `BatchArray` API remains batch-oriented, but the `.items` accessor offers a read-only flat view across all items. Integer indexing returns one item and slicing returns a Python list."
    ]
   },
   {