==================== Images API Reference ==================== .. currentmodule:: neuro_sdk Images ====== .. class:: Images Docker image subsystem. Used for pushing docker images onto Neuro docker registry for later usage by :meth:`Jobs.run` and pulling these images back to local docker. .. comethod:: push(local: LocalImage, \ remote: Optional[RemoteImage] = None, \ *, \ progress: Optional[AbstractDockerImageProgress] = None, \ ) -> RemoteImage Push *local* docker image to *remote* side. :param LocalImage local: a spec of local docker image (e.g. created by ``docker build``) for pushing on Neuro Registry. :param RemoteImage remote: a spec for remote image on Neuro Registry. Calculated from *local* image automatically if ``None`` (default). :param AbstractDockerImageProgress progress: a callback interface for reporting pushing progress, ``None`` for no progress report (default). :return: *remote* image if explicitly specified, calculated remote image if *remote* is ``None`` (:class:`RemoteImage`) .. comethod:: pull(remote: Optional[RemoteImage] = None, \ local: LocalImage, \ *, \ progress: Optional[AbstractDockerImageProgress] = None, \ ) -> RemoteImage Pull *remote* image from Neuro registry to *local* docker side. :param RemoteImage remote: a spec for remote image on Neuro registry. :param LocalImage local: a spec of local docker image to pull. Calculated from *remote* image automatically if ``None`` (default). :param AbstractDockerImageProgress progress: a callback interface for reporting pulling progress, ``None`` for no progress report (default). :return: *local* image if explicitly specified, calculated remote image if *local* is ``None`` (:class:`LocalImage`) .. comethod:: digest(image: RemoteImage) -> str Get digest of an image in Neuro registry. :param RemoteImage image: a spec for remote image on Neuro registry. :return: string representing image digest .. comethod:: rm(image: RemoteImage, digest: str) -> str Delete remote image specified by given reference and digest from Neuro registry. :param RemoteImage image: a spec for remote image on Neuro registry. :param str digest: remote image digest, which can be obtained via `digest` method. .. comethod:: list(cluster_name: Optional[str] = None) -> List[RemoteImage] List images on Neuro registry available to the user. :param str cluster_name: name of the cluster. ``None`` means the current cluster (default). :return: list of remote images not including tags (:class:`List[RemoteImage]`) .. comethod:: tags(image: RemoteImage) -> List[RemoteImage] List image references with tags for the specified remote *image*. :param RemoteImage image: a spec for remote image without tag on Neuro registry. :return: list of remote images with tags (:class:`List[RemoteImage]`) .. comethod:: size(image: RemoteImage) -> int Return image size. :param RemoteImage image: a spec for remote image with tag on Neuro registry. :return: remote image size in bytes .. comethod:: tag_info(image: RemoteImage) -> Tag Return info about specified tag. :param RemoteImage image: a spec for remote image with tag on Neuro registry. :return: tag information (name and size) (:class:`Tag`) AbstractDockerImageProgress =========================== .. class:: AbstractDockerImageProgress Base class for image operations progress, e.g. :meth:`Images.pull` and :meth:`Images.push`. Inherited from :class:`abc.ABC`. .. method:: pull(data: ImageProgressPull) -> None Pulling image from remote Neuro registry to local Docker is started. :param ImageProgressPull data: additional data, e.g. local and remote image objects. .. method:: push(data: ImageProgressPush) -> None Pushing image from local Docker to remote Neuro registry is started. :param ImageProgressPush data: additional data, e.g. local and remote image objects. .. method:: step(data: ImageProgressStep) -> None Next step in image transfer is performed. :param ImageProgressStep data: additional data, e.g. image layer id and progress report. ImageProgressPull ================= .. class:: ImageProgressPull *Read-only* :class:`~dataclasses.dataclass` for pulling operation report. .. attribute:: src Source image, :class:`RemoteImage` instance. .. attribute:: dst Destination image, :class:`LocalImage` instance. .. class:: ImageProgressPush *Read-only* :class:`~dataclasses.dataclass` for pulling operation report. .. attribute:: src Source image, :class:`LocalImage` instance. .. attribute:: dst Destination image, :class:`RemoteImage` instance. .. class:: ImageProgressStep *Read-only* :class:`~dataclasses.dataclass` for push/pull progress step. .. attribute:: layer_id Image layer, :class:`str`. .. attribute:: message Progress message, :class:`str`. LocalImage ========== .. class:: LocalImage *Read-only* :class:`~dataclasses.dataclass` for describing *image* in local Docker system. .. attribute:: name Image name, :class:`str`. .. attribute:: tag Image tag (:class:`str`), ``None`` if the tag is omitted (implicit ``latest`` tag). RemoteImage =========== .. class:: RemoteImage *Read-only* :class:`~dataclasses.dataclass` for describing *image* in remote registry (Neuro Platform hosted or other registries like DockerHub_). .. attribute:: name Image name, :class:`str`. .. attribute:: tag Image tag (:class:`str`), ``None`` if the tag is omitted (implicit ``latest`` tag). .. attribute:: owner User name (:class:`str`) of a person who manages this image. Public DockerHub_ images (e.g. ``"ubuntu:latest"``) have no *owner*, the attribute is ``None``. .. attribute:: org_name Name (:class:`str`) of an organization who manages this image or `None` if there is no such org. Public DockerHub_ images (e.g. ``"ubuntu:latest"``) have no *org*, the attribute is ``None``. .. attribute:: registry Host name for images hosted on Neuro Registry (:class:`str`), ``None`` for other registries like DockerHub_. .. method:: as_docker_url(with_scheme: bool = False) -> str URL that can be used to reference this image with Docker. :param bool with_scheme: if set to True, returned URL includes scheme (`https://`), otherwise (default behavior) - scheme is omitted. .. method:: with_tag(tag: bool) -> RemoteImage Creates a new reference to remote image with *tag*. :param str tag: new tag :return: remote image with *tag* .. py:classmethod:: new_neuro_image(name: str, registry: str, *, owner: str, cluster_name: str, tag: Optional[str] = None) -> RemoteImage Create a new instance referring to an image hosted on Neuro Platform. :param str name: name of the image :param str registry: registry where the image is located :param str owner: image owner name :param str cluster_name: name of the cluster :param str tag: image tag .. py:classmethod:: new_external_image(name: str, registry: Optional[str] = None, *, tag: Optional[str] = None) -> RemoteImage Create a new instance referring to an image hosted on an external registry (e.g. DockerHub_). :param str name: name of the image :param str registry: registry where the image is located :param str tag: image tag .. class:: Tag *Read-only* :class:`~dataclasses.dataclass` for tag information. .. attribute:: name Tag name, :class:`str`. .. attribute:: size Tag size in bytes, :class:`int`. .. _DockerHub: https://hub.docker.com