diff --git a/caterva2/client.py b/caterva2/client.py index 60522849..e47bb3a9 100644 --- a/caterva2/client.py +++ b/caterva2/client.py @@ -656,6 +656,9 @@ def __repr__(self): @property def dtype(self): + """ + The data type of the dataset. + """ try: return self.meta["dtype"] except KeyError as e: @@ -663,6 +666,9 @@ def dtype(self): @property def shape(self): + """ + The shape of the dataset. + """ try: return tuple(self.meta["shape"]) except KeyError as e: @@ -670,6 +676,9 @@ def shape(self): @property def chunks(self): + """ + The chunkshape of the compressed dataset. + """ try: return tuple(self.meta["chunks"]) except KeyError as e: @@ -677,6 +686,9 @@ def chunks(self): @property def blocks(self): + """ + The blockshape of the compressed dataset. + """ try: return tuple(self.meta["blocks"]) except KeyError as e: @@ -1351,6 +1363,37 @@ def copy(self, src, dst): return pathlib.PurePosixPath(result) def concatenate(self, srcs, dst, axis): + """ + Concatenate the srcs along axis to a new location dst. + + Parameters + ---------- + srcs: list of Paths + Source files to be concatenated + dst : Path + The destination path for the file. + axis: int + Axis along which to concatenate. + + Returns + ------- + Path + The new path of the concatenated file. + + Examples + -------- + >>> import caterva2 as cat2 + >>> import numpy as np + >>> # For concatenating a file you need to be a registered user + >>> client = cat2.Client("https://cat2.cloud/demo", ("joedoe@example.com", "foobar")) + >>> root = client.get('@personal') + >>> root.upload('root-example/dir2/ds-4d.b2nd', "a.b2nd") + + >>> root.upload('root-example/dir2/ds-4d.b2nd', "b.b2nd") + + >>> client.concatenate(['@personal/a.b2nd', '@personal/b.b2nd'], '@personal/c.b2nd', axis=0) + PurePosixPath('@personal/c.b2nd') + """ urlbase, _ = _format_paths(self.urlbase) result = api_utils.post( f"{self.urlbase}/api/concat/", @@ -1361,6 +1404,37 @@ def concatenate(self, srcs, dst, axis): return pathlib.PurePosixPath(result) def stack(self, srcs, dst, axis): + """ + Stack the files in srcs along new axis to a new location dst. + + Parameters + ---------- + srcs: list of Paths + Source files accessible by client to be stacked + dst : Path + The destination path for the file. + axis: int + Axis along which to stack. + + Returns + ------- + Path + The new path of the stacked file. + + Examples + -------- + >>> import caterva2 as cat2 + >>> import numpy as np + >>> # For stacking a file you need to be a registered user + >>> client = cat2.Client("https://cat2.cloud/demo", ("joedoe@example.com", "foobar")) + >>> root = client.get('@personal') + >>> root.upload('root-example/dir2/ds-4d.b2nd', "a.b2nd") + + >>> root.upload('root-example/dir2/ds-4d.b2nd', "b.b2nd") + + >>> client.stack(['@personal/a.b2nd', '@personal/b.b2nd'], '@personal/c.b2nd', axis=0) + PurePosixPath('@personal/c.b2nd') + """ urlbase, _ = _format_paths(self.urlbase) result = api_utils.post( f"{self.urlbase}/api/stack/", diff --git a/doc/conf.py b/doc/conf.py index f49838f5..24a11512 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -6,10 +6,10 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'Caterva2' -copyright = '2024, ironArray SLU' -author = 'ironArray SLU' -release = '0.3.dev0' +project = "Caterva2" +copyright = "2024, ironArray SLU" +author = "ironArray SLU" +release = "0.3.dev0" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -26,19 +26,20 @@ "nbsphinx", ] +autosummary_generate = True # Enable auto generation of stub files + myst_enable_extensions = [ "html_image", ] -templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_static_path = ['_static'] +html_static_path = ["_static"] source_suffix = [".rst", ".md"] html_theme = "pydata_sphinx_theme" html_css_files = [ diff --git a/doc/reference/client_class.rst b/doc/reference/client_class.rst index 0d29e25d..398c45e6 100644 --- a/doc/reference/client_class.rst +++ b/doc/reference/client_class.rst @@ -8,67 +8,59 @@ A client is a remote repository that can be subscribed to. It is the main entry .. currentmodule:: caterva2 -Constructor ------------ - -.. autosummary:: - :toctree: autofiles - - Client.__init__ - - -Getting roots, files, datasets, subscribing... ----------------------------------------------- - -.. autosummary:: - :toctree: autofiles - - Client.get - Client.get_roots - Client.get_list - Client.subscribe - - -Fetch / download / upload datasets ----------------------------------- - -.. autosummary:: - :toctree: autofiles - - Client.fetch - Client.get_chunk - Client.download - Client.upload - - -User management ---------------- - -.. autosummary:: - :toctree: autofiles - - Client.adduser - Client.deluser - Client.listusers - - -Utility methods ---------------- - -.. autosummary:: - :toctree: autofiles - - Client.append - Client.copy - Client.move - Client.remove - Client.get_info - - -Evaluating expressions ----------------------- - -.. autosummary:: - :toctree: autofiles - - Client.lazyexpr +.. autoclass:: Client + :members: + :exclude-members: get, get_roots, get_list, subscribe, fetch, get_chunk, download, upload, adduser, deluser, listusers, lazyexpr + + :Special Methods: + .. autosummary:: + + __init__ + get + get_roots + get_list + subscribe + fetch + get_chunk + download + upload + adduser + deluser + listusers + lazyexpr + + + Constructor + ---------- + .. automethod:: __init__ + + + Getting roots, files, datasets, subscribing... + ---------------------------------------------- + .. automethod:: get + .. automethod:: get_roots + .. automethod:: get_list + .. automethod:: subscribe + + + Fetch / download / upload datasets + ---------------------------------- + .. automethod:: fetch + .. automethod:: get_chunk + .. automethod:: download + .. automethod:: upload + + + User management + --------------- + .. automethod:: adduser + .. automethod:: deluser + .. automethod:: listusers + + + Evaluating expressions + ---------------------- + .. automethod:: lazyexpr + + Utility methods + --------------- diff --git a/doc/reference/dataset_class.rst b/doc/reference/dataset_class.rst index 93d07cb7..e9d2fc26 100644 --- a/doc/reference/dataset_class.rst +++ b/doc/reference/dataset_class.rst @@ -5,31 +5,25 @@ Dataset class A dataset is a Blosc2-encoded file on a root repository (thus a :ref:`File `) representing either a flat string of bytes or an n-dimensional array. -.. currentmodule:: caterva2.client.Dataset +.. currentmodule:: caterva2 -Methods -------- +.. autoclass:: Dataset + :members: + :inherited-members: + :exclude-members: client, urlbase, cookie + :show-inheritance: + :member-order: groupwise -.. autosummary:: - :toctree: autofiles - :nosignatures: + :Special Methods: + .. autosummary:: + __init__ + __getitem__ - __init__ - __getitem__ - slice - append - get_download_url - download - vlmeta + Constructor + ----------- + .. automethod:: __init__ -Attributes ----------- - -.. autosummary:: - :toctree: autofiles - - shape - chunks - blocks - dtype + Utility Methods + ----------- + .. automethod:: __getitem__ diff --git a/doc/reference/file_class.rst b/doc/reference/file_class.rst index c4b85fec..ada6af0b 100644 --- a/doc/reference/file_class.rst +++ b/doc/reference/file_class.rst @@ -6,14 +6,21 @@ File class A file is either a Blosc2 dataset or a regular file on a root repository. .. currentmodule:: caterva2 -.. autosummary:: - :toctree: autofiles - File.__init__ - File.__getitem__ - File.get_download_url - File.download - File.remove - File.move - File.copy - File.vlmeta +.. autoclass:: File + :members: + :exclude-members: client, urlbase, cookie + :member-order: groupwise + + :Special Methods: + .. autosummary:: + __init__ + __getitem__ + + Constructor + ----------- + .. automethod:: __init__ + + Utility Methods + ----------- + .. automethod:: __getitem__ diff --git a/doc/reference/index.rst b/doc/reference/index.rst index aa53443d..c6a00452 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -1,8 +1,7 @@ API Reference ============= - .. toctree:: - :maxdepth: 2 + :maxdepth: 1 client_class root_class diff --git a/doc/reference/root_class.rst b/doc/reference/root_class.rst index 24e7a976..abfab8b7 100644 --- a/doc/reference/root_class.rst +++ b/doc/reference/root_class.rst @@ -6,13 +6,26 @@ Root class A root is a remote repository that can be subscribed to. .. currentmodule:: caterva2 -.. autosummary:: - :toctree: autofiles - Root.__init__ - Root.__getitem__ - Root.__contains__ - Root.__iter__ - Root.__len__ - Root.file_list - Root.upload +.. autoclass:: Root + :members: + :member-order: groupwise + + :Special Methods: + .. autosummary:: + __init__ + __getitem__ + __contains__ + __iter__ + __len__ + + Constructor + ----------- + .. automethod:: __init__ + + Utility Methods + ----------- + .. automethod:: __getitem__ + .. automethod:: __contains__ + .. automethod:: __iter__ + .. automethod:: __len__ diff --git a/doc/reference/utils.rst b/doc/reference/utils.rst index 960bc53f..c76a1b70 100644 --- a/doc/reference/utils.rst +++ b/doc/reference/utils.rst @@ -6,21 +6,9 @@ Utility classes and variables A collection of utility classes and variables that are used throughout the Caterva2 API. -.. currentmodule:: caterva2 - -Classes -------- - -.. autosummary:: - :toctree: autofiles - - BasicAuth - -Variables ---------- - -.. autosummary:: - :toctree: autofiles +.. automodule:: caterva2 + :members: + :undoc-members: + :exclude-members: Client, Root, Dataset, File - __version__ -.. sub_urlbase_default + .. autodata:: __version__ diff --git a/doc/tutorials/hdf5.md b/doc/tutorials/hdf5.md index fe3c8fb5..73c69645 100644 --- a/doc/tutorials/hdf5.md +++ b/doc/tutorials/hdf5.md @@ -9,7 +9,6 @@ HDF stands for Hierarchical Data Format. [HDF5](https://www.hdfgroup.org/solutio --- class: with-border -scale: 75% --- Schematic of hdf5 file structure @@ -46,11 +45,14 @@ bloscpath = client.unfold(apath) ``` By running the line ``print(f"After uploading and unfolding: {myroot.file_list}")``, one can check that the `.h5` indeed has been correctly exposed. Note that one may also use the `unfold` command in the prompt on the web client, applying it to the uploaded file: - -

- - -

+```{image} images/hdf5-unfold.webp +:alt: Unfold command +:width: 49.5% +``` +```{image} images/hdf5-unfold2.webp +:alt: Unfold result +:width: 49.5% +``` The unfolded file structure is clearly visible in the second image. We may now perform operations on the `.b2nd` proxy. @@ -69,7 +71,6 @@ plt.imshow(example_image / 65535, --- class: with-border -scale: 75% --- First visualisation @@ -92,7 +93,6 @@ The result is an image with the desired diffraction pattern visible, as shown be --- class: with-border -scale: 75% --- Second visualisation @@ -103,7 +103,6 @@ We can also go to the web client and directly visualize the lazy expression we h --- class: with-border -scale: 75% --- Second visualisation diff --git a/doc/tutorials/images/web-command.webp b/doc/tutorials/images/web-command.webp new file mode 100644 index 00000000..3361200f Binary files /dev/null and b/doc/tutorials/images/web-command.webp differ diff --git a/doc/tutorials/web-client.md b/doc/tutorials/web-client.md index 7e516a7e..aff01bdd 100644 --- a/doc/tutorials/web-client.md +++ b/doc/tutorials/web-client.md @@ -43,7 +43,6 @@ Up until now we've just seen the read-only operations that may be performed on t --- class: with-border -scale: 75% --- The login screen @@ -55,7 +54,6 @@ The main Web client screen has some changes now: besides the indication of the l --- class: with-border -scale: 75% --- The main screen showing new user features