datalab-api 0.2.0__py3-none-any.whl

datalab_api/__init__.py

@@ -0,0 +1,371 @@
+from pathlib import Path
+from typing import Any, Optional, Union
+
+from ._base import BaseDatalabClient, __version__
+
+__all__ = ("__version__", "DatalabClient")
+
+
+class DatalabClient(BaseDatalabClient):
+    """A client for the Datalab API.
+
+    The client will keep an HTTP session open for the duration of its life and thus is
+    amenable for use as a context manager, e.g.,
+
+    ```python
+    with DatalabClient("https://public.api.odbx.science") as client:
+        client.get_items()
+    ```
+
+    """
+
+    def get_info(self) -> dict[str, Any]:
+        """Fetch metadata associated with this datalab instance.
+
+        Returns:
+            dict: The JSON response from the `/info` endpoint of the Datalab API.
+
+        """
+        info_url = f"{self.datalab_api_url}/info"
+        info_resp = self.session.get(info_url, follow_redirects=True)
+        return info_resp.json()
+
+    def authenticate(self):
+        """Tests authentication of the client with the Datalab API."""
+        user_url = f"{self.datalab_api_url}/get-current-user"
+        user_resp = self.session.get(user_url, follow_redirects=True)
+        if user_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to authenticate to {self.datalab_api_url!r}: {user_resp.status_code=} from {self._headers}. Please check your API key."
+            )
+        return user_resp.json()
+
+    def get_items(self, item_type: Optional[str] = "samples") -> list[dict[str, Any]]:
+        """List items of the given type available to the authenticated user.
+
+        Parameters:
+            item_type: The type of item to list. Defaults to "samples". Other
+            choices will trigger a call to the `/<item_type>` endpoint of the API.
+
+        Returns:
+            A list of items of the given type.
+
+        """
+        if item_type is None:
+            item_type = "samples"
+        items_url = f"{self.datalab_api_url}/{item_type}"
+        items_resp = self.session.get(items_url, follow_redirects=True)
+        if items_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to list items with {item_type=} at {items_url}: {items_resp.status_code=}. Check the item type is correct."
+            )
+        items = items_resp.json()
+        if items["status"] != "success":
+            raise RuntimeError(f"Failed to list items at {items_url}: {items['status']!r}.")
+        return items[item_type]
+
+    def search_items(
+        self, query: str, item_types: Union[list[str], str] = ["samples", "cells"]
+    ) -> list[dict[str, Any]]:
+        """Search for items of the given types that match the query.
+
+        Parameters:
+            query: Free-text query to search for.
+            item_types: The types of items to search for. Defaults to ["samples", "cells"].
+
+        Returns:
+            An ordered list of items of the given types that match the query.
+
+        """
+        if isinstance(item_types, str):
+            item_types = [item_types]
+
+        search_items_url = (
+            f"{self.datalab_api_url}/search-items?query={query}&types={','.join(item_types)}"
+        )
+        items_resp = self.session.get(search_items_url, follow_redirects=True)
+        if items_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to search items with {item_types=} at {search_items_url}: {items_resp.status_code=}"
+            )
+        items = items_resp.json()
+        if items["status"] != "success":
+            raise RuntimeError(f"Failed to list items at {search_items_url}: {items['status']!r}.")
+
+        return items["items"]
+
+    def create_item(
+        self, item_id: str, item_type: str, item_data: Optional[dict[str, Any]] = None
+    ) -> dict[str, Any]:
+        """Create an item with a given ID and item data.
+
+        Parameters:
+            item_id: The ID of the item to create.
+            item_type: The type of item to create, e.g., 'samples', 'cells'.
+            item_data: The data for the item.
+
+        """
+        new_item = {}
+        if item_data is not None:
+            new_item = item_data
+        new_item.update(**{"item_id": item_id, "type": item_type})
+
+        create_item_url = f"{self.datalab_api_url}/new-sample/"
+        create_item_resp = self.session.post(
+            create_item_url,
+            json=new_item,
+            follow_redirects=True,
+        )
+        try:
+            created_item = create_item_resp.json()
+            if created_item["status"] != "success":
+                raise RuntimeError(
+                    f"Failed to create item at {create_item_url}: {created_item['status']!r}."
+                )
+            return created_item["sample_list_entry"]
+
+        except Exception:
+            raise RuntimeError(
+                f"Failed to create item {item_id=} with data {item_data=} at {create_item_url}: {create_item_resp.status_code=}. Check the item information is correct."
+            )
+
+    def update_item(self, item_id: str, item_data: dict[str, Any]) -> dict[str, Any]:
+        """Update an item with the given item data.
+
+        Parameters:
+            item_id: The ID of the item to update.
+            item_data: The new data for the item.
+
+        Returns:
+            A dictionary of the updated item data.
+
+        """
+        update_item_data = {"item_id": item_id, "data": item_data}
+        update_item_url = f"{self.datalab_api_url}/save-item/"
+        update_item_resp = self.session.post(
+            update_item_url,
+            json=update_item_data,
+            follow_redirects=True,
+        )
+        if update_item_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to update item {item_id=} at {update_item_url}: {update_item_resp.status_code=}. Check the item information is correct."
+            )
+        updated_item = update_item_resp.json()
+        if updated_item["status"] != "success":
+            raise RuntimeError(
+                f"Failed to update item at {update_item_url}: {updated_item['status']!r}."
+            )
+        return updated_item
+
+    def get_item(
+        self,
+        item_id: Optional[str] = None,
+        refcode: Optional[str] = None,
+        load_blocks: bool = False,
+    ) -> dict[str, Any]:
+        """Get an item with a given ID or refcode.
+
+        Parameters:
+            item_id: The ID of the item to search for.
+            refcode: The refcode of the item to search fork
+            load_blocks: Whether to load the blocks associated with the item.
+
+        Returns:
+            A dictionary of item data for the item with the given ID or refcode.
+
+        """
+
+        if item_id is None and refcode is None:
+            raise ValueError("Must provide one of `item_id` or `refcode`.")
+        if item_id is not None and refcode is not None:
+            raise ValueError("Must provide only one of `item_id` or `refcode`.")
+
+        if refcode is not None:
+            raise NotImplementedError("Searching by `refcode` is not yet implemented.")
+
+        item_url = f"{self.datalab_api_url}/get-item-data/{item_id}"
+        item_resp = self.session.get(item_url, follow_redirects=True)
+
+        if item_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to find item {item_id=}, {refcode=} {item_url}: {item_resp.status_code=}. Check the item information is correct."
+            )
+
+        item = item_resp.json()
+        if item["status"] != "success":
+            raise RuntimeError(f"Failed to get item at {item_url}: {item['status']!r}.")
+
+        # Filter out any deleted blocks
+        item["item_data"]["blocks_obj"] = {
+            block_id: block
+            for block_id, block in item["item_data"]["blocks_obj"].items()
+            if block_id in item["item_data"]["display_order"]
+        }
+
+        # Make a call to `/update-block` which will parse/create plots and return as JSON
+        if load_blocks:
+            ret_item_id = item["item_data"]["item_id"]
+            for block_id, block in item["item_data"]["blocks_obj"].items():
+                block_data = self.get_block(
+                    item_id=ret_item_id, block_id=block_id, block_data=block
+                )
+                item["item_data"]["blocks_obj"][block_id] = block_data
+
+        return item["item_data"]
+
+    def get_block(self, item_id: str, block_id: str, block_data: dict[str, Any]) -> dict[str, Any]:
+        """Get a block with a given ID and block data.
+        Should be used in conjunction with `get_item` to load an existing block.
+
+        Parameters:
+            item_id: The ID of the item to search for.
+            block_id: The ID of the block to search for.
+            block_data: Any other block data required by the request.
+
+        Returns:
+            A dictionary of block data for the block with the given ID.
+
+        """
+        block_url = f"{self.datalab_api_url}/update-block/"
+        block_request = {
+            "block_data": block_data,
+            "item_id": item_id,
+            "block_id": block_id,
+            "save_to_db": False,
+        }
+        block_resp = self.session.post(block_url, json=block_request, follow_redirects=True)
+        if block_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to find block {block_id=} for item {item_id=} at {block_url}: {block_resp.status_code=}. Check the block information is correct."
+            )
+
+        block = block_resp.json()
+        if block["status"] != "success":
+            raise RuntimeError(f"Failed to get block at {block_url}: {block['status']!r}.")
+        return block["new_block_data"]
+
+    def upload_file(self, item_id: str, file_path: Union[Path, str]) -> dict[str, Any]:
+        """Upload a file to an item with a given ID.
+
+        Parameters:
+            item_id: The ID of the item to upload the file to.
+            file_path: The path to the file to upload.
+
+        Returns:
+            A dictionary of the uploaded file data.
+
+        """
+        if isinstance(file_path, str):
+            file_path = Path(file_path)
+        if not file_path.exists():
+            raise FileNotFoundError(f"File {file_path=} does not exist.")
+
+        upload_url = f"{self.datalab_api_url}/upload-file/"
+        with open(file_path, "rb") as file:
+            files = {"file": (file_path.name, file)}
+            upload_resp = self.session.post(
+                upload_url,
+                files=files,
+                data={"item_id": item_id, "replace_file": None},
+                follow_redirects=True,
+            )
+        if upload_resp.status_code != 201:
+            raise RuntimeError(
+                f"Failed to upload file {file_path=} to item {item_id=} at {upload_url}: {upload_resp.status_code=}. Check the file information is correct."
+            )
+
+        upload = upload_resp.json()
+        if upload["status"] != "success":
+            raise RuntimeError(f"Failed to upload file at {upload_url}: {upload['status']!r}.")
+
+        return upload
+
+    def create_data_block(
+        self,
+        item_id: str,
+        block_type: str,
+        file_ids: Optional[Union[str, list[str]]] = None,
+        file_paths: Optional[Union[Path, list[Path]]] = None,
+    ) -> dict[str, Any]:
+        """Creates a data block for an item with the given block type and file ID.
+
+        Parameters:
+            item_id: The ID of the item to create the block for.
+            block_type: The type of block to create.
+            file_ids: The ID of the file to attach to the block, must already
+                be uploaded to the item.
+            file_paths: A path, or set of paths, to files to upload and attach to the
+                item. Conflicts with `file_id`, only one can be provided.
+
+        Returns:
+            The created block data.
+
+        """
+
+        blocks_url = f"{self.datalab_api_url}/add-data-block/"
+
+        # TODO: future validation of block types based on server response
+        payload = {
+            "item_id": item_id,
+            "block_type": block_type,
+            "index": None,
+        }
+
+        if file_paths:
+            raise NotImplementedError(
+                "Simultaneously uploading files and creating blocks is not yet supported."
+            )
+
+        if file_ids:
+            if isinstance(file_ids, str):
+                file_ids = [file_ids]
+            # check that the file is attached to the item
+            item = self.get_item(item_id=item_id, load_blocks=False)
+            attached_file_ids = set(item["file_ObjectIds"])
+            if not set(file_ids).issubset(attached_file_ids):
+                raise RuntimeError(
+                    f"Not all IDs {file_ids=} are attached to item {item_id=}: {attached_file_ids=}"
+                )
+
+        block_resp = self.session.post(blocks_url, json=payload, follow_redirects=True)
+        if block_resp.status_code != 200:
+            raise RuntimeError(
+                f"Failed to create block {block_type=} for item {item_id=}:\n{block_resp.text}"
+            )
+        block_data = block_resp.json()["new_block_obj"]
+
+        if file_ids:
+            block_data = self._update_data_block(
+                block_type=block_type, block_data=block_data, file_ids=file_ids
+            )
+
+        return block_data
+
+    def _update_data_block(
+        self, block_type: str, block_data: dict, file_ids: Optional[Union[str, list[str]]] = None
+    ) -> dict[str, Any]:
+        """Attaches files to blocks: should only be used via wrapper methods."""
+        if file_ids and isinstance(file_ids, str):
+            file_ids = [file_ids]
+
+        if file_ids:
+            if len(file_ids) > 1:
+                raise RuntimeError(
+                    "API does not currently support attaching multiple files in a block."
+                )
+
+            block_data["file_id"] = file_ids[0]
+
+        blocks_url = f"{self.datalab_api_url}/update-block/"
+        payload = {
+            "block_data": block_data,
+            "block_type": block_type,
+            "save_to_db": True,
+        }
+
+        resp = self.session.post(blocks_url, json=payload, follow_redirects=True)
+        if resp.status_code != 200:
+            raise RuntimeError(f"Failed to update block {block_type=}:\n{resp.text}")
+
+        return resp.json()["new_block_data"]

datalab_api/_base.py

@@ -0,0 +1,200 @@
+import functools
+import logging
+import os
+from importlib.metadata import version
+from typing import Any, Optional
+
+import httpx
+from rich.logging import RichHandler
+from rich.pretty import pprint
+
+__version__ = version("datalab-api")
+
+__all__ = ("__version__", "BaseDatalabClient")
+
+
+def pretty_displayer(method):
+    @functools.wraps(method)
+    def rich_wrapper(self, *args, **kwargs):
+        display = kwargs.pop("display", False)
+        result = method(self, *args, **kwargs)
+        if display:
+            if isinstance(result, dict) and "blocks_obj" in result:
+                blocks: dict[str, dict] = result["blocks_obj"]
+                for block in blocks.values():
+                    if "bokeh_plot_data" in block:
+                        bokeh_from_json(block)
+            pprint(result, max_length=None, max_string=100, max_depth=3)
+
+        return result
+
+    return rich_wrapper
+
+
+class AutoPrettyPrint(type):
+    def __new__(cls, name, bases, dct):
+        for attr, value in dct.items():
+            if callable(value) and not attr.startswith("__"):
+                dct[attr] = pretty_displayer(value)
+        return super().__new__(cls, name, bases, dct)
+
+
+def bokeh_from_json(block_data):
+    from bokeh.io import curdoc
+    from bokeh.plotting import show
+
+    if "bokeh_plot_data" in block_data:
+        bokeh_plot_data = block_data["bokeh_plot_data"]
+    else:
+        bokeh_plot_data = block_data
+    curdoc().replace_with_json(bokeh_plot_data["doc"])
+    show(curdoc().roots[0])
+
+
+class BaseDatalabClient(metaclass=AutoPrettyPrint):
+    """A base class that implements some of the shared/logistical functionality
+    (hopefully) common to all Datalab clients.
+
+    Mainly used to keep the namespace of the 'real' client classes clean and
+    readable by users.
+    """
+
+    _api_key: Optional[str] = None
+    _session: Optional[httpx.Client] = None
+    _headers: dict[str, str] = {}
+
+    bad_server_versions: Optional[tuple[tuple[int, int, int]]] = ((0, 2, 0),)
+    """Any known server versions that are not supported by this client."""
+
+    min_server_version: tuple[int, int, int] = (0, 1, 0)
+    """The minimum supported server version that this client supports."""
+
+    def __init__(self, datalab_api_url: str, log_level: str = "WARNING"):
+        """Creates an authenticated client.
+
+        An API key is required to authenticate requests. The client will attempt to load it from a
+        series of environment variables, `DATALAB_API_KEY` and prefixed versions for the given
+        requested instance (e.g., `PUBLIC_DATALAB_API_KEY` for the public deployment
+        which has prefix `public`).
+
+        Parameters:
+            datalab_api_url: The URL of the Datalab API.
+                TODO: If the URL of a datalab *UI* is provided, a request will be made to attempt
+                to resolve the underlying API URL (e.g., `https://public.datalab.odbx.science`
+                will 'redirect' to `https://public.api.odbx.science`).
+            log_level: The logging level to use for the client. Defaults to "WARNING".
+
+
+        """
+
+        self.datalab_api_url = datalab_api_url
+        if not self.datalab_api_url:
+            raise ValueError("No Datalab API URL provided.")
+        if not self.datalab_api_url.startswith("http"):
+            self.datalab_api_url = f"https://{self.datalab_api_url}"
+        logging.basicConfig(level=log_level, handlers=[RichHandler()])
+        self.log = logging.getLogger(__name__)
+
+        self._http_client = httpx.Client
+        self._headers["User-Agent"] = f"Datalab Python API/{__version__}"
+
+        info_json = self.get_info()
+
+        self._datalab_api_versions: list[str] = info_json["data"]["attributes"][
+            "available_api_versions"
+        ]
+        self._datalab_server_version: str = info_json["data"]["attributes"]["server_version"]
+        self._datalab_instance_prefix: Optional[str] = info_json["data"]["attributes"].get(
+            "identifier_prefix"
+        )
+
+        self._find_api_key()
+
+    def get_info(self) -> dict[str, Any]:
+        raise NotImplementedError
+
+    @property
+    def session(self) -> httpx.Client:
+        if self._session is None:
+            return self._http_client(headers=self.headers)
+        return self._session
+
+    @property
+    def headers(self):
+        return self._headers
+
+    def _version_negotiation(self):
+        """Check whether this client is expected to work with this instance.
+
+        Raises:
+            RuntimeError: If the server version is not supported or if no supported API versions are found.
+
+        """
+
+        for available_api_version in sorted(self._datalab_api_versions):
+            major, minor, _ = (int(_) for _ in available_api_version.split("."))
+            if major == self.min_api_version[0] and minor == self.min_api_version[1]:
+                self._selected_api_version = available_api_version
+                break
+        else:
+            raise RuntimeError(f"No supported API versions found in {self._datalab_api_versions=}")
+
+        if self._datalab_server_version in self.bad_server_versions:
+            raise RuntimeError(
+                f"Server version {self._datalab_server_version} is not supported by this client."
+            )
+
+    @property
+    def api_key(self) -> str:
+        """The API key used to authenticate requests to the Datalab API, passed
+        as the `DATALAB-API-KEY` HTTP header.
+
+        This can be retrieved by an authenticated user with the `/get-api-key`
+        endpoint of a Datalab API.
+
+        """
+        if self._api_key is not None:
+            return self._api_key
+        return self._find_api_key()
+
+    def _find_api_key(self) -> str:
+        """Checks various environment variables for an API key and sets the value in the
+        session headers.
+        """
+        if self._api_key is None:
+            key_env_var = "DATALAB_API_KEY"
+
+            api_key: Optional[str] = None
+
+            # probe the prefixed environment variable first
+            if self._datalab_instance_prefix is not None:
+                api_key = os.getenv(f"{self._datalab_instance_prefix.upper()}_{key_env_var}")
+
+            if api_key is None:
+                api_key = os.getenv("DATALAB_API_KEY")
+
+            if api_key is None:
+                raise ValueError(
+                    f"No API key found in environment variables {key_env_var}/<prefix>_{key_env_var}."
+                )
+
+            self._api_key = api_key
+
+            # Reset session as we are now updating the headers
+            if self._session is not None:
+                try:
+                    self._session.close()
+                except Exception:
+                    pass
+                finally:
+                    self._session = None
+            self._headers["DATALAB-API-KEY"] = self.api_key
+
+        return self.api_key
+
+    def __enter__(self) -> "BaseDatalabClient":
+        return self
+
+    def __exit__(self, *_):
+        if self._session is not None:
+            self._session.close()

datalab_api/cli.py

@@ -0,0 +1,195 @@
+import time
+from typing import Annotated, Optional
+
+import typer
+from click_shell import make_click_shell
+from rich.console import Console
+from rich.live import Live
+from rich.panel import Panel
+from rich.pretty import pprint
+from rich.table import Table
+
+from datalab_api import DatalabClient
+
+app = typer.Typer(
+    name="datalab",
+    help="A command-line interface for the Datalab API.",
+    epilog="Copyright (c) 2020-2024 Matthew Evans, Joshua Bocarsly & the Datalab Development Team.",
+)
+
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def launch(
+    ctx: typer.Context,
+    instance_url: Annotated[Optional[str], typer.Argument()] = None,
+    animate_intro: bool = True,
+):
+    """Makes an interactive REPL-style interface using the subcommands below."""
+    shell = make_click_shell(
+        ctx,
+        prompt="datalab > ",
+    )
+
+    animation_intro = _make_fancy_intro()
+    if animate_intro:
+        with Live(console=console, auto_refresh=False) as live:
+            for frame in animation_intro:
+                live._live_render.set_renderable(
+                    Panel(
+                        frame,
+                        subtitle=app.info.epilog,
+                        width=len(app.info.epilog) + 6,
+                        highlight=False,
+                    )
+                )  # type: ignore
+                console.print(live._live_render.position_cursor())
+                time.sleep(0.05)
+
+    console.print(
+        Panel(animation_intro[-1], subtitle=app.info.epilog, width=len(app.info.epilog) + 6),
+        highlight=False,
+    )  # type: ignore
+    console.print()
+    console.print(
+        Panel(
+            "This CLI is an experimental work in progress and does not expose the full functionality of the underlying DatalabClient.",
+            title="[red]WARNING![/red]",
+            width=len(app.info.epilog) + 6,
+        )
+    )
+    console.print()
+
+    if instance_url:
+        authenticate(ctx, instance_url)
+    shell.cmdloop()
+
+
+def _get_client(
+    ctx: typer.Context,
+    instance_url: Optional[str] = None,
+    log_level: str = "WARNING",
+):
+    client = getattr(ctx, "client", None)
+    if instance_url is None:
+        instance_url = getattr(ctx, "instance_url", None)  # type: ignore
+    if client is None:
+        client = DatalabClient(datalab_api_url=instance_url, log_level=log_level)  # type: ignore
+    ctx.client = client
+    ctx.instance_url = client.datalab_api_url
+    return ctx.client
+
+
+def _get_instance_url(ctx: typer.Context):
+    instance_url = getattr(ctx, "instance_url", None)
+    if instance_url is None:
+        raise ValueError("No Datalab API URL provided.")
+    return instance_url
+
+
+@app.command()
+def authenticate(
+    ctx: typer.Context,
+    instance_url: Annotated[Optional[str], typer.Argument()] = None,
+    log_level: str = "WARNING",
+):
+    client = _get_client(ctx, instance_url, log_level)
+    user = client.authenticate()
+    console.print(
+        f"Welcome [red]{user['display_name']}[/red]!\nSuccessfully authenticated at [blue]{client.datalab_api_url}[/blue]."
+    )
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    item_type: str,
+    instance_url: Annotated[Optional[str], typer.Argument()] = None,
+    page_limit: int = 10,
+    log_level: str = "WARNING",
+):
+    """Get a table of items of the given type."""
+    client = _get_client(ctx, instance_url, log_level)
+    items = client.get_items(item_type)
+    table = Table(title=f"/{item_type}/", show_lines=True)
+    table.add_column("type", overflow="crop", justify="center")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("refcode", style="magenta", no_wrap=True)
+    table.add_column("name", width=30, overflow="ellipsis", no_wrap=True)
+    table.add_column("nblocks", justify="right")
+    table.add_column("collections")
+    table.add_column("creators")
+    for item in items[:page_limit]:
+        table.add_row(
+            item["type"][0].upper(),
+            item["item_id"],
+            item["refcode"],
+            item["name"],
+            str(item["nblocks"]),
+            ", ".join(d["collection_id"] for d in item["collections"]),
+            ", ".join(d["display_name"] for d in item["creators"]),
+            end_section=True,
+        )
+    console.print(table)
+
+
+@app.command()
+def info(ctx: typer.Context, instance_url: str, log_level: str = "WARNING"):
+    """Print the server info."""
+    client = _get_client(ctx, instance_url, log_level)
+    pprint(client.get_info())
+
+
+def _make_fancy_intro(animate=True):
+    """Bit of fun, make an animated datalab logo intro to the CLI."""
+    import random
+
+    intro_ascii = """
+              oooo              o8              o888             oooo
+           ooooo888    ooooooo o888oo  ooooooo    888   ooooooo    888ooooo
+         888    888    ooooo888 888    ooooo888   888   ooooo888   888    888
+         888    888  888    888 888  888    888   888 888    888   888    888
+           88ooo888o  88ooo88 8o 888o 88ooo88 8o o888o 88ooo88 8o o888ooo88
+    """
+
+    # Colour themes that should work in both light and dark terminals
+    themes = [
+        ["dark_orange", "salmon1", "light_coral", "pale_violet_red1", "orchid2", "orchid1"],
+        ["dark_orange3", "indian_red", "hot_pink3", "hot_pink2", "orchid"],
+        ["chartreuse4", "pale_turqoise4", "steel_blue", "steel_blue3", "cornflower_blue"],
+    ]
+
+    colours = random.choice(themes)
+    random.shuffle(colours)
+    colours.append("black")
+    num_colours = len(colours)
+
+    animation: list[str] = []
+    colours_by_index: list[int] = [num_colours - 1] * len(intro_ascii)
+    beta_1: float = 0.2
+    beta_2: float = 0.6
+    steps: int = 0
+    max_steps: int = 50
+
+    while max(colours_by_index) != 0:
+        intro_fancy = ""
+        for ind, char in enumerate(intro_ascii):
+            if char == " ":
+                colours_by_index[ind] = 0
+                intro_fancy += " "
+            else:
+                if colours_by_index[ind] != 0 and random.random() < (steps / max_steps) * beta_1:
+                    colours_by_index[ind] = 0
+                elif colours_by_index[ind] != 0 and random.random() < (steps / max_steps) * beta_2:
+                    colours_by_index[ind] = random.randint(1, num_colours - 2)
+                intro_fancy += f"[{colours[colours_by_index[ind]]}]{char}[/]"
+
+        animation.append(intro_fancy)
+        steps += 1
+
+    return animation
+
+
+if __name__ == "__main__":
+    app()

datalab_api-0.2.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Matthew Evans, Joshua Bocarsly and the Datalab Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datalab_api-0.2.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.1
+Name: datalab-api
+Version: 0.2.0
+Author-email: Matthew Evans <matthew@ml-evs.science>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Other/Nonlisted Topic
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx ~=0.27
+Requires-Dist: bokeh ~=2.4
+Requires-Dist: rich ~=13.0
+Provides-Extra: cli
+Requires-Dist: typer ~=0.9 ; extra == 'cli'
+Requires-Dist: click-shell ~=2.1 ; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pre-commit ~=3.0 ; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs ; extra == 'docs'
+Requires-Dist: mkdocs-material ; extra == 'docs'
+Requires-Dist: mkdocstrings[python-legacy] ; extra == 'docs'
+Requires-Dist: mkdocs-awesome-pages-plugin ; extra == 'docs'
+Requires-Dist: mkdocs-jupyter ; extra == 'docs'
+
+# <div align="center"><i>datalab</i> Python API</div>
+
+<div align="center">
+<a href="https://datalab-python-api.readthedocs.io/en/stable/?badge=stable">
+<img src="https://readthedocs.org/projects/datalab-python-api/badge/?version=stable"></img>
+</a>
+</div>
+
+A simple Python API that can interact with [*datalab*](https://github.com/the-grey-group/datalab) instances.
+
+The idea here is to provide a set of utility functions and models for manipulating samples, cells, inventory, files, users and metadata associated with *datalab* entries in an automated way.
+
+This API may not expose all the functionality available in a given *datalab* instance, and the idea would be that this package can support multiple versions of the underlying [*datalab* REST API](https://the-datalab.readthedocs.io/en/latest/rest_api/).
+This means that the API is primarily *functional* in nature, as opposed to object-oriented, since *datalab* instances are free to use their own custom data models.
+The available schemas are reported as instance metadata and in the future object-oriented models may be able to be genereated directly in the client (so e.g., the returned data would be Python objects like `Sample` rather than JSON data).
+
+The issue tracker here will be used to track development of features, as well as bug reports.
+If you have any suggestions or feedback, please post it there.
+
+## Installation
+
+The API can be used by installing this repository with `pip`, ideally in a fresh Python 3.9+ environment (created using e.g., conda, virtualenv or other related tools -- if you're not sure about this, ask).
+
+Either from PyPI, for the latest released version:
+
+```shell
+pip install datalab-api
+```
+
+or for the latest development version from GitHub:
+
+```shell
+git clone git@github.com:datalab-org/datalab-api
+cd datalab-api
+pip install .
+```
+
+## Usage
+
+Example usage as a Jupyter notebook can be found in the `examples` directory or
+in the [online documentation](https://datalab-api.readthedocs.io/), as
+well as the full [API
+documentation](https://datalab-api.readthedocs.io/en/latest/reference/).
+
+### Authentication
+
+Currently the only supported authentication method is via an API key.
+You can generate one for your account for a given *datalab* instance by visiting the `/get-api-key` endpoint of your chosen instance, or, if using a recent version of *datalab*, by visiting your account settings in the browser.
+
+This API key can be set via the environment variable `DATALAB_API_KEY`.
+To suport the use case of needing to interact with multiple datalab instances, the client will also check prefixed environment variables that use the [`IDENTIFIER_PREFIX` of the chosen datalab instance](https://the-datalab.readthedocs.io/en/latest/config/#mandatory-settings), e.g., `GREY_DATALAB_API_KEY` or `PUBLIC_DATALAB_API_KEY`.
+Only keys that match will be read (e.g., other environment variables starting with `PUBLIC_` will be ignored, when connecting to the [public demo datalab](https://public.datalab.odbx.science)).
+
+### Python API
+
+This package implements basic functionality for displaying and manipulating entries:
+
+```python
+from datalab_api import DatalabClient
+
+with DatalabClient("https://api.public.odbx.science") as client:
+
+    # List all items of a given type
+    items = client.get_items()
+
+    # Get more info on a particular item
+    item = client.get_item(item_id="test")
+
+    # Upload a file to an item
+    file_response = client.upload_file(filepath="my_echem_data.mpr", item_id="test")
+
+```
+
+### Command-line interface (CLI)
+
+There is also an EXPERIMENTAL CLI, exposed via the `datalab` command.
+This CLI has many subcommands, which can be listed with `datalab help` or by entering the shell with just `datalab`.
+For now, the CLI does not expose all of the functionality of the underlying API, and is mostly oriented on GET-focused operations.
+
+```shell
+$ datalab
+
+╭──────────────────────────────────────────────────────────────────────────────────────────╮
+│                                                                                          │
+│               oooo              o8              o888             oooo                    │
+│            ooooo888    ooooooo o888oo  ooooooo    888   ooooooo    888ooooo              │
+│          888    888    ooooo888 888    ooooo888   888   ooooo888   888    888            │
+│          888    888  888    888 888  888    888   888 888    888   888    888            │
+│            88ooo888o  88ooo88 8o 888o 88ooo88 8o o888o 88ooo88 8o o888ooo88              │
+│                                                                                          │
+╰─ Copyright (c) 2020-2024 Matthew Evans, Joshua Bocarsly & the Datalab Development Team. ─╯
+
+datalab > help
+
+Documented commands (type help <topic>):
+========================================
+authenticate  get  info
+
+Undocumented commands:
+======================
+exit  help  quit
+
+datalab > help get
+
+ Usage: [INSTANCE_URL] get [OPTIONS] ITEM_TYPE [INSTANCE_URL]
+
+ Get a table of items of the given type.
+
+╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────╮
+│ *    item_type         TEXT            [default: None] [required]                                   │
+│      instance_url      [INSTANCE_URL]  [default: None]                                              │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────╮
+│ --page-limit        INTEGER  [default: 10]                                                          │
+│ --api-key           TEXT     [default: None]                                                        │
+│ --log-level         TEXT     [default: WARNING]                                                     │
+│ --help                       Show this message and exit.                                            │
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
+
+datalab > get samples api.odbx.science --page-limit 2
+                                                    /samples/
+┏━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
+┃ type ┃ ID              ┃ refcode     ┃ name                           ┃ nblocks ┃ collections ┃ creators      ┃
+┡━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
+│  C   │ test_api        │ grey:WHQFXG │                                │       0 │             │ Matthew Evans │
+├──────┼─────────────────┼─────────────┼────────────────────────────────┼─────────┼─────────────┼───────────────┤
+│  S   │ test12331231312 │ grey:GFSUQM │                                │       1 │             │ Matthew Evans │
+└──────┴─────────────────┴─────────────┴────────────────────────────────┴─────────┴─────────────┴───────────────┘
+```

datalab_api-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+datalab_api/__init__.py,sha256=Dyu1SFjboTSiuovspMcFrQK5AMUT5OOYLhXXrw4AgOE,14227
+datalab_api/_base.py,sha256=hZw8JiovHmCyVPErYg5cXdI8Ra6_q8eoMtC4AkJ8JjU,7003
+datalab_api/cli.py,sha256=sC3fPMQPGnZK4Uz3hHtnk_GjSTLkTS8fydGSILAG8lM,6451
+datalab_api-0.2.0.dist-info/LICENSE,sha256=lSeXwvkn4v5VW4QJ5JSeoxIqUtngjE6Yo6i-iYJQj3M,1120
+datalab_api-0.2.0.dist-info/METADATA,sha256=jP8VrUeCGChg6MxRKK7kQA35Rq1ddFv5zPVaa1wFywU,10211
+datalab_api-0.2.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+datalab_api-0.2.0.dist-info/entry_points.txt,sha256=oP1qs074fbtdexaK705O96H3ZXQFpNha_UB-1CbWe64,48
+datalab_api-0.2.0.dist-info/top_level.txt,sha256=IvPpoa6z7jfGDXBZrDcC5cNEwDl3_L0u-mYrPh327UQ,12
+datalab_api-0.2.0.dist-info/RECORD,,

datalab_api-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.43.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

datalab_api-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+datalab = datalab_api.cli:app

datalab_api-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+datalab_api