Merge branch 'main' into dask-distributed

* main:
  Sync with zarr python 3 beta 2 (#388)

docs/docs/icechunk-python/configuration.md

@@ -17,7 +17,7 @@ When using Icechunk with s3 compatible storage systems, credentials must be prov
 
     With this option, the credentials for connecting to S3 are detected automatically from your environment.
     This is usually the best choice if you are connecting from within an AWS environment (e.g. from EC2). [See the API](./reference.md#icechunk.StorageConfig.s3_from_env)
-    
+
     ```python
     icechunk.StorageConfig.s3_from_env(
         bucket="icechunk-test",
@@ -28,7 +28,7 @@ When using Icechunk with s3 compatible storage systems, credentials must be prov
 === "Provide credentials"
 
     With this option, you provide your credentials and other details explicitly. [See the API](./reference.md#icechunk.StorageConfig.s3_from_config)
-    
+
     ```python
     icechunk.StorageConfig.s3_from_config(
         bucket="icechunk-test",
@@ -49,7 +49,7 @@ When using Icechunk with s3 compatible storage systems, credentials must be prov
 
     With this option, you connect to S3 anonymously (without credentials).
     This is suitable for public data. [See the API](./reference.md#icechunk.StorageConfig.s3_anonymous)
-    
+
     ```python
     icechunk.StorageConfig.s3_anonymous(
         bucket="icechunk-test",
@@ -153,8 +153,8 @@ Now we can now create or open an Icechunk store using our config.
     )
 
     store = icechunk.IcechunkStore.create(
-        storage=storage, 
-        mode="w", 
+        storage=storage,
+        read_only=False,
     )
     ```
 
@@ -167,8 +167,8 @@ Now we can now create or open an Icechunk store using our config.
     )
 
     store = icechunk.IcechunkStore.create(
-        storage=storage, 
-        mode="w", 
+        storage=storage,
+        read_only=False,
     )
     ```
 
@@ -188,8 +188,8 @@ Now we can now create or open an Icechunk store using our config.
     )
 
     store = icechunk.IcechunkStore.open_existing(
-        storage=storage, 
-        mode="r+", 
+        storage=storage,
+        read_only=False,
         config=config,
     )
     ```
@@ -204,11 +204,34 @@ Now we can now create or open an Icechunk store using our config.
 
     store = icechunk.IcechunkStore.open_existing(
         storage=storage,
-        mode='r+',
+        read_only=False,
         config=config,
     )
     ```
 
-#### Access Mode
+#### Read Only Mode
+
+Note that in all of the above examples, a `read_only` is provided to instruct the access level of the user to the store. This instructs whether the store should be opened in read only mode. When the store is marked read only, no write operations can be called and will resolve in a `ValueError`.
+
+It is possible to make a read only store writeable and vice versa:
+
+```python
+# Store is opened writeable
+store = icechunk.IcechunkStore.open_existing(
+    storage=storage,
+    read_only=False,
+    config=config,
+)
+
+# Change in place to read_only
+store.set_read_only()
+
+# Open another instance of the store that is writeable
+writeable_store = store.as_writeable()
+
+# Open another read only instance of the store
+another_store = writeable_store.as_read_only()
 
-Note that in all of the above examples, a `mode` is provided to instruct the access level of the user to the store. This mode instructs whether the store should be opened in read only mode, and the store should start with a clean slate (although Icechunk prevents the possibility of accidentally overwriting any data that was previously comimtted to the store forever). For more about the access modes, see the [`zarr-python` docs](https://zarr.readthedocs.io/en/v3/_autoapi/zarr/abc/store/index.html#zarr.abc.store.AccessMode).
+# Set it writeable in place
+another_store.set_writeable()
+```

icechunk-python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "icechunk-python"
-version = "0.1.0-alpha.4"
+version = "0.1.0-alpha.5"
 description = "Transactional storage engine for Zarr designed for use on cloud object storage"
 readme = "../README.md"
 repository = "https://github.com/earth-mover/icechunk"

icechunk-python/notebooks/demo-s3.ipynb

@@ -48,11 +48,24 @@
    "execution_count": 3,
    "id": "39e76b2a-e294-41a4-a1e4-2a1845eb4f2b",
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "ename": "ValueError",
+     "evalue": "Error initializing repository: ref error: `storage error `S3ListObjectError(DispatchFailure(DispatchFailure { source: ConnectorError { kind: Other(None), source: ResolveEndpointError { message: \"A region must be set when sending requests to S3.\", source: None }, connection: Unknown } }))``",
+     "output_type": "error",
+     "traceback": [
+      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
+      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
+      "Cell \u001b[0;32mIn[3], line 1\u001b[0m\n\u001b[0;32m----> 1\u001b[0m store \u001b[38;5;241m=\u001b[39m \u001b[43mIcechunkStore\u001b[49m\u001b[38;5;241;43m.\u001b[39;49m\u001b[43mcreate\u001b[49m\u001b[43m(\u001b[49m\n\u001b[1;32m      2\u001b[0m \u001b[43m    \u001b[49m\u001b[43mstorage\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43ms3_storage\u001b[49m\u001b[43m,\u001b[49m\n\u001b[1;32m      3\u001b[0m \u001b[43m    \u001b[49m\u001b[43mread_only\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[38;5;28;43;01mFalse\u001b[39;49;00m\u001b[43m,\u001b[49m\n\u001b[1;32m      4\u001b[0m \u001b[43m)\u001b[49m\n",
+      "File \u001b[0;32m~/Developer/icechunk/icechunk-python/python/icechunk/__init__.py:144\u001b[0m, in \u001b[0;36mIcechunkStore.create\u001b[0;34m(cls, storage, read_only, config, *args, **kwargs)\u001b[0m\n\u001b[1;32m    139\u001b[0m \u001b[38;5;250m\u001b[39m\u001b[38;5;124;03m\"\"\"Create a new IcechunkStore with the given storage configuration.\u001b[39;00m\n\u001b[1;32m    140\u001b[0m \n\u001b[1;32m    141\u001b[0m \u001b[38;5;124;03mIf a store already exists at the given location, an error will be raised.\u001b[39;00m\n\u001b[1;32m    142\u001b[0m \u001b[38;5;124;03m\"\"\"\u001b[39;00m\n\u001b[1;32m    143\u001b[0m config \u001b[38;5;241m=\u001b[39m config \u001b[38;5;129;01mor\u001b[39;00m StoreConfig()\n\u001b[0;32m--> 144\u001b[0m store \u001b[38;5;241m=\u001b[39m \u001b[43mpyicechunk_store_create\u001b[49m\u001b[43m(\u001b[49m\u001b[43mstorage\u001b[49m\u001b[43m,\u001b[49m\u001b[43m \u001b[49m\u001b[43mconfig\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mconfig\u001b[49m\u001b[43m)\u001b[49m\n\u001b[1;32m    145\u001b[0m \u001b[38;5;28;01mreturn\u001b[39;00m \u001b[38;5;28mcls\u001b[39m(store\u001b[38;5;241m=\u001b[39mstore, read_only\u001b[38;5;241m=\u001b[39mread_only, args\u001b[38;5;241m=\u001b[39margs, kwargs\u001b[38;5;241m=\u001b[39mkwargs)\n",
+      "\u001b[0;31mValueError\u001b[0m: Error initializing repository: ref error: `storage error `S3ListObjectError(DispatchFailure(DispatchFailure { source: ConnectorError { kind: Other(None), source: ResolveEndpointError { message: \"A region must be set when sending requests to S3.\", source: None }, connection: Unknown } }))``"
+     ]
+    }
+   ],
    "source": [
     "store = IcechunkStore.create(\n",
     "    storage=s3_storage,\n",
-    "    mode=\"w\",\n",
+    "    read_only=False,\n",
     ")"
    ]
   },
@@ -1157,7 +1170,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "id": "d0bf89c2-dd6e-4024-9083-0cb7c355fda4",
    "metadata": {},
    "outputs": [
@@ -1175,7 +1188,7 @@
    "source": [
     "store = IcechunkStore.open_existing(\n",
     "    storage=s3_storage,\n",
-    "    mode=\"r\",\n",
+    "    read_only=True,\n",
     ")\n",
     "store"
    ]