Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 21 additions & 24 deletions docs/user-guide/v3_migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,51 +117,48 @@ The following sections provide details on breaking changes in Zarr-Python 3.

### The Store class

The Store API has changed significant in Zarr-Python 3. The most notable changes to the
Store API are:
The Store API has changed significant in Zarr-Python 3.

#### Store Import Paths
#### The base store class

Several store implementations have moved from the top-level module to `zarr.storage`:
The `MutableMapping` base class has been replaced in favor of a custom abstract base class ([`zarr.abc.store.Store`][]).
An asynchronous interface is used for all store methods that use I/O.
This change ensures that these store methods are non-blocking and are as performant as possible.

#### Store implementations

Store implementations have moved from the top-level module to `zarr.storage`:

```diff title="Store import changes from v2 to v3"
# Before (v2)
- from zarr import MemoryStore, DirectoryStore
+ from zarr.storage import MemoryStore, LocalStore # LocalStore replaces DirectoryStore
- from zarr import MemoryStore
+ from zarr.storage import MemoryStore
```

Common replacements:
The following stores have been renamed or changed:

| v2 Import | v3 Import |
|-------------------------|------------------------------------|
| `zarr.MemoryStore` | [`zarr.storage.MemoryStore`][] |
| `zarr.DirectoryStore` | [`zarr.storage.LocalStore`][] |
| `zarr.TempStore` | Use [`tempfile.TemporaryDirectory`][] with [`LocalStore`][zarr.storage.LocalStore] |
| v2 | v3 |
|------------------------|------------------------------------|
| `DirectoryStore` | [`zarr.storage.LocalStore`][] |
| `FSStore` | [`zarr.storage.FsspecStore`][] |
| `TempStore` | Use [`tempfile.TemporaryDirectory`][] with [`LocalStore`][zarr.storage.LocalStore] |
| `zarr.

1. Replaced the `MutableMapping` base class in favor of a custom abstract base class
([`zarr.abc.store.Store`][]).
2. Switched to an asynchronous interface for all store methods that result in IO. This
change ensures that all store methods are non-blocking and are as performant as
possible.

Beyond the changes store interface, a number of deprecated stores were also removed in
Zarr-Python 3. See issue #1274 for more details on the removal of these stores.
A number of deprecated stores were also removed.
See issue #1274 for more details on the removal of these stores.

- `N5Store` - see https://github.com/zarr-developers/n5py for an alternative interface to
N5 formatted data.
- `ABSStore` - use the [`zarr.storage.FsspecStore`][] instead along with fsspec's
[adlfs backend](https://github.com/fsspec/adlfs).

The following stores have been removed altogether. Users who need these stores will have to
implement their own version in zarr-python v3.

- `DBMStore`
- `LMDBStore`
- `SQLiteStore`
- `MongoDBStore`
- `RedisStore`

At present, the latter five stores in this list do not have an equivalent in Zarr-Python 3.
The latter five stores in this list do not have an equivalent in Zarr-Python 3.
If you are interested in developing a custom store that targets these backends, see
[developing custom stores](storage.md/#developing-custom-stores) or open an
[issue](https://github.com/zarr-developers/zarr-python/issues) to discuss your use case.
Expand Down