Skip to content

Commit 2803283

Browse files
sanketverma1704sanketverma1704
committed
Add docstrings for array module
1 parent 2761845 commit 2803283

File tree

1 file changed

+298
-0
lines changed

1 file changed

+298
-0
lines changed

‎src/zarr/core/array.py‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -314,6 +314,58 @@ async def _create_v3(
314314
attributes: dict[str, JSON] | None = None,
315315
exists_ok: bool = False,
316316
) -> AsyncArray:
317+
"""
318+
Asynchronously create a Zarr V3 array.
319+
320+
Parameters
321+
----------
322+
store_path : StorePath
323+
The path within the store where the array should be created.
324+
325+
shape : ShapeLike
326+
The shape of the array.
327+
328+
dtype : numpy.typing.DTypeLike
329+
The data type of the array elements.
330+
331+
chunk_shape : ChunkCoords
332+
The shape of the chunks in the array.
333+
334+
fill_value : Any, optional
335+
The default value to use for uninitialized regions of the array. Default is None.
336+
337+
chunk_key_encoding : ChunkKeyEncoding or tuple, optional
338+
The encoding to use for chunk keys. Can be either 'default' or 'v2' along with a separator,
339+
either "." or "/". Default is None.
340+
341+
codecs : Iterable of Codec or dict of str to JSON, optional
342+
The codecs to apply to each chunk. These can be codec objects or dictionaries specifying codec
343+
configurations. Default is None.
344+
345+
dimension_names : Iterable of str or None, optional
346+
The names of the array dimensions. Default is None.
347+
348+
attributes : dict of str to JSON, optional
349+
User-defined attributes to be associated with the array. Default is None.
350+
351+
exists_ok : bool, optional
352+
If False (default), raise an error if the array already exists. If True, overwrite the existing array.
353+
354+
Returns
355+
-------
356+
AsyncArray
357+
The created Zarr v3 array.
358+
359+
Raises
360+
------
361+
ValueError
362+
If the parameters are incompatible or invalid.
363+
364+
Notes
365+
-----
366+
- This method is asynchronous and should be awaited.
367+
- This function is specific to Zarr V3 format arrays.
368+
"""
317369
if not exists_ok:
318370
await ensure_no_existing_node(store_path, zarr_format=3)
319371

@@ -362,6 +414,61 @@ async def _create_v2(
362414
attributes: dict[str, JSON] | None = None,
363415
exists_ok: bool = False,
364416
) -> AsyncArray:
417+
"""
418+
Asynchronously create a Zarr V2 array.
419+
420+
Parameters
421+
----------
422+
store_path : StorePath
423+
The path within the store where the array should be created.
424+
425+
shape : ChunkCoords
426+
The shape of the array.
427+
428+
dtype : numpy.typing.DTypeLike
429+
The data type of the array elements.
430+
431+
chunks : ChunkCoords
432+
The shape of the chunks in the array.
433+
434+
dimension_separator : {'.', '/'} or None, optional
435+
The separator to use between chunk dimensions. Default is None.
436+
437+
fill_value : float or None, optional
438+
The default value to use for uninitialized regions of the array. Default is None.
439+
440+
order : {'C', 'F'} or None, optional
441+
The memory layout order for the array. 'C' is row-major (C-style), 'F' is column-major
442+
(Fortran-style). Default is None.
443+
444+
filters : list of dict of str to JSON or None, optional
445+
Filters to apply to each chunk. These can be dictionaries specifying filter configurations.
446+
Default is None.
447+
448+
compressor : dict of str to JSON or None, optional
449+
The compression algorithm to use for chunks. Default is None.
450+
451+
attributes : dict of str to JSON, optional
452+
User-defined attributes to be associated with the array. Default is None.
453+
454+
exists_ok : bool, optional
455+
If False (default), raise an error if the array already exists. If True, overwrite the existing array.
456+
457+
Returns
458+
-------
459+
AsyncArray
460+
The created Zarr V2 array.
461+
462+
Raises
463+
------
464+
ValueError
465+
If the parameters are incompatible or invalid.
466+
467+
Notes
468+
-----
469+
- This method is asynchronous and should be awaited.
470+
- This function is specific to Zarr v2 format arrays.
471+
"""
365472
if not exists_ok:
366473
await ensure_no_existing_node(store_path, zarr_format=2)
367474
if order is None:
@@ -391,6 +498,26 @@ def from_dict(
391498
store_path: StorePath,
392499
data: dict[str, JSON],
393500
) -> AsyncArray:
501+
"""
502+
Create a Zarr array from a dictionary.
503+
504+
Parameters
505+
----------
506+
store_path : StorePath
507+
The path within the store where the array should be created.
508+
509+
data : dict of str to JSON
510+
A dictionary representing the array data and metadata in JSON-serializable format.
511+
Returns
512+
-------
513+
AsyncArray
514+
The created Zarr array.
515+
516+
Raises
517+
------
518+
ValueError
519+
If the provided dictionary is not compatible with the Zarr array format.
520+
"""
394521
metadata = parse_array_metadata(data)
395522
return cls(metadata=metadata, store_path=store_path)
396523

@@ -575,6 +702,40 @@ async def _get_selection(
575702
out: NDBuffer | None = None,
576703
fields: Fields | None = None,
577704
) -> NDArrayLike:
705+
"""
706+
Asynchronously retrieve a selection from the array.
707+
708+
Parameters
709+
----------
710+
indexer : Indexer
711+
An object representing the indices to be used for selecting data from the array.
712+
713+
prototype : BufferPrototype
714+
A prototype buffer that defines the structure and properties of the output data.
715+
716+
out : NDBuffer or None, optional
717+
An optional output buffer to write the selected data into. If None, a new buffer
718+
will be created. Default is None.
719+
720+
fields : Fields or None, optional
721+
Specifies which fields to select if the array has structured data. If None, all fields
722+
are selected. Default is None.
723+
724+
Returns
725+
-------
726+
NDArrayLike
727+
The selected data from the array.
728+
729+
Raises
730+
------
731+
ValueError
732+
If the indices or selection criteria are invalid.
733+
734+
Notes
735+
-----
736+
- This method is asynchronous and should be awaited.
737+
- The selection can be made using advanced indexing and supports structured arrays.
738+
"""
578739
# check fields are sensible
579740
out_dtype = check_fields(fields, self.dtype)
580741

@@ -628,6 +789,28 @@ async def getitem(
628789
return await self._get_selection(indexer, prototype=prototype)
629790

630791
async def _save_metadata(self, metadata: ArrayMetadata, ensure_parents: bool = False) -> None:
792+
"""
793+
Asynchronously save the array metadata.
794+
795+
Parameters
796+
----------
797+
metadata : ArrayMetadata
798+
The metadata to be saved for the array. This typically includes information about the
799+
array's shape, dtype, chunking, etc.
800+
801+
ensure_parents : bool, optional
802+
If True, ensures that any necessary parent directories are created before saving the metadata.
803+
Default is False.
804+
805+
Returns
806+
-------
807+
None
808+
This method does not return any value.
809+
810+
Notes
811+
-----
812+
- This method is asynchronous and should be awaited.
813+
"""
631814
to_save = metadata.to_buffer_dict(default_buffer_prototype())
632815
awaitables = [set_or_delete(self.store_path / key, value) for key, value in to_save.items()]
633816

@@ -655,6 +838,37 @@ async def _set_selection(
655838
prototype: BufferPrototype,
656839
fields: Fields | None = None,
657840
) -> None:
841+
"""
842+
Asynchronously set a selection of values in the array.
843+
844+
Parameters
845+
----------
846+
indexer : Indexer
847+
An object representing the indices to be used for selecting locations in the array where data will be written.
848+
849+
value : numpy.typing.ArrayLike
850+
The values to be written into the array at the selected locations. Must be compatible with the array's dtype and shape.
851+
852+
prototype : BufferPrototype
853+
A prototype buffer that defines the structure and properties of the array chunks being modified.
854+
855+
fields : Fields or None, optional
856+
Specifies which fields to set if the array has structured data. If None, all fields are set. Default is None.
857+
858+
Returns
859+
-------
860+
None
861+
This method does not return any value.
862+
863+
Raises
864+
------
865+
ValueError
866+
If the indices or values are incompatible with the array's shape or dtype.
867+
868+
Notes
869+
-----
870+
- This method is asynchronous and should be awaited.
871+
"""
658872
# check fields are sensible
659873
check_fields(fields, self.dtype)
660874
fields = check_no_multi_fields(fields)
@@ -706,6 +920,39 @@ async def setitem(
706920
value: npt.ArrayLike,
707921
prototype: BufferPrototype | None = None,
708922
) -> None:
923+
"""
924+
Asynchronously set values in the array using basic indexing.
925+
926+
Parameters
927+
----------
928+
selection : BasicSelection
929+
The selection defining the region of the array to set.
930+
931+
value : numpy.typing.ArrayLike
932+
The values to be written into the selected region of the array.
933+
934+
prototype : BufferPrototype or None, optional
935+
A prototype buffer that defines the structure and properties of the array chunks being modified.
936+
If None, the default buffer prototype is used. Default is None.
937+
938+
Returns
939+
-------
940+
None
941+
This method does not return any value.
942+
943+
Raises
944+
------
945+
IndexError
946+
If the selection is out of bounds for the array.
947+
948+
ValueError
949+
If the values are not compatible with the array's dtype or shape.
950+
951+
Notes
952+
-----
953+
- This method is asynchronous and should be awaited.
954+
- Supports basic indexing, where the selection is contiguous and does not involve advanced indexing.
955+
"""
709956
if prototype is None:
710957
prototype = default_buffer_prototype()
711958
indexer = BasicIndexer(
@@ -718,6 +965,32 @@ async def setitem(
718965
async def resize(
719966
self, new_shape: ChunkCoords, delete_outside_chunks: bool = True
720967
) -> AsyncArray:
968+
"""
969+
Asynchronously resize the array to a new shape.
970+
971+
Parameters
972+
----------
973+
new_shape : ChunkCoords
974+
The desired new shape of the array.
975+
976+
delete_outside_chunks : bool, optional
977+
If True (default), chunks that fall outside the new shape will be deleted. If False,
978+
the data in those chunks will be preserved.
979+
980+
Returns
981+
-------
982+
AsyncArray
983+
The resized array.
984+
985+
Raises
986+
------
987+
ValueError
988+
If the new shape is incompatible with the current array's chunking configuration.
989+
990+
Notes
991+
-----
992+
- This method is asynchronous and should be awaited.
993+
"""
721994
assert len(new_shape) == len(self.metadata.shape)
722995
new_metadata = self.metadata.update_shape(new_shape)
723996

@@ -744,6 +1017,31 @@ async def _delete_key(key: str) -> None:
7441017
return replace(self, metadata=new_metadata)
7451018

7461019
async def update_attributes(self, new_attributes: dict[str, JSON]) -> AsyncArray:
1020+
"""
1021+
Asynchronously update the array's attributes.
1022+
1023+
Parameters
1024+
----------
1025+
new_attributes : dict of str to JSON
1026+
A dictionary of new attributes to update or add to the array. The keys represent attribute
1027+
names, and the values must be JSON-compatible.
1028+
1029+
Returns
1030+
-------
1031+
AsyncArray
1032+
The array with the updated attributes.
1033+
1034+
Raises
1035+
------
1036+
ValueError
1037+
If the attributes are invalid or incompatible with the array's metadata.
1038+
1039+
Notes
1040+
-----
1041+
- This method is asynchronous and should be awaited.
1042+
- The updated attributes will be merged with existing attributes, and any conflicts will be
1043+
overwritten by the new values.
1044+
"""
7471045
new_metadata = self.metadata.update_attributes(new_attributes)
7481046

7491047
# Write new metadata

0 commit comments

Comments
 (0)