Skip to content

Commit d8e4378

Browse files
committed
Update V3 migration links
1 parent 128a205 commit d8e4378

File tree

1 file changed

+30
-32
lines changed

1 file changed

+30
-32
lines changed

docs/user-guide/v3_migration.md

Lines changed: 30 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ so we can improve this guide.
2020

2121
The goals described above necessitated some breaking changes to the API (hence the
2222
major version update), but where possible we have maintained backwards compatibility
23-
in the most widely used parts of the API. This in the `zarr.Array` and
24-
`zarr.Group` classes and the "top-level API" (e.g. `zarr.open_array` and
25-
`zarr.open_group`).
23+
in the most widely used parts of the API. This in the [`zarr.Array`][] and
24+
[`zarr.Group`][] classes and the "top-level API" (e.g. [`zarr.open_array`][] and
25+
[`zarr.open_group`][]).
2626

2727
## Getting ready for 3.0
2828

@@ -92,22 +92,22 @@ The following sections provide details on breaking changes in Zarr-Python 3.
9292
### The Array class
9393

9494
1. Disallow direct construction - the signature for initializing the `Array` class has changed
95-
significantly. Please use `zarr.create_array` or `zarr.open_array` instead of
96-
directly constructing the `zarr.Array` class.
95+
significantly. Please use [`zarr.create_array`][] or [`zarr.open_array`][] instead of
96+
directly constructing the [`zarr.Array`][] class.
9797

9898
2. Defaulting to `zarr_format=3` - newly created arrays will use the version 3 of the
9999
Zarr specification. To continue using version 2, set `zarr_format=2` when creating arrays
100100
or set `default_zarr_version=2` in Zarr's runtime configuration.
101101

102102
### The Group class
103103

104-
1. Disallow direct construction - use `zarr.open_group` or `zarr.create_group`
104+
1. Disallow direct construction - use [`zarr.open_group`][] or [`zarr.create_group`][]
105105
instead of directly constructing the `zarr.Group` class.
106106
2. Most of the h5py compatibility methods are deprecated and will issue warnings if used.
107107
The following functions are drop in replacements that have the same signature and functionality:
108108

109-
- Use `zarr.Group.create_array` in place of `zarr.Group.create_dataset`
110-
- Use `zarr.Group.require_array` in place of `zarr.Group.require_dataset`
109+
- Use [`zarr.Group.create_array`][] in place of `zarr.Group.create_dataset`
110+
- Use [`zarr.Group.require_array`][] in place of `zarr.Group.require_dataset`
111111
3. Disallow "." syntax for getting group members. To get a member of a group named `foo`,
112112
use `group["foo"]` in place of `group.foo`.
113113

@@ -129,14 +129,13 @@ Several store implementations have moved from the top-level module to `zarr.stor
129129
Common replacements:
130130

131131
| v2 Import | v3 Import |
132-
|=========================|====================================|
133-
| `zarr.MemoryStore` | `zarr.storage.MemoryStore` |
134-
| `zarr.DirectoryStore` | `zarr.storage.LocalStore` |
135-
| `zarr.TempStore` | Use `tempfile.TemporaryDirectory` |
136-
| | with `LocalStore` |
132+
|-------------------------|------------------------------------|
133+
| `zarr.MemoryStore` | [`zarr.storage.MemoryStore`][] |
134+
| `zarr.DirectoryStore` | [`zarr.storage.LocalStore`][] |
135+
| `zarr.TempStore` | Use [`tempfile.TemporaryDirectory`][] with [`LocalStore`][zarr.storage.LocalStore] |
137136

138137
1. Replaced the `MutableMapping` base class in favor of a custom abstract base class
139-
(`zarr.abc.store.Store`).
138+
([`zarr.abc.store.Store`][]).
140139
2. Switched to an asynchronous interface for all store methods that result in IO. This
141140
change ensures that all store methods are non-blocking and are as performant as
142141
possible.
@@ -146,7 +145,7 @@ Zarr-Python 3. See issue #1274 for more details on the removal of these stores.
146145

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

152151
The following stores have been removed altogether. Users who need these stores will have to
@@ -160,7 +159,7 @@ implement their own version in zarr-python v3.
160159

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

166165
### Codecs
@@ -187,7 +186,7 @@ When installing using `pip`:
187186
### Miscellaneous
188187

189188
- The keyword argument `zarr_version` available in most creation functions in `zarr`
190-
(e.g. `zarr.create`, `zarr.open`, `zarr.group`, `zarr.array`) has
189+
(e.g. [`zarr.create`][], [`zarr.open`][], [`zarr.group`][], [`zarr.array`][]) has
191190
been deprecated in favor of `zarr_format`.
192191

193192
## 🚧 Work in Progress 🚧
@@ -200,31 +199,30 @@ of Zarr-Python, please open (or comment on) a
200199

201200
- The following functions / methods have not been ported to Zarr-Python 3 yet:
202201

203-
* `zarr.copy` (issue #2407)
204-
* `zarr.copy_all` (issue #2407)
205-
* `zarr.copy_store` (issue #2407)
206-
* `zarr.Group.move` (issue #2108)
202+
* `zarr.copy` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
203+
* `zarr.copy_all` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
204+
* `zarr.copy_store` ([issue #2407](https://github.com/zarr-developers/zarr-python/issues/2407))
205+
* `zarr.Group.move` ([issue #2108](https://github.com/zarr-developers/zarr-python/issues/2108))
207206

208207
- The following features (corresponding to function arguments to functions in
209208
`zarr`) have not been ported to Zarr-Python 3 yet. Using these features
210209
will raise a warning or a `NotImplementedError`:
211210

212211
* `cache_attrs`
213212
* `cache_metadata`
214-
* `chunk_store` (issue #2495)
213+
* `chunk_store` ([issue #2495](https://github.com/zarr-developers/zarr-python/issues/2495))
215214
* `meta_array`
216-
* `object_codec` (issue #2617)
217-
* `synchronizer` (issue #1596)
215+
* `object_codec` ([issue #2617](https://github.com/zarr-developers/zarr-python/issues/2617))
216+
* `synchronizer` ([issue #1596](https://github.com/zarr-developers/zarr-python/issues/1596))
218217
* `dimension_separator`
219218

220219
- The following features that were supported by Zarr-Python 2 have not been ported
221220
to Zarr-Python 3 yet:
222221

223-
* Structured arrays / dtypes (issue #2134)
224-
* Fixed-length string dtypes (issue #2347)
225-
* Datetime and timedelta dtypes (issue #2616)
226-
* Object dtypes (issue #2617)
227-
* Ragged arrays (issue #2618)
228-
* Groups and Arrays do not implement `__enter__` and `__exit__` protocols (issue #2619)
229-
* Big Endian dtypes (issue #2324)
230-
* Default filters for object dtypes for Zarr format 2 arrays (issue #2627)
222+
* Structured arrays / dtypes ([issue #2134](https://github.com/zarr-developers/zarr-python/issues/2134))
223+
* Fixed-length string dtypes ([issue #2347](https://github.com/zarr-developers/zarr-python/issues/2347))
224+
* Datetime and timedelta dtypes ([issue #2616](https://github.com/zarr-developers/zarr-python/issues/2616))
225+
* Object dtypes ([issue #2616](https://github.com/zarr-developers/zarr-python/issues/2616))
226+
* Ragged arrays ([issue #2618](https://github.com/zarr-developers/zarr-python/issues/2618))
227+
* Groups and Arrays do not implement `__enter__` and `__exit__` protocols ([issue #2619](https://github.com/zarr-developers/zarr-python/issues/2619))
228+
* Default filters for object dtypes for Zarr format 2 arrays ([issue #2627](https://github.com/zarr-developers/zarr-python/issues/2627))

0 commit comments

Comments
 (0)