diff --git a/docarray/__init__.py b/docarray/__init__.py index 619cfce0d91..c195352d68d 100644 --- a/docarray/__init__.py +++ b/docarray/__init__.py @@ -5,6 +5,7 @@ from docarray.document import Document from docarray.array import DocumentArray from docarray.dataclasses import dataclass, field +from docarray.helper import login, logout if 'DA_RICH_HANDLER' in os.environ: from rich.traceback import install diff --git a/docarray/helper.py b/docarray/helper.py index a564532eb78..b5858724517 100644 --- a/docarray/helper.py +++ b/docarray/helper.py @@ -9,6 +9,8 @@ from typing import Any, Dict, Optional, Sequence, Tuple, Union, TYPE_CHECKING from collections import Counter +import hubble + if TYPE_CHECKING: # pragma: no cover from docarray import DocumentArray @@ -487,3 +489,16 @@ def _get_array_info(da: 'DocumentArray'): ) return is_homo, _nested_in, _nested_items, attr_counter, all_attrs_names + + +def login(interactive: Optional[bool] = None, force: bool = False, **kwargs): + """Login to Jina AI Cloud account. + :param interactive: If set to true, login will support notebook environments, otherwise the enviroment will be inferred. + :param force: If set to true, overwrite token and re-login. + """ + hubble.login(interactive=interactive, force=force) + + +def logout(): + """Log out of Hubble account.""" + hubble.logout() diff --git a/docs/fundamentals/cloud-support/data.md b/docs/fundamentals/cloud-support/data.md new file mode 100644 index 00000000000..c39bcb5fc3b --- /dev/null +++ b/docs/fundamentals/cloud-support/data.md @@ -0,0 +1,64 @@ +(data-management)= +## Data Management +Jina AI Cloud offers data management of DocumentArrays, using either the console or the DocArray Python API. + +### Web Console +In order to use the web console to manage your storage, you need to log in at [cloud.jina.ai](https://cloud.jina.ai). +Then, head to the [User Storage page](https://cloud.jina.ai/user/storage). + +Your DocumentArrays should appear in the data section inside the storage page: +```{figure} user-storage-page.png +:width: 90% +``` + +You can delete, download, view, or change the visibility of your DocumentArray objects using the web console. + + +### Python API +DocArray offers a Python API for data management. +Once you've successfully {ref}`logged in`, you can start using `DocumentArray` methods to manage data. + +#### Push (create/update): +You can push in-memory `DocumentArray` objects using the {meth}`~docarray.array.mixins.io.pushpull.PushPullMixin.push` method: +```python +from docarray import DocumentArray + +da = DocumentArray(...) +da.push('my_da', show_progress=True) +``` +This will create a DocumentArray object in the cloud or update it if it already exists. + +#### Pull (Read): +You can download a DocumentArray stored in the cloud using the {meth}`~docarray.array.mixins.io.pushpull.PushPullMixin.pull` method: +```python +from docarray import DocumentArray + +my_da = DocumentArray('my_da') +``` + +#### List +You can list all `DocumentArray` objects stored in the cloud using the {meth}`~docarray.array.mixins.io.pushpull.PushPullMixin.cloud_list` method: +```python +DocumentArray.cloud_list(show_table=True) +``` + +```text + You have 1 DocumentArray on the cloud + + Name Length Access Created at Updated at + ──────────────────────────────────────────────────────────────────────────────── + my_da 10 public 2022-09-15T07:14:54.256Z 2022-09-15T07:14:54.256Z + +['my_da'] +``` + +```{tip} +Use the `show_table` parameter to show summary information about DocumentArrays in the cloud. +``` + +#### Delete + +You can delete DocumentArray objects in the cloud using the method {meth}`~docarray.array.mixins.io.pushpull.PushPullMixin.cloud_delete`: +```python +DocumentArray.cloud_delete('my_da') +``` diff --git a/docs/fundamentals/cloud-support/index.md b/docs/fundamentals/cloud-support/index.md new file mode 100644 index 00000000000..2dc216f8bd0 --- /dev/null +++ b/docs/fundamentals/cloud-support/index.md @@ -0,0 +1,39 @@ +# {octicon}`rocket` Cloud Support + + + +:::::{grid} 2 +:gutter: 3 + + +::::{grid-item-card} {octicon}`person;1.5em` Log in to Jina AI Cloud using DocArray +:link: login +:link-type: doc + + +Log in to Jina AI Cloud to use and manage your cloud resources using DocArray. + +:::: + + +::::{grid-item-card} {octicon}`fold-up;1.5em` Manage Data on Jina AI Cloud +:link: data +:link-type: doc + +Push, pull, and manage DocumentArray objects on Jina AI Cloud. +:::: + + +::::: + + +Jina AI Cloud is the **portal** and **single entry point** to manage **all** your Jina AI resources. +Read more about [Jina AI Cloud](https://docs.jina.ai/jina-ai-cloud/). + + +```{toctree} +:hidden: + +login +data +``` \ No newline at end of file diff --git a/docs/fundamentals/cloud-support/login.md b/docs/fundamentals/cloud-support/login.md new file mode 100644 index 00000000000..1d287af02f6 --- /dev/null +++ b/docs/fundamentals/cloud-support/login.md @@ -0,0 +1,33 @@ +(login)= +# Authentication + +To manage your resources in Jina AI Cloud using DocArray, you need to authenticate to Jina AI Cloud. +Jina AI Cloud offers several ways to log in. Read more about [Login & Token Management in Jina AI Cloud](https://docs.jina.ai/jina-ai-cloud/login/). +DocArray also offers convenience methods to log in and log out using the Python API. + +## Login +To log in using the Python API, use the {meth}`~docarray.helper.login` method: +```python +from docarray import login + +login() +``` +The {meth}`~docarray.helper.login` method is interactive, meaning that it will prompt you to log in using a browser. Non-interactive login options are +explained in [Login & Token Management](https://docs.jina.ai/jina-ai-cloud/login/). + +{meth}`~docarray.helper.login` supports notebook environments as well, but it's recommended to use parameter `interactive` +in that case: +```python +from docarray import login + +login(interactive=True) +``` +## Logout +To log out, you can use the {meth}`~docarray.helper.logout` method: +```python +from docarray import logout + +logout() +``` + +For more logout methods (CLI), see [Login & Token Management](https://docs.jina.ai/jina-ai-cloud/login/). \ No newline at end of file diff --git a/docs/fundamentals/cloud-support/user-storage-page.png b/docs/fundamentals/cloud-support/user-storage-page.png new file mode 100644 index 00000000000..e5b04f3a9a1 Binary files /dev/null and b/docs/fundamentals/cloud-support/user-storage-page.png differ diff --git a/docs/fundamentals/documentarray/serialization.md b/docs/fundamentals/documentarray/serialization.md index 1e86d4af5e6..c6d2c568fc8 100644 --- a/docs/fundamentals/documentarray/serialization.md +++ b/docs/fundamentals/documentarray/serialization.md @@ -393,26 +393,8 @@ The maximum size of an upload is 4GB under the `protocol='protobuf'` and `compre To avoid unnecessary download when upstream DocumentArray is unchanged, you can add `DocumentArray.pull(..., local_cache=True)`. -Furthermore, it is possible to list all `DocumentArray` objects stored on the cloud using: -```python -DocumentArray.cloud_list(show_table=True) -``` - -```text - You have 1 DocumentArray on the cloud - - Name Length Access Created at Updated at - ──────────────────────────────────────────────────────────────────────────────── - da123 10 public 2022-09-15T07:14:54.256Z 2022-09-15T07:14:54.256Z - -['da123'] -``` - -```{tip} -Use parameter `show_table` to show table summarizing information about DocumentArrays in the cloud. -``` - -It is also possible to delete DocumentArray objects in the cloud using: -```python -DocumentArray.cloud_delete('da123') +```{seealso} +DocArray allows pushing, pulling, and managing your DocumentArrays in Jina AI Cloud. +Read more about how to manage your data in Jina AI Cloud, using either the console or the DocArray Python API, in the +{ref}`Data Management section `. ``` diff --git a/docs/index.md b/docs/index.md index a2ad063e62b..5f278236c15 100644 --- a/docs/index.md +++ b/docs/index.md @@ -41,6 +41,7 @@ fundamentals/document/index fundamentals/documentarray/index fundamentals/dataclass/index advanced/document-store/index +fundamentals/cloud-support/index ``` ```{toctree}