modal 1.0.4.dev12__py3-none-any.whl → 1.0.5__py3-none-any.whl

modal/image.pyi

@@ -19,8 +19,13 @@ import typing_extensions
 ImageBuilderVersion = typing.Literal["2023.12", "2024.04", "2024.10", "PREVIEW"]
 
 class _AutoDockerIgnoreSentinel:
-    def __repr__(self) -> str: ...
-    def __call__(self, _: pathlib.Path) -> bool: ...
+    def __repr__(self) -> str:
+        """Return repr(self)."""
+        ...
+
+    def __call__(self, _: pathlib.Path) -> bool:
+        """Call self as a function."""
+        ...
 
 AUTO_DOCKERIGNORE: _AutoDockerIgnoreSentinel
 
@@ -43,8 +48,17 @@ def _get_modal_requirements_path(
 def _get_modal_requirements_command(version: typing.Literal["2023.12", "2024.04", "2024.10", "PREVIEW"]) -> str: ...
 def _flatten_str_args(
     function_name: str, arg_name: str, args: collections.abc.Sequence[typing.Union[str, list[str]]]
-) -> list[str]: ...
-def _validate_packages(packages: list[str]) -> bool: ...
+) -> list[str]:
+    """Takes a sequence of strings, or string lists, and flattens it.
+
+    Raises an error if any of the elements are not strings or string lists.
+    """
+    ...
+
+def _validate_packages(packages: list[str]) -> bool:
+    """Validates that a list of packages does not contain any command-line options."""
+    ...
+
 def _make_pip_install_args(
     find_links: typing.Optional[str] = None,
     index_url: typing.Optional[str] = None,
@@ -59,7 +73,15 @@ def _create_context_mount(
     docker_commands: collections.abc.Sequence[str],
     ignore_fn: collections.abc.Callable[[pathlib.Path], bool],
     context_dir: pathlib.Path,
-) -> typing.Optional[modal.mount._Mount]: ...
+) -> typing.Optional[modal.mount._Mount]:
+    """Creates a context mount from a list of docker commands.
+
+    1. Paths are evaluated relative to context_dir.
+    2. First selects inclusions based on COPY commands in the list of commands.
+    3. Then ignore any files as per the ignore predicate.
+    """
+    ...
+
 def _create_context_mount_function(
     ignore: typing.Union[
         collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool], _AutoDockerIgnoreSentinel
@@ -71,22 +93,42 @@ def _create_context_mount_function(
 ): ...
 
 class _ImageRegistryConfig:
-    def __init__(self, registry_auth_type: int = 0, secret: typing.Optional[modal.secret._Secret] = None): ...
+    """mdmd:hidden"""
+    def __init__(self, registry_auth_type: int = 0, secret: typing.Optional[modal.secret._Secret] = None):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
     def get_proto(self) -> modal_proto.api_pb2.ImageRegistryConfig: ...
 
 class DockerfileSpec:
+    """DockerfileSpec(commands: list[str], context_files: dict[str, str])"""
+
     commands: list[str]
     context_files: dict[str, str]
 
-    def __init__(self, commands: list[str], context_files: dict[str, str]) -> None: ...
-    def __repr__(self): ...
-    def __eq__(self, other): ...
+    def __init__(self, commands: list[str], context_files: dict[str, str]) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
 
 async def _image_await_build_result(
     image_id: str, client: modal.client._Client
 ) -> modal_proto.api_pb2.ImageJoinStreamingResponse: ...
 
 class _Image(modal._object._Object):
+    """Base class for container images to run functions in.
+
+    Do not construct this class directly; instead use one of its static factory methods,
+    such as `modal.Image.debian_slim`, `modal.Image.from_registry`, or `modal.Image.micromamba`.
+    """
+
     force_build: bool
     inside_exceptions: list[Exception]
     _serve_mounts: frozenset[modal.mount._Mount]
@@ -100,7 +142,18 @@ class _Image(modal._object._Object):
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
     def _add_mount_layer_or_copy(self, mount: modal.mount._Mount, copy: bool = False): ...
     @property
-    def _mount_layers(self) -> typing.Sequence[modal.mount._Mount]: ...
+    def _mount_layers(self) -> typing.Sequence[modal.mount._Mount]:
+        """Non-evaluated mount layers on the image
+
+        When the image is used by a Modal container, these mounts need to be attached as well to
+        represent the full image content, as they haven't yet been represented as a layer in the
+        image.
+
+        When the image is used as a base image for a new layer (that is not itself a mount layer)
+        these mounts need to first be inserted as a copy operation (.copy_mount) into the image.
+        """
+        ...
+
     def _assert_no_mount_layers(self): ...
     @staticmethod
     def _from_args(
@@ -121,10 +174,31 @@ class _Image(modal._object._Object):
         _namespace: int = 1,
         _do_assert_no_mount_layers: bool = True,
     ): ...
-    def _copy_mount(self, mount: modal.mount._Mount, remote_path: typing.Union[str, pathlib.Path] = ".") -> _Image: ...
+    def _copy_mount(self, mount: modal.mount._Mount, remote_path: typing.Union[str, pathlib.Path] = ".") -> _Image:
+        """mdmd:hidden
+        Internal
+        """
+        ...
+
     def add_local_file(
         self, local_path: typing.Union[str, pathlib.Path], remote_path: str, *, copy: bool = False
-    ) -> _Image: ...
+    ) -> _Image:
+        """Adds a local file to the image at `remote_path` within the container
+
+        By default (`copy=False`), the files are added to containers on startup and are not built into the actual Image,
+        which speeds up deployment.
+
+        Set `copy=True` to copy the files into an Image layer at build time instead, similar to how
+        [`COPY`](https://docs.docker.com/engine/reference/builder/#copy) works in a `Dockerfile`.
+
+        copy=True can slow down iteration since it requires a rebuild of the Image and any subsequent
+        build steps whenever the included files change, but it is required if you want to run additional
+        build steps after this one.
+
+        *Added in v0.66.40*: This method replaces the deprecated `modal.Image.copy_local_file` method.
+        """
+        ...
+
     def add_local_dir(
         self,
         local_path: typing.Union[str, pathlib.Path],
@@ -132,10 +206,72 @@ class _Image(modal._object._Object):
         *,
         copy: bool = False,
         ignore: typing.Union[collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]] = [],
-    ) -> _Image: ...
+    ) -> _Image:
+        """Adds a local directory's content to the image at `remote_path` within the container
+
+        By default (`copy=False`), the files are added to containers on startup and are not built into the actual Image,
+        which speeds up deployment.
+
+        Set `copy=True` to copy the files into an Image layer at build time instead, similar to how
+        [`COPY`](https://docs.docker.com/engine/reference/builder/#copy) works in a `Dockerfile`.
+
+        copy=True can slow down iteration since it requires a rebuild of the Image and any subsequent
+        build steps whenever the included files change, but it is required if you want to run additional
+        build steps after this one.
+
+        **Usage:**
+
+        ```python
+        from modal import FilePatternMatcher
+
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=["*.venv"],
+        )
+
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=lambda p: p.is_relative_to(".venv"),
+        )
+
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=FilePatternMatcher("**/*.txt"),
+        )
+
+        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=~FilePatternMatcher("**/*.py"),
+        )
+
+        # You can also read ignore patterns from a file.
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=FilePatternMatcher.from_file("/path/to/ignorefile"),
+        )
+        ```
+
+        *Added in v0.66.40*: This method replaces the deprecated `modal.Image.copy_local_dir` method.
+        """
+        ...
+
     def copy_local_file(
         self, local_path: typing.Union[str, pathlib.Path], remote_path: typing.Union[str, pathlib.Path] = "./"
-    ) -> _Image: ...
+    ) -> _Image:
+        """mdmd:hidden
+        Copy a file into the image as a part of building it.
+
+        This works in a similar way to [`COPY`](https://docs.docker.com/engine/reference/builder/#copy)
+        works in a `Dockerfile`.
+        """
+        ...
+
     def add_local_python_source(
         self,
         *module_names: str,
@@ -143,15 +279,106 @@ class _Image(modal._object._Object):
         ignore: typing.Union[
             collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]
         ] = modal.file_pattern_matcher.NON_PYTHON_FILES,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Adds locally available Python packages/modules to containers
+
+        Adds all files from the specified Python package or module to containers running the Image.
+
+        Packages are added to the `/root` directory of containers, which is on the `PYTHONPATH`
+        of any executed Modal Functions, enabling import of the module by that name.
+
+        By default (`copy=False`), the files are added to containers on startup and are not built into the actual Image,
+        which speeds up deployment.
+
+        Set `copy=True` to copy the files into an Image layer at build time instead. This can slow down iteration since
+        it requires a rebuild of the Image and any subsequent build steps whenever the included files change, but it is
+        required if you want to run additional build steps after this one.
+
+        **Note:** This excludes all dot-prefixed subdirectories or files and all `.pyc`/`__pycache__` files.
+        To add full directories with finer control, use `.add_local_dir()` instead and specify `/root` as
+        the destination directory.
+
+        By default only includes `.py`-files in the source modules. Set the `ignore` argument to a list of patterns
+        or a callable to override this behavior, e.g.:
+
+        ```py
+        # includes everything except data.json
+        modal.Image.debian_slim().add_local_python_source("mymodule", ignore=["data.json"])
+
+        # exclude large files
+        modal.Image.debian_slim().add_local_python_source(
+            "mymodule",
+            ignore=lambda p: p.stat().st_size > 1e9
+        )
+        ```
+
+        *Added in v0.67.28*: This method replaces the deprecated `modal.Mount.from_local_python_packages` pattern.
+        """
+        ...
+
     def copy_local_dir(
         self,
         local_path: typing.Union[str, pathlib.Path],
         remote_path: typing.Union[str, pathlib.Path] = ".",
         ignore: typing.Union[collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]] = [],
-    ) -> _Image: ...
+    ) -> _Image:
+        """mdmd:hidden
+        **Deprecated**: Use image.add_local_dir instead
+
+        Copy a directory into the image as a part of building the image.
+
+        This works in a similar way to [`COPY`](https://docs.docker.com/engine/reference/builder/#copy)
+        works in a `Dockerfile`.
+
+        **Usage:**
+
+        ```python notest
+        from pathlib import Path
+        from modal import FilePatternMatcher
+
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=["**/*.venv"],
+        )
+
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=lambda p: p.is_relative_to(".venv"),
+        )
+
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=FilePatternMatcher("**/*.txt"),
+        )
+
+        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=~FilePatternMatcher("**/*.py"),
+        )
+
+        # You can also read ignore patterns from a file.
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=FilePatternMatcher.from_file("/path/to/ignorefile"),
+        )
+        ```
+        """
+        ...
+
     @staticmethod
-    async def from_id(image_id: str, client: typing.Optional[modal.client._Client] = None) -> _Image: ...
+    async def from_id(image_id: str, client: typing.Optional[modal.client._Client] = None) -> _Image:
+        """Construct an Image from an id and look up the Image result.
+
+        The ID of an Image object can be accessed using `.object_id`.
+        """
+        ...
+
     def pip_install(
         self,
         *packages: typing.Union[str, list[str]],
@@ -163,7 +390,36 @@ class _Image(modal._object._Object):
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret._Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Install a list of Python packages using pip.
+
+        **Examples**
+
+        Simple installation:
+        ```python
+        image = modal.Image.debian_slim().pip_install("click", "httpx~=0.23.3")
+        ```
+
+        More complex installation:
+        ```python
+        image = (
+            modal.Image.from_registry(
+                "nvidia/cuda:12.2.0-devel-ubuntu22.04", add_python="3.11"
+            )
+            .pip_install(
+                "ninja",
+                "packaging",
+                "wheel",
+                "transformers==4.40.2",
+            )
+            .pip_install(
+                "flash-attn==2.5.8", extra_options="--no-build-isolation"
+            )
+        )
+        ```
+        """
+        ...
+
     def pip_install_private_repos(
         self,
         *repositories: str,
@@ -176,7 +432,39 @@ class _Image(modal._object._Object):
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         secrets: collections.abc.Sequence[modal.secret._Secret] = [],
         force_build: bool = False,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Install a list of Python packages from private git repositories using pip.
+
+        This method currently supports Github and Gitlab only.
+
+        - **Github:** Provide a `modal.Secret` that contains a `GITHUB_TOKEN` key-value pair
+        - **Gitlab:** Provide a `modal.Secret` that contains a `GITLAB_TOKEN` key-value pair
+
+        These API tokens should have permissions to read the list of private repositories provided as arguments.
+
+        We recommend using Github's ['fine-grained' access tokens](https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/).
+        These tokens are repo-scoped, and avoid granting read permission across all of a user's private repos.
+
+        **Example**
+
+        ```python
+        image = (
+            modal.Image
+            .debian_slim()
+            .pip_install_private_repos(
+                "github.com/ecorp/private-one@1.0.0",
+                "github.com/ecorp/private-two@main"
+                "github.com/ecorp/private-three@d4776502"
+                # install from 'inner' directory on default branch.
+                "github.com/ecorp/private-four#subdirectory=inner",
+                git_user="erikbern",
+                secrets=[modal.Secret.from_name("github-read-private")],
+            )
+        )
+        ```
+        """
+        ...
+
     def pip_install_from_requirements(
         self,
         requirements_txt: str,
@@ -189,7 +477,10 @@ class _Image(modal._object._Object):
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret._Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Install a list of Python packages from a local `requirements.txt` file."""
+        ...
+
     def pip_install_from_pyproject(
         self,
         pyproject_toml: str,
@@ -203,7 +494,16 @@ class _Image(modal._object._Object):
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret._Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Install dependencies specified by a local `pyproject.toml` file.
+
+        `optional_dependencies` is a list of the keys of the
+        optional-dependencies section(s) of the `pyproject.toml` file
+        (e.g. test, doc, experiment, etc). When provided,
+        all of the packages in each listed section are installed as well.
+        """
+        ...
+
     def poetry_install_from_file(
         self,
         poetry_pyproject_toml: str,
@@ -217,7 +517,17 @@ class _Image(modal._object._Object):
         only: list[str] = [],
         secrets: collections.abc.Sequence[modal.secret._Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Install poetry *dependencies* specified by a local `pyproject.toml` file.
+
+        If not provided as argument the path to the lockfile is inferred. However, the
+        file has to exist, unless `ignore_lockfile` is set to `True`.
+
+        Note that the root project of the poetry project is not installed, only the dependencies.
+        For including local python source files see `add_local_python_source`
+        """
+        ...
+
     def dockerfile_commands(
         self,
         *dockerfile_commands: typing.Union[str, list[str]],
@@ -230,18 +540,72 @@ class _Image(modal._object._Object):
         ignore: typing.Union[
             collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]
         ] = modal.image.AUTO_DOCKERIGNORE,
-    ) -> _Image: ...
-    def entrypoint(self, entrypoint_commands: list[str]) -> _Image: ...
-    def shell(self, shell_commands: list[str]) -> _Image: ...
+    ) -> _Image:
+        """Extend an image with arbitrary Dockerfile-like commands.
+
+        **Usage:**
+
+        ```python
+        from modal import FilePatternMatcher
+
+        # By default a .dockerignore file is used if present in the current working directory
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+        )
+
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=["*.venv"],
+        )
+
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=lambda p: p.is_relative_to(".venv"),
+        )
+
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=FilePatternMatcher("**/*.txt"),
+        )
+
+        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=~FilePatternMatcher("**/*.py"),
+        )
+
+        # You can also read ignore patterns from a file.
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=FilePatternMatcher.from_file("/path/to/dockerignore"),
+        )
+        ```
+        """
+        ...
+
+    def entrypoint(self, entrypoint_commands: list[str]) -> _Image:
+        """Set the entrypoint for the image."""
+        ...
+
+    def shell(self, shell_commands: list[str]) -> _Image:
+        """Overwrite default shell for the image."""
+        ...
+
     def run_commands(
         self,
         *commands: typing.Union[str, list[str]],
         secrets: collections.abc.Sequence[modal.secret._Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         force_build: bool = False,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Extend an image with a list of shell commands to run."""
+        ...
+
     @staticmethod
-    def micromamba(python_version: typing.Optional[str] = None, force_build: bool = False) -> _Image: ...
+    def micromamba(python_version: typing.Optional[str] = None, force_build: bool = False) -> _Image:
+        """A Micromamba base image. Micromamba allows for fast building of small Conda-based containers."""
+        ...
+
     def micromamba_install(
         self,
         *packages: typing.Union[str, list[str]],
@@ -250,7 +614,10 @@ class _Image(modal._object._Object):
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret._Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Install a list of additional packages using micromamba."""
+        ...
+
     @staticmethod
     def _registry_setup_commands(
         tag: str,
@@ -267,7 +634,36 @@ class _Image(modal._object._Object):
         force_build: bool = False,
         add_python: typing.Optional[str] = None,
         **kwargs,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Build a Modal Image from a public or private image registry, such as Docker Hub.
+
+        The image must be built for the `linux/amd64` platform.
+
+        If your image does not come with Python installed, you can use the `add_python` parameter
+        to specify a version of Python to add to the image. Otherwise, the image is expected to
+        have Python on PATH as `python`, along with `pip`.
+
+        You may also use `setup_dockerfile_commands` to run Dockerfile commands before the
+        remaining commands run. This might be useful if you want a custom Python installation or to
+        set a `SHELL`. Prefer `run_commands()` when possible though.
+
+        To authenticate against a private registry with static credentials, you must set the `secret` parameter to
+        a `modal.Secret` containing a username (`REGISTRY_USERNAME`) and
+        an access token or password (`REGISTRY_PASSWORD`).
+
+        To authenticate against private registries with credentials from a cloud provider,
+        use `Image.from_gcp_artifact_registry()` or `Image.from_aws_ecr()`.
+
+        **Examples**
+
+        ```python
+        modal.Image.from_registry("python:3.11-slim-bookworm")
+        modal.Image.from_registry("ubuntu:22.04", add_python="3.11")
+        modal.Image.from_registry("nvcr.io/nvidia/pytorch:22.12-py3")
+        ```
+        """
+        ...
+
     @staticmethod
     def from_gcp_artifact_registry(
         tag: str,
@@ -277,7 +673,38 @@ class _Image(modal._object._Object):
         force_build: bool = False,
         add_python: typing.Optional[str] = None,
         **kwargs,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Build a Modal image from a private image in Google Cloud Platform (GCP) Artifact Registry.
+
+        You will need to pass a `modal.Secret` containing [your GCP service account key data](https://cloud.google.com/iam/docs/keys-create-delete#creating)
+        as `SERVICE_ACCOUNT_JSON`. This can be done from the [Secrets](https://modal.com/secrets) page.
+        Your service account should be granted a specific role depending on the GCP registry used:
+
+        - For Artifact Registry images (`pkg.dev` domains) use
+          the ["Artifact Registry Reader"](https://cloud.google.com/artifact-registry/docs/access-control#roles) role
+        - For Container Registry images (`gcr.io` domains) use
+          the ["Storage Object Viewer"](https://cloud.google.com/artifact-registry/docs/transition/setup-gcr-repo) role
+
+        **Note:** This method does not use `GOOGLE_APPLICATION_CREDENTIALS` as that
+        variable accepts a path to a JSON file, not the actual JSON string.
+
+        See `Image.from_registry()` for information about the other parameters.
+
+        **Example**
+
+        ```python
+        modal.Image.from_gcp_artifact_registry(
+            "us-east1-docker.pkg.dev/my-project-1234/my-repo/my-image:my-version",
+            secret=modal.Secret.from_name(
+                "my-gcp-secret",
+                required_keys=["SERVICE_ACCOUNT_JSON"],
+            ),
+            add_python="3.11",
+        )
+        ```
+        """
+        ...
+
     @staticmethod
     def from_aws_ecr(
         tag: str,
@@ -287,7 +714,32 @@ class _Image(modal._object._Object):
         force_build: bool = False,
         add_python: typing.Optional[str] = None,
         **kwargs,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Build a Modal image from a private image in AWS Elastic Container Registry (ECR).
+
+        You will need to pass a `modal.Secret` containing `AWS_ACCESS_KEY_ID`,
+        `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` to access the target ECR registry.
+
+        IAM configuration details can be found in the AWS documentation for
+        ["Private repository policies"](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html).
+
+        See `Image.from_registry()` for information about the other parameters.
+
+        **Example**
+
+        ```python
+        modal.Image.from_aws_ecr(
+            "000000000000.dkr.ecr.us-east-1.amazonaws.com/my-private-registry:my-version",
+            secret=modal.Secret.from_name(
+                "aws",
+                required_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+            ),
+            add_python="3.11",
+        )
+        ```
+        """
+        ...
+
     @staticmethod
     def from_dockerfile(
         path: typing.Union[str, pathlib.Path],
@@ -301,16 +753,80 @@ class _Image(modal._object._Object):
         ignore: typing.Union[
             collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]
         ] = modal.image.AUTO_DOCKERIGNORE,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Build a Modal image from a local Dockerfile.
+
+        If your Dockerfile does not have Python installed, you can use the `add_python` parameter
+        to specify a version of Python to add to the image.
+
+        **Usage:**
+
+        ```python
+        from modal import FilePatternMatcher
+
+        # By default a .dockerignore file is used if present in the current working directory
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+        )
+
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=["*.venv"],
+        )
+
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=lambda p: p.is_relative_to(".venv"),
+        )
+
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=FilePatternMatcher("**/*.txt"),
+        )
+
+        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=~FilePatternMatcher("**/*.py"),
+        )
+
+        # You can also read ignore patterns from a file.
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=FilePatternMatcher.from_file("/path/to/dockerignore"),
+        )
+        ```
+        """
+        ...
+
     @staticmethod
-    def debian_slim(python_version: typing.Optional[str] = None, force_build: bool = False) -> _Image: ...
+    def debian_slim(python_version: typing.Optional[str] = None, force_build: bool = False) -> _Image:
+        """Default image, based on the official `python` Docker images."""
+        ...
+
     def apt_install(
         self,
         *packages: typing.Union[str, list[str]],
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret._Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> _Image: ...
+    ) -> _Image:
+        """Install a list of Debian packages using `apt`.
+
+        **Example**
+
+        ```python
+        image = modal.Image.debian_slim().apt_install("git")
+        ```
+        """
+        ...
+
     def run_function(
         self,
         raw_f: collections.abc.Callable[..., typing.Any],
@@ -333,16 +849,109 @@ class _Image(modal._object._Object):
         args: collections.abc.Sequence[typing.Any] = (),
         kwargs: dict[str, typing.Any] = {},
         include_source: typing.Optional[bool] = None,
-    ) -> _Image: ...
-    def env(self, vars: dict[str, str]) -> _Image: ...
-    def workdir(self, path: typing.Union[str, pathlib.PurePosixPath]) -> _Image: ...
-    def cmd(self, cmd: list[str]) -> _Image: ...
-    def imports(self): ...
-    def _logs(self) -> typing.AsyncGenerator[str, None]: ...
+    ) -> _Image:
+        """Run user-defined function `raw_f` as an image build step. The function runs just like an ordinary Modal
+        function, and any kwargs accepted by `@app.function` (such as `Mount`s, `NetworkFileSystem`s,
+        and resource requests) can be supplied to it.
+        After it finishes execution, a snapshot of the resulting container file system is saved as an image.
+
+        **Note**
+
+        Only the source code of `raw_f`, the contents of `**kwargs`, and any referenced *global* variables
+        are used to determine whether the image has changed and needs to be rebuilt.
+        If this function references other functions or variables, the image will not be rebuilt if you
+        make changes to them. You can force a rebuild by changing the function's source code itself.
+
+        **Example**
+
+        ```python notest
+
+        def my_build_function():
+            open("model.pt", "w").write("parameters!")
+
+        image = (
+            modal.Image
+                .debian_slim()
+                .pip_install("torch")
+                .run_function(my_build_function, secrets=[...], mounts=[...])
+        )
+        ```
+        """
+        ...
+
+    def env(self, vars: dict[str, str]) -> _Image:
+        """Sets the environment variables in an Image.
+
+        **Example**
+
+        ```python
+        image = (
+            modal.Image.debian_slim()
+            .env({"HF_HUB_ENABLE_HF_TRANSFER": "1"})
+        )
+        ```
+        """
+        ...
+
+    def workdir(self, path: typing.Union[str, pathlib.PurePosixPath]) -> _Image:
+        """Set the working directory for subsequent image build steps and function execution.
+
+        **Example**
+
+        ```python
+        image = (
+            modal.Image.debian_slim()
+            .run_commands("git clone https://xyz app")
+            .workdir("/app")
+            .run_commands("yarn install")
+        )
+        ```
+        """
+        ...
+
+    def cmd(self, cmd: list[str]) -> _Image:
+        """Set the default entrypoint argument (`CMD`) for the image.
+
+        **Example**
+
+        ```python
+        image = (
+            modal.Image.debian_slim().cmd(["python", "app.py"])
+        )
+        ```
+        """
+        ...
+
+    def imports(self):
+        """Used to import packages in global scope that are only available when running remotely.
+        By using this context manager you can avoid an `ImportError` due to not having certain
+        packages installed locally.
+
+        **Usage:**
+
+        ```python notest
+        with image.imports():
+            import torch
+        ```
+        """
+        ...
+
+    def _logs(self) -> typing.AsyncGenerator[str, None]:
+        """Streams logs from an image, or returns logs from an already completed image.
+
+        This method is considered private since its interface may change - use it at your own risk!
+        """
+        ...
 
 SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 
 class Image(modal.object.Object):
+    """Base class for container images to run functions in.
+
+    Do not construct this class directly; instead use one of its static factory methods,
+    such as `modal.Image.debian_slim`, `modal.Image.from_registry`, or `modal.Image.micromamba`.
+    """
+
     force_build: bool
     inside_exceptions: list[Exception]
     _serve_mounts: frozenset[modal.mount.Mount]
@@ -350,14 +959,28 @@ class Image(modal.object.Object):
     _added_python_source_set: frozenset[str]
     _metadata: typing.Optional[modal_proto.api_pb2.ImageMetadata]
 
-    def __init__(self, *args, **kwargs): ...
+    def __init__(self, *args, **kwargs):
+        """mdmd:hidden"""
+        ...
+
     def _initialize_from_empty(self): ...
     def _initialize_from_other(self, other: Image): ...
     def _get_metadata(self) -> typing.Optional[google.protobuf.message.Message]: ...
     def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
     def _add_mount_layer_or_copy(self, mount: modal.mount.Mount, copy: bool = False): ...
     @property
-    def _mount_layers(self) -> typing.Sequence[modal.mount.Mount]: ...
+    def _mount_layers(self) -> typing.Sequence[modal.mount.Mount]:
+        """Non-evaluated mount layers on the image
+
+        When the image is used by a Modal container, these mounts need to be attached as well to
+        represent the full image content, as they haven't yet been represented as a layer in the
+        image.
+
+        When the image is used as a base image for a new layer (that is not itself a mount layer)
+        these mounts need to first be inserted as a copy operation (.copy_mount) into the image.
+        """
+        ...
+
     def _assert_no_mount_layers(self): ...
     @staticmethod
     def _from_args(
@@ -378,10 +1001,31 @@ class Image(modal.object.Object):
         _namespace: int = 1,
         _do_assert_no_mount_layers: bool = True,
     ): ...
-    def _copy_mount(self, mount: modal.mount.Mount, remote_path: typing.Union[str, pathlib.Path] = ".") -> Image: ...
+    def _copy_mount(self, mount: modal.mount.Mount, remote_path: typing.Union[str, pathlib.Path] = ".") -> Image:
+        """mdmd:hidden
+        Internal
+        """
+        ...
+
     def add_local_file(
         self, local_path: typing.Union[str, pathlib.Path], remote_path: str, *, copy: bool = False
-    ) -> Image: ...
+    ) -> Image:
+        """Adds a local file to the image at `remote_path` within the container
+
+        By default (`copy=False`), the files are added to containers on startup and are not built into the actual Image,
+        which speeds up deployment.
+
+        Set `copy=True` to copy the files into an Image layer at build time instead, similar to how
+        [`COPY`](https://docs.docker.com/engine/reference/builder/#copy) works in a `Dockerfile`.
+
+        copy=True can slow down iteration since it requires a rebuild of the Image and any subsequent
+        build steps whenever the included files change, but it is required if you want to run additional
+        build steps after this one.
+
+        *Added in v0.66.40*: This method replaces the deprecated `modal.Image.copy_local_file` method.
+        """
+        ...
+
     def add_local_dir(
         self,
         local_path: typing.Union[str, pathlib.Path],
@@ -389,10 +1033,72 @@ class Image(modal.object.Object):
         *,
         copy: bool = False,
         ignore: typing.Union[collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]] = [],
-    ) -> Image: ...
+    ) -> Image:
+        """Adds a local directory's content to the image at `remote_path` within the container
+
+        By default (`copy=False`), the files are added to containers on startup and are not built into the actual Image,
+        which speeds up deployment.
+
+        Set `copy=True` to copy the files into an Image layer at build time instead, similar to how
+        [`COPY`](https://docs.docker.com/engine/reference/builder/#copy) works in a `Dockerfile`.
+
+        copy=True can slow down iteration since it requires a rebuild of the Image and any subsequent
+        build steps whenever the included files change, but it is required if you want to run additional
+        build steps after this one.
+
+        **Usage:**
+
+        ```python
+        from modal import FilePatternMatcher
+
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=["*.venv"],
+        )
+
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=lambda p: p.is_relative_to(".venv"),
+        )
+
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=FilePatternMatcher("**/*.txt"),
+        )
+
+        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=~FilePatternMatcher("**/*.py"),
+        )
+
+        # You can also read ignore patterns from a file.
+        image = modal.Image.debian_slim().add_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=FilePatternMatcher.from_file("/path/to/ignorefile"),
+        )
+        ```
+
+        *Added in v0.66.40*: This method replaces the deprecated `modal.Image.copy_local_dir` method.
+        """
+        ...
+
     def copy_local_file(
         self, local_path: typing.Union[str, pathlib.Path], remote_path: typing.Union[str, pathlib.Path] = "./"
-    ) -> Image: ...
+    ) -> Image:
+        """mdmd:hidden
+        Copy a file into the image as a part of building it.
+
+        This works in a similar way to [`COPY`](https://docs.docker.com/engine/reference/builder/#copy)
+        works in a `Dockerfile`.
+        """
+        ...
+
     def add_local_python_source(
         self,
         *module_names: str,
@@ -400,17 +1106,112 @@ class Image(modal.object.Object):
         ignore: typing.Union[
             collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]
         ] = modal.file_pattern_matcher.NON_PYTHON_FILES,
-    ) -> Image: ...
+    ) -> Image:
+        """Adds locally available Python packages/modules to containers
+
+        Adds all files from the specified Python package or module to containers running the Image.
+
+        Packages are added to the `/root` directory of containers, which is on the `PYTHONPATH`
+        of any executed Modal Functions, enabling import of the module by that name.
+
+        By default (`copy=False`), the files are added to containers on startup and are not built into the actual Image,
+        which speeds up deployment.
+
+        Set `copy=True` to copy the files into an Image layer at build time instead. This can slow down iteration since
+        it requires a rebuild of the Image and any subsequent build steps whenever the included files change, but it is
+        required if you want to run additional build steps after this one.
+
+        **Note:** This excludes all dot-prefixed subdirectories or files and all `.pyc`/`__pycache__` files.
+        To add full directories with finer control, use `.add_local_dir()` instead and specify `/root` as
+        the destination directory.
+
+        By default only includes `.py`-files in the source modules. Set the `ignore` argument to a list of patterns
+        or a callable to override this behavior, e.g.:
+
+        ```py
+        # includes everything except data.json
+        modal.Image.debian_slim().add_local_python_source("mymodule", ignore=["data.json"])
+
+        # exclude large files
+        modal.Image.debian_slim().add_local_python_source(
+            "mymodule",
+            ignore=lambda p: p.stat().st_size > 1e9
+        )
+        ```
+
+        *Added in v0.67.28*: This method replaces the deprecated `modal.Mount.from_local_python_packages` pattern.
+        """
+        ...
+
     def copy_local_dir(
         self,
         local_path: typing.Union[str, pathlib.Path],
         remote_path: typing.Union[str, pathlib.Path] = ".",
         ignore: typing.Union[collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]] = [],
-    ) -> Image: ...
+    ) -> Image:
+        """mdmd:hidden
+        **Deprecated**: Use image.add_local_dir instead
+
+        Copy a directory into the image as a part of building the image.
+
+        This works in a similar way to [`COPY`](https://docs.docker.com/engine/reference/builder/#copy)
+        works in a `Dockerfile`.
+
+        **Usage:**
+
+        ```python notest
+        from pathlib import Path
+        from modal import FilePatternMatcher
+
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=["**/*.venv"],
+        )
+
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=lambda p: p.is_relative_to(".venv"),
+        )
+
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=FilePatternMatcher("**/*.txt"),
+        )
+
+        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=~FilePatternMatcher("**/*.py"),
+        )
+
+        # You can also read ignore patterns from a file.
+        image = modal.Image.debian_slim().copy_local_dir(
+            "~/assets",
+            remote_path="/assets",
+            ignore=FilePatternMatcher.from_file("/path/to/ignorefile"),
+        )
+        ```
+        """
+        ...
 
     class __from_id_spec(typing_extensions.Protocol):
-        def __call__(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None) -> Image: ...
-        async def aio(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None) -> Image: ...
+        def __call__(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None) -> Image:
+            """Construct an Image from an id and look up the Image result.
+
+            The ID of an Image object can be accessed using `.object_id`.
+            """
+            ...
+
+        async def aio(self, /, image_id: str, client: typing.Optional[modal.client.Client] = None) -> Image:
+            """Construct an Image from an id and look up the Image result.
+
+            The ID of an Image object can be accessed using `.object_id`.
+            """
+            ...
 
     from_id: __from_id_spec
 
@@ -425,7 +1226,36 @@ class Image(modal.object.Object):
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret.Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> Image: ...
+    ) -> Image:
+        """Install a list of Python packages using pip.
+
+        **Examples**
+
+        Simple installation:
+        ```python
+        image = modal.Image.debian_slim().pip_install("click", "httpx~=0.23.3")
+        ```
+
+        More complex installation:
+        ```python
+        image = (
+            modal.Image.from_registry(
+                "nvidia/cuda:12.2.0-devel-ubuntu22.04", add_python="3.11"
+            )
+            .pip_install(
+                "ninja",
+                "packaging",
+                "wheel",
+                "transformers==4.40.2",
+            )
+            .pip_install(
+                "flash-attn==2.5.8", extra_options="--no-build-isolation"
+            )
+        )
+        ```
+        """
+        ...
+
     def pip_install_private_repos(
         self,
         *repositories: str,
@@ -438,7 +1268,39 @@ class Image(modal.object.Object):
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         secrets: collections.abc.Sequence[modal.secret.Secret] = [],
         force_build: bool = False,
-    ) -> Image: ...
+    ) -> Image:
+        """Install a list of Python packages from private git repositories using pip.
+
+        This method currently supports Github and Gitlab only.
+
+        - **Github:** Provide a `modal.Secret` that contains a `GITHUB_TOKEN` key-value pair
+        - **Gitlab:** Provide a `modal.Secret` that contains a `GITLAB_TOKEN` key-value pair
+
+        These API tokens should have permissions to read the list of private repositories provided as arguments.
+
+        We recommend using Github's ['fine-grained' access tokens](https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/).
+        These tokens are repo-scoped, and avoid granting read permission across all of a user's private repos.
+
+        **Example**
+
+        ```python
+        image = (
+            modal.Image
+            .debian_slim()
+            .pip_install_private_repos(
+                "github.com/ecorp/private-one@1.0.0",
+                "github.com/ecorp/private-two@main"
+                "github.com/ecorp/private-three@d4776502"
+                # install from 'inner' directory on default branch.
+                "github.com/ecorp/private-four#subdirectory=inner",
+                git_user="erikbern",
+                secrets=[modal.Secret.from_name("github-read-private")],
+            )
+        )
+        ```
+        """
+        ...
+
     def pip_install_from_requirements(
         self,
         requirements_txt: str,
@@ -451,7 +1313,10 @@ class Image(modal.object.Object):
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret.Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> Image: ...
+    ) -> Image:
+        """Install a list of Python packages from a local `requirements.txt` file."""
+        ...
+
     def pip_install_from_pyproject(
         self,
         pyproject_toml: str,
@@ -465,7 +1330,16 @@ class Image(modal.object.Object):
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret.Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> Image: ...
+    ) -> Image:
+        """Install dependencies specified by a local `pyproject.toml` file.
+
+        `optional_dependencies` is a list of the keys of the
+        optional-dependencies section(s) of the `pyproject.toml` file
+        (e.g. test, doc, experiment, etc). When provided,
+        all of the packages in each listed section are installed as well.
+        """
+        ...
+
     def poetry_install_from_file(
         self,
         poetry_pyproject_toml: str,
@@ -479,7 +1353,17 @@ class Image(modal.object.Object):
         only: list[str] = [],
         secrets: collections.abc.Sequence[modal.secret.Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> Image: ...
+    ) -> Image:
+        """Install poetry *dependencies* specified by a local `pyproject.toml` file.
+
+        If not provided as argument the path to the lockfile is inferred. However, the
+        file has to exist, unless `ignore_lockfile` is set to `True`.
+
+        Note that the root project of the poetry project is not installed, only the dependencies.
+        For including local python source files see `add_local_python_source`
+        """
+        ...
+
     def dockerfile_commands(
         self,
         *dockerfile_commands: typing.Union[str, list[str]],
@@ -492,18 +1376,72 @@ class Image(modal.object.Object):
         ignore: typing.Union[
             collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]
         ] = modal.image.AUTO_DOCKERIGNORE,
-    ) -> Image: ...
-    def entrypoint(self, entrypoint_commands: list[str]) -> Image: ...
-    def shell(self, shell_commands: list[str]) -> Image: ...
+    ) -> Image:
+        """Extend an image with arbitrary Dockerfile-like commands.
+
+        **Usage:**
+
+        ```python
+        from modal import FilePatternMatcher
+
+        # By default a .dockerignore file is used if present in the current working directory
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+        )
+
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=["*.venv"],
+        )
+
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=lambda p: p.is_relative_to(".venv"),
+        )
+
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=FilePatternMatcher("**/*.txt"),
+        )
+
+        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=~FilePatternMatcher("**/*.py"),
+        )
+
+        # You can also read ignore patterns from a file.
+        image = modal.Image.debian_slim().dockerfile_commands(
+            ["COPY data /data"],
+            ignore=FilePatternMatcher.from_file("/path/to/dockerignore"),
+        )
+        ```
+        """
+        ...
+
+    def entrypoint(self, entrypoint_commands: list[str]) -> Image:
+        """Set the entrypoint for the image."""
+        ...
+
+    def shell(self, shell_commands: list[str]) -> Image:
+        """Overwrite default shell for the image."""
+        ...
+
     def run_commands(
         self,
         *commands: typing.Union[str, list[str]],
         secrets: collections.abc.Sequence[modal.secret.Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
         force_build: bool = False,
-    ) -> Image: ...
+    ) -> Image:
+        """Extend an image with a list of shell commands to run."""
+        ...
+
     @staticmethod
-    def micromamba(python_version: typing.Optional[str] = None, force_build: bool = False) -> Image: ...
+    def micromamba(python_version: typing.Optional[str] = None, force_build: bool = False) -> Image:
+        """A Micromamba base image. Micromamba allows for fast building of small Conda-based containers."""
+        ...
+
     def micromamba_install(
         self,
         *packages: typing.Union[str, list[str]],
@@ -512,7 +1450,10 @@ class Image(modal.object.Object):
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret.Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> Image: ...
+    ) -> Image:
+        """Install a list of additional packages using micromamba."""
+        ...
+
     @staticmethod
     def _registry_setup_commands(
         tag: str,
@@ -529,7 +1470,36 @@ class Image(modal.object.Object):
         force_build: bool = False,
         add_python: typing.Optional[str] = None,
         **kwargs,
-    ) -> Image: ...
+    ) -> Image:
+        """Build a Modal Image from a public or private image registry, such as Docker Hub.
+
+        The image must be built for the `linux/amd64` platform.
+
+        If your image does not come with Python installed, you can use the `add_python` parameter
+        to specify a version of Python to add to the image. Otherwise, the image is expected to
+        have Python on PATH as `python`, along with `pip`.
+
+        You may also use `setup_dockerfile_commands` to run Dockerfile commands before the
+        remaining commands run. This might be useful if you want a custom Python installation or to
+        set a `SHELL`. Prefer `run_commands()` when possible though.
+
+        To authenticate against a private registry with static credentials, you must set the `secret` parameter to
+        a `modal.Secret` containing a username (`REGISTRY_USERNAME`) and
+        an access token or password (`REGISTRY_PASSWORD`).
+
+        To authenticate against private registries with credentials from a cloud provider,
+        use `Image.from_gcp_artifact_registry()` or `Image.from_aws_ecr()`.
+
+        **Examples**
+
+        ```python
+        modal.Image.from_registry("python:3.11-slim-bookworm")
+        modal.Image.from_registry("ubuntu:22.04", add_python="3.11")
+        modal.Image.from_registry("nvcr.io/nvidia/pytorch:22.12-py3")
+        ```
+        """
+        ...
+
     @staticmethod
     def from_gcp_artifact_registry(
         tag: str,
@@ -539,7 +1509,38 @@ class Image(modal.object.Object):
         force_build: bool = False,
         add_python: typing.Optional[str] = None,
         **kwargs,
-    ) -> Image: ...
+    ) -> Image:
+        """Build a Modal image from a private image in Google Cloud Platform (GCP) Artifact Registry.
+
+        You will need to pass a `modal.Secret` containing [your GCP service account key data](https://cloud.google.com/iam/docs/keys-create-delete#creating)
+        as `SERVICE_ACCOUNT_JSON`. This can be done from the [Secrets](https://modal.com/secrets) page.
+        Your service account should be granted a specific role depending on the GCP registry used:
+
+        - For Artifact Registry images (`pkg.dev` domains) use
+          the ["Artifact Registry Reader"](https://cloud.google.com/artifact-registry/docs/access-control#roles) role
+        - For Container Registry images (`gcr.io` domains) use
+          the ["Storage Object Viewer"](https://cloud.google.com/artifact-registry/docs/transition/setup-gcr-repo) role
+
+        **Note:** This method does not use `GOOGLE_APPLICATION_CREDENTIALS` as that
+        variable accepts a path to a JSON file, not the actual JSON string.
+
+        See `Image.from_registry()` for information about the other parameters.
+
+        **Example**
+
+        ```python
+        modal.Image.from_gcp_artifact_registry(
+            "us-east1-docker.pkg.dev/my-project-1234/my-repo/my-image:my-version",
+            secret=modal.Secret.from_name(
+                "my-gcp-secret",
+                required_keys=["SERVICE_ACCOUNT_JSON"],
+            ),
+            add_python="3.11",
+        )
+        ```
+        """
+        ...
+
     @staticmethod
     def from_aws_ecr(
         tag: str,
@@ -549,7 +1550,32 @@ class Image(modal.object.Object):
         force_build: bool = False,
         add_python: typing.Optional[str] = None,
         **kwargs,
-    ) -> Image: ...
+    ) -> Image:
+        """Build a Modal image from a private image in AWS Elastic Container Registry (ECR).
+
+        You will need to pass a `modal.Secret` containing `AWS_ACCESS_KEY_ID`,
+        `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` to access the target ECR registry.
+
+        IAM configuration details can be found in the AWS documentation for
+        ["Private repository policies"](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html).
+
+        See `Image.from_registry()` for information about the other parameters.
+
+        **Example**
+
+        ```python
+        modal.Image.from_aws_ecr(
+            "000000000000.dkr.ecr.us-east-1.amazonaws.com/my-private-registry:my-version",
+            secret=modal.Secret.from_name(
+                "aws",
+                required_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION"],
+            ),
+            add_python="3.11",
+        )
+        ```
+        """
+        ...
+
     @staticmethod
     def from_dockerfile(
         path: typing.Union[str, pathlib.Path],
@@ -563,16 +1589,80 @@ class Image(modal.object.Object):
         ignore: typing.Union[
             collections.abc.Sequence[str], collections.abc.Callable[[pathlib.Path], bool]
         ] = modal.image.AUTO_DOCKERIGNORE,
-    ) -> Image: ...
+    ) -> Image:
+        """Build a Modal image from a local Dockerfile.
+
+        If your Dockerfile does not have Python installed, you can use the `add_python` parameter
+        to specify a version of Python to add to the image.
+
+        **Usage:**
+
+        ```python
+        from modal import FilePatternMatcher
+
+        # By default a .dockerignore file is used if present in the current working directory
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+        )
+
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=["*.venv"],
+        )
+
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=lambda p: p.is_relative_to(".venv"),
+        )
+
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=FilePatternMatcher("**/*.txt"),
+        )
+
+        # When including files is simpler than excluding them, you can use the `~` operator to invert the matcher.
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=~FilePatternMatcher("**/*.py"),
+        )
+
+        # You can also read ignore patterns from a file.
+        image = modal.Image.from_dockerfile(
+            "./Dockerfile",
+            add_python="3.12",
+            ignore=FilePatternMatcher.from_file("/path/to/dockerignore"),
+        )
+        ```
+        """
+        ...
+
     @staticmethod
-    def debian_slim(python_version: typing.Optional[str] = None, force_build: bool = False) -> Image: ...
+    def debian_slim(python_version: typing.Optional[str] = None, force_build: bool = False) -> Image:
+        """Default image, based on the official `python` Docker images."""
+        ...
+
     def apt_install(
         self,
         *packages: typing.Union[str, list[str]],
         force_build: bool = False,
         secrets: collections.abc.Sequence[modal.secret.Secret] = [],
         gpu: typing.Union[None, str, modal.gpu._GPUConfig] = None,
-    ) -> Image: ...
+    ) -> Image:
+        """Install a list of Debian packages using `apt`.
+
+        **Example**
+
+        ```python
+        image = modal.Image.debian_slim().apt_install("git")
+        ```
+        """
+        ...
+
     def run_function(
         self,
         raw_f: collections.abc.Callable[..., typing.Any],
@@ -595,15 +1685,107 @@ class Image(modal.object.Object):
         args: collections.abc.Sequence[typing.Any] = (),
         kwargs: dict[str, typing.Any] = {},
         include_source: typing.Optional[bool] = None,
-    ) -> Image: ...
-    def env(self, vars: dict[str, str]) -> Image: ...
-    def workdir(self, path: typing.Union[str, pathlib.PurePosixPath]) -> Image: ...
-    def cmd(self, cmd: list[str]) -> Image: ...
-    def imports(self): ...
+    ) -> Image:
+        """Run user-defined function `raw_f` as an image build step. The function runs just like an ordinary Modal
+        function, and any kwargs accepted by `@app.function` (such as `Mount`s, `NetworkFileSystem`s,
+        and resource requests) can be supplied to it.
+        After it finishes execution, a snapshot of the resulting container file system is saved as an image.
+
+        **Note**
+
+        Only the source code of `raw_f`, the contents of `**kwargs`, and any referenced *global* variables
+        are used to determine whether the image has changed and needs to be rebuilt.
+        If this function references other functions or variables, the image will not be rebuilt if you
+        make changes to them. You can force a rebuild by changing the function's source code itself.
+
+        **Example**
+
+        ```python notest
+
+        def my_build_function():
+            open("model.pt", "w").write("parameters!")
+
+        image = (
+            modal.Image
+                .debian_slim()
+                .pip_install("torch")
+                .run_function(my_build_function, secrets=[...], mounts=[...])
+        )
+        ```
+        """
+        ...
+
+    def env(self, vars: dict[str, str]) -> Image:
+        """Sets the environment variables in an Image.
+
+        **Example**
+
+        ```python
+        image = (
+            modal.Image.debian_slim()
+            .env({"HF_HUB_ENABLE_HF_TRANSFER": "1"})
+        )
+        ```
+        """
+        ...
+
+    def workdir(self, path: typing.Union[str, pathlib.PurePosixPath]) -> Image:
+        """Set the working directory for subsequent image build steps and function execution.
+
+        **Example**
+
+        ```python
+        image = (
+            modal.Image.debian_slim()
+            .run_commands("git clone https://xyz app")
+            .workdir("/app")
+            .run_commands("yarn install")
+        )
+        ```
+        """
+        ...
+
+    def cmd(self, cmd: list[str]) -> Image:
+        """Set the default entrypoint argument (`CMD`) for the image.
+
+        **Example**
+
+        ```python
+        image = (
+            modal.Image.debian_slim().cmd(["python", "app.py"])
+        )
+        ```
+        """
+        ...
+
+    def imports(self):
+        """Used to import packages in global scope that are only available when running remotely.
+        By using this context manager you can avoid an `ImportError` due to not having certain
+        packages installed locally.
+
+        **Usage:**
+
+        ```python notest
+        with image.imports():
+            import torch
+        ```
+        """
+        ...
 
     class ___logs_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /) -> typing.Generator[str, None, None]: ...
-        def aio(self, /) -> typing.AsyncGenerator[str, None]: ...
+        def __call__(self, /) -> typing.Generator[str, None, None]:
+            """Streams logs from an image, or returns logs from an already completed image.
+
+            This method is considered private since its interface may change - use it at your own risk!
+            """
+            ...
+
+        def aio(self, /) -> typing.AsyncGenerator[str, None]:
+            """Streams logs from an image, or returns logs from an already completed image.
+
+            This method is considered private since its interface may change - use it at your own risk!
+            """
+            ...
 
     _logs: ___logs_spec[typing_extensions.Self]