flyte 2.0.0b22__py3-none-any.whl → 2.0.0b23__py3-none-any.whl

flyte/_deploy.py

@@ -2,10 +2,8 @@ from __future__ import annotations
 
 import asyncio
 import hashlib
-import sys
-import typing
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Dict, List, Optional, Protocol, Set, Tuple, Type
 
 import cloudpickle
 import rich.repr
@@ -22,7 +20,7 @@ from ._task import TaskTemplate
 from ._task_environment import TaskEnvironment
 
 if TYPE_CHECKING:
-    from flyte._protos.workflow import task_definition_pb2
+    from flyte._protos.workflow import task_definition_pb2, trigger_definition_pb2
 
     from ._code_bundle import CopyFiles
     from ._internal.imagebuild.image_builder import ImageCache
@@ -37,53 +35,110 @@ class DeploymentPlan:
 
 @rich.repr.auto
 @dataclass
+class DeploymentContext:
+    """
+    Context for deployment operations.
+    """
+
+    environment: Environment | TaskEnvironment
+    serialization_context: SerializationContext
+    dryrun: bool = False
+
+
+@rich.repr.auto
+@dataclass
+class DeployedTask:
+    deployed_task: task_definition_pb2.TaskSpec
+    deployed_triggers: List[trigger_definition_pb2.TaskTrigger]
+
+    def summary_repr(self) -> str:
+        """
+        Returns a summary representation of the deployed task.
+        """
+        return (
+            f"DeployedTask(name={self.deployed_task.task_template.id.name}, "
+            f"version={self.deployed_task.task_template.id.version})"
+        )
+
+    def table_repr(self) -> List[Tuple[str, ...]]:
+        """
+        Returns a table representation of the deployed task.
+        """
+        return [
+            ("name", self.deployed_task.task_template.id.name),
+            ("version", self.deployed_task.task_template.id.version),
+            ("triggers", ",".join([t.name for t in self.deployed_triggers])),
+        ]
+
+
+@rich.repr.auto
+@dataclass
+class DeployedEnv:
+    env: Environment
+    deployed_entities: List[DeployedTask]
+
+    def summary_repr(self) -> str:
+        """
+        Returns a summary representation of the deployment.
+        """
+        entities = ", ".join(f"{e.summary_repr()}" for e in self.deployed_entities or [])
+        return f"Deployment(env=[{self.env.name}], entities=[{entities}])"
+
+    def table_repr(self) -> List[List[Tuple[str, ...]]]:
+        """
+        Returns a detailed representation of the deployed tasks.
+        """
+        tuples = []
+        if self.deployed_entities:
+            for e in self.deployed_entities:
+                tuples.append(e.table_repr())
+        return tuples
+
+    def env_repr(self) -> List[Tuple[str, ...]]:
+        """
+        Returns a detailed representation of the deployed environments.
+        """
+        env = self.env
+        return [
+            ("environment", env.name),
+            ("image", env.image.uri if isinstance(env.image, Image) else env.image or ""),
+        ]
+
+
+@rich.repr.auto
+@dataclass(frozen=True)
 class Deployment:
-    envs: Dict[str, Environment]
-    deployed_tasks: List[task_definition_pb2.TaskSpec] | None = None
+    envs: Dict[str, DeployedEnv]
 
     def summary_repr(self) -> str:
         """
         Returns a summary representation of the deployment.
         """
-        env_names = ", ".join(self.envs.keys())
-        task_names_versions = ", ".join(
-            f"{task.task_template.id.name} (v{task.task_template.id.version})" for task in self.deployed_tasks or []
-        )
-        return f"Deployment(envs=[{env_names}], tasks=[{task_names_versions}])"
+        envs = ", ".join(f"{e.summary_repr()}" for e in self.envs.values() or [])
+        return f"Deployment(envs=[{envs}])"
 
-    def task_repr(self) -> List[List[Tuple[str, str]]]:
+    def table_repr(self) -> List[List[Tuple[str, ...]]]:
         """
         Returns a detailed representation of the deployed tasks.
         """
         tuples = []
-        if self.deployed_tasks:
-            for task in self.deployed_tasks:
-                tuples.append(
-                    [
-                        ("name", task.task_template.id.name),
-                        ("version", task.task_template.id.version),
-                    ]
-                )
+        for d in self.envs.values():
+            tuples.extend(d.table_repr())
         return tuples
 
-    def env_repr(self) -> List[List[Tuple[str, str]]]:
+    def env_repr(self) -> List[List[Tuple[str, ...]]]:
         """
         Returns a detailed representation of the deployed environments.
         """
         tuples = []
-        for env_name, env in self.envs.items():
-            tuples.append(
-                [
-                    ("environment", env_name),
-                    ("image", env.image.uri if isinstance(env.image, Image) else env.image or ""),
-                ]
-            )
+        for d in self.envs.values():
+            tuples.append(d.env_repr())
         return tuples
 
 
 async def _deploy_task(
     task: TaskTemplate, serialization_context: SerializationContext, dryrun: bool = False
-) -> task_definition_pb2.TaskSpec:
+) -> DeployedTask:
     """
     Deploy the given task.
     """
@@ -92,13 +147,14 @@ async def _deploy_task(
 
     from ._internal.runtime.convert import convert_upload_default_inputs
     from ._internal.runtime.task_serde import translate_task_to_wire
+    from ._internal.runtime.trigger_serde import to_task_trigger
     from ._protos.workflow import task_definition_pb2, task_service_pb2
 
     image_uri = task.image.uri if isinstance(task.image, Image) else task.image
 
     try:
         if dryrun:
-            return translate_task_to_wire(task, serialization_context)
+            return DeployedTask(translate_task_to_wire(task, serialization_context), [])
 
         default_inputs = await convert_upload_default_inputs(task.interface)
         spec = translate_task_to_wire(task, serialization_context, default_inputs=default_inputs)
@@ -115,15 +171,31 @@ async def _deploy_task(
             name=spec.task_template.id.name,
         )
 
+        deployable_triggers_coros = []
+        for t in task.triggers:
+            inputs = spec.task_template.interface.inputs
+            default_inputs = spec.default_inputs
+            deployable_triggers_coros.append(
+                to_task_trigger(t=t, task_name=task.name, task_inputs=inputs, task_default_inputs=list(default_inputs))
+            )
+
+        deployable_triggers = await asyncio.gather(*deployable_triggers_coros)
         try:
-            await get_client().task_service.DeployTask(task_service_pb2.DeployTaskRequest(task_id=task_id, spec=spec))
+            await get_client().task_service.DeployTask(
+                task_service_pb2.DeployTaskRequest(
+                    task_id=task_id,
+                    spec=spec,
+                    triggers=deployable_triggers,
+                )
+            )
             logger.info(f"Deployed task {task.name} with version {task_id.version}")
         except grpc.aio.AioRpcError as e:
             if e.code() == grpc.StatusCode.ALREADY_EXISTS:
                 logger.info(f"Task {task.name} with image {image_uri} already exists, skipping deployment.")
-                return spec
+                return DeployedTask(spec, deployable_triggers)
             raise
-        return spec
+
+        return DeployedTask(spec, deployable_triggers)
     except Exception as e:
         logger.error(f"Failed to deploy task {task.name} with image {image_uri}: {e}")
         raise flyte.errors.DeploymentError(
@@ -162,16 +234,80 @@ async def _build_images(deployment: DeploymentPlan) -> ImageCache:
     for env_name, image_uri in final_images:
         logger.warning(f"Built Image for environment {env_name}, image: {image_uri}")
         env = deployment.envs[env_name]
-        if isinstance(env.image, Image):
-            py_version = "{}.{}".format(*env.image.python_version)
-            image_identifier_map[env.image.identifier] = {py_version: image_uri}
-        elif env.image == "auto":
-            py_version = "{}.{}".format(sys.version_info.major, sys.version_info.minor)
-            image_identifier_map["auto"] = {py_version: image_uri}
+        image_identifier_map[env_name] = image_uri
 
     return ImageCache(image_lookup=image_identifier_map)
 
 
+class Deployer(Protocol):
+    """
+    Protocol for deployment callables.
+    """
+
+    async def __call__(self, context: DeploymentContext) -> DeployedEnv:
+        """
+        Deploy the environment described in the context.
+
+        Args:
+            context: Deployment context containing environment, serialization context, and dryrun flag
+
+        Returns:
+            Deployment result
+        """
+        ...
+
+
+async def _deploy_task_env(context: DeploymentContext) -> DeployedEnv:
+    """
+    Deploy the given task environment.
+    """
+    ensure_client()
+    env = context.environment
+    if not isinstance(env, TaskEnvironment):
+        raise ValueError(f"Expected TaskEnvironment, got {type(env)}")
+
+    task_coros = []
+    for task in env.tasks.values():
+        task_coros.append(_deploy_task(task, context.serialization_context, dryrun=context.dryrun))
+    deployed_task_vals = await asyncio.gather(*task_coros)
+    deployed_tasks = []
+    for t in deployed_task_vals:
+        deployed_tasks.append(t)
+    return DeployedEnv(env=env, deployed_entities=deployed_tasks)
+
+
+_ENVTYPE_REGISTRY: Dict[Type[Environment | TaskEnvironment], Deployer] = {
+    TaskEnvironment: _deploy_task_env,
+}
+
+
+def register_deployer(env_type: Type[Environment | TaskEnvironment], deployer: Deployer) -> None:
+    """
+    Register a deployer for a specific environment type.
+
+    Args:
+        env_type: Type of environment this deployer handles
+        deployer: Deployment callable that conforms to the Deployer protocol
+    """
+    _ENVTYPE_REGISTRY[env_type] = deployer
+
+
+def get_deployer(env_type: Type[Environment | TaskEnvironment]) -> Deployer:
+    """
+    Get the registered deployer for an environment type.
+
+    Args:
+        env_type: Type of environment to get deployer for
+
+    Returns:
+        Deployer for the environment type, defaults to task environment deployer
+    """
+    v = _ENVTYPE_REGISTRY.get(env_type)
+    if v is None:
+        raise ValueError(f"No deployer registered for environment type {env_type}")
+    return v
+
+
 @requires_initialization
 async def apply(deployment_plan: DeploymentPlan, copy_style: CopyFiles, dryrun: bool = False) -> Deployment:
     from ._code_bundle import build_code_bundle
@@ -203,15 +339,18 @@ async def apply(deployment_plan: DeploymentPlan, copy_style: CopyFiles, dryrun:
         root_dir=cfg.root_dir,
     )
 
-    tasks = []
-
+    deployment_coros = []
     for env_name, env in deployment_plan.envs.items():
         logger.info(f"Deploying environment {env_name}")
-        # TODO Make this pluggable based on the environment type
-        if isinstance(env, TaskEnvironment):
-            for task in env.tasks.values():
-                tasks.append(_deploy_task(task, dryrun=dryrun, serialization_context=sc))
-    return Deployment(envs=deployment_plan.envs, deployed_tasks=await asyncio.gather(*tasks))
+        deployer = get_deployer(type(env))
+        context = DeploymentContext(environment=env, serialization_context=sc, dryrun=dryrun)
+        deployment_coros.append(deployer(context))
+    deployed_envs = await asyncio.gather(*deployment_coros)
+    envs = {}
+    for d in deployed_envs:
+        envs[d.env.name] = d
+
+    return Deployment(envs)
 
 
 def _recursive_discover(planned_envs: Dict[str, Environment], env: Environment) -> Dict[str, Environment]:
@@ -219,14 +358,16 @@ def _recursive_discover(planned_envs: Dict[str, Environment], env: Environment)
     Recursively deploy the environment and its dependencies, if not already deployed (present in env_tasks) and
     return the updated env_tasks.
     """
-    # Skip if the environment is already planned
     if env.name in planned_envs:
-        return planned_envs
+        if planned_envs[env.name] is not env:
+            # Raise error if different TaskEnvironment objects have the same name
+            raise ValueError(f"Duplicate environment name '{env.name}' found")
+    # Add the environment to the existing envs
+    planned_envs[env.name] = env
+
     # Recursively discover dependent environments
     for dependent_env in env.depends_on:
         _recursive_discover(planned_envs, dependent_env)
-    # Add the environment to the existing envs
-    planned_envs[env.name] = env
     return planned_envs
 
 
@@ -234,10 +375,10 @@ def plan_deploy(*envs: Environment, version: Optional[str] = None) -> List[Deplo
     if envs is None:
         return [DeploymentPlan({})]
     deployment_plans = []
-    visited_envs: typing.Set[str] = set()
+    visited_envs: Set[str] = set()
     for env in envs:
         if env.name in visited_envs:
-            continue
+            raise ValueError(f"Duplicate environment name '{env.name}' found")
         planned_envs = _recursive_discover({}, env)
         deployment_plans.append(DeploymentPlan(planned_envs, version=version))
         visited_envs.update(planned_envs.keys())

flyte/_environment.py

@@ -36,6 +36,9 @@ class Environment:
     :param resources: Resources to allocate for the environment.
     :param env_vars: Environment variables to set for the environment.
     :param secrets: Secrets to inject into the environment.
+    :param pod_template: Pod template to use for the environment.
+    :param description: Description of the environment.
+    :param interruptible: Whether the environment is interruptible and can be scheduled on spot/preemptible instances
     :param depends_on: Environment dependencies to hint, so when you deploy the environment, the dependencies are
         also deployed. This is useful when you have a set of environments that depend on each other.
     """
@@ -47,6 +50,7 @@ class Environment:
     secrets: Optional[SecretRequest] = None
     env_vars: Optional[Dict[str, str]] = None
     resources: Optional[Resources] = None
+    interruptible: bool = False
     image: Union[str, Image, Literal["auto"]] = "auto"
 
     def __post_init__(self):
@@ -87,6 +91,7 @@ class Environment:
         env_vars: Optional[Dict[str, str]] = None,
         secrets: Optional[SecretRequest] = None,
         depends_on: Optional[List[Environment]] = None,
+        description: Optional[str] = None,
         **kwargs: Any,
     ) -> Environment:
         raise NotImplementedError

flyte/_excepthook.py

@@ -33,5 +33,5 @@ def custom_excepthook(exc_type, exc_value, exc_tb):
         filtered_tb = [frame for frame in tb_list if should_include_frame(frame)]
         # Print the filtered version (custom format)
         print("Filtered traceback (most recent call last):")
-        print("".join(traceback.format_list(filtered_tb)))
+        traceback.print_tb(filtered_tb)
         print(f"{exc_type.__name__}: {exc_value}\n")

flyte/_image.py

@@ -1,11 +1,10 @@
 from __future__ import annotations
 
-import base64
 import hashlib
 import sys
 import typing
 from abc import abstractmethod
-from dataclasses import asdict, dataclass, field, fields
+from dataclasses import dataclass, field
 from functools import cached_property
 from pathlib import Path
 from typing import TYPE_CHECKING, ClassVar, Dict, List, Literal, Optional, Tuple, TypeVar, Union
@@ -13,6 +12,8 @@ from typing import TYPE_CHECKING, ClassVar, Dict, List, Literal, Optional, Tuple
 import rich.repr
 from packaging.version import Version
 
+from flyte._utils import update_hasher_for_source
+
 if TYPE_CHECKING:
     from flyte import Secret, SecretRequest
 
@@ -56,7 +57,6 @@ class Layer:
 
         :param hasher: The hash object to update with the layer's data.
         """
-        print("hash hash")
 
     def validate(self):
         """
@@ -64,27 +64,6 @@ class Layer:
         :return:
         """
 
-    def identifier(self) -> str:
-        """
-        This method computes a unique identifier for the layer based on its properties.
-        It is used to identify the layer in the image cache.
-
-        It is also used to compute a unique identifier for the image itself, which is a combination of all the layers.
-        This identifier is used to look up previously built images in the image cache. So having a consistent
-        identifier is important for the image cache to work correctly.
-
-        :return: A unique identifier for the layer.
-        """
-        ignore_fields: list[str] = []
-        for f in fields(self):
-            if f.metadata.get("identifier", True) is False:
-                ignore_fields.append(f.name)
-        d = asdict(self)
-        for v in ignore_fields:
-            d.pop(v)
-
-        return str(d)
-
 
 @rich.repr.auto
 @dataclass(kw_only=True, frozen=True, repr=True)
@@ -152,7 +131,7 @@ class PipPackages(PipOption, Layer):
 @rich.repr.auto
 @dataclass(kw_only=True, frozen=True, repr=True)
 class PythonWheels(PipOption, Layer):
-    wheel_dir: Path = field(metadata={"identifier": False})
+    wheel_dir: Path
     wheel_dir_name: str = field(init=False)
     package_name: str
 
@@ -202,14 +181,56 @@ class UVProject(PipOption, Layer):
         from ._utils import filehash_update
 
         super().update_hash(hasher)
-        filehash_update(self.uvlock, hasher)
-        filehash_update(self.pyproject, hasher)
+        if self.extra_args and "--no-install-project" in self.extra_args:
+            filehash_update(self.uvlock, hasher)
+            filehash_update(self.pyproject, hasher)
+        else:
+            update_hasher_for_source(self.pyproject.parent, hasher)
+
+
+@rich.repr.auto
+@dataclass(frozen=True, repr=True)
+class PoetryProject(Layer):
+    """
+    Poetry does not use pip options, so the PoetryProject class do not inherits PipOption class
+    """
+
+    pyproject: Path
+    poetry_lock: Path
+    extra_args: Optional[str] = None
+    secret_mounts: Optional[Tuple[str | Secret, ...]] = None
+
+    def validate(self):
+        if not self.pyproject.exists():
+            raise FileNotFoundError(f"pyproject.toml file {self.pyproject} does not exist")
+        if not self.pyproject.is_file():
+            raise ValueError(f"Pyproject file {self.pyproject} is not a file")
+        if not self.poetry_lock.exists():
+            raise ValueError(f"poetry.lock file {self.poetry_lock} does not exist")
+        super().validate()
+
+    def update_hash(self, hasher: hashlib._Hash):
+        from ._utils import filehash_update
+
+        hash_input = ""
+        if self.extra_args:
+            hash_input += self.extra_args
+        if self.secret_mounts:
+            for secret_mount in self.secret_mounts:
+                hash_input += str(secret_mount)
+        hasher.update(hash_input.encode("utf-8"))
+
+        if self.extra_args and "--no-root" in self.extra_args:
+            filehash_update(self.poetry_lock, hasher)
+            filehash_update(self.pyproject, hasher)
+        else:
+            update_hasher_for_source(self.pyproject.parent, hasher)
 
 
 @rich.repr.auto
 @dataclass(frozen=True, repr=True)
 class UVScript(PipOption, Layer):
-    script: Path = field(metadata={"identifier": False})
+    script: Path
     script_name: str = field(init=False)
 
     def __post_init__(self):
@@ -285,15 +306,14 @@ class DockerIgnore(Layer):
 @rich.repr.auto
 @dataclass(frozen=True, repr=True)
 class CopyConfig(Layer):
-    path_type: CopyConfigType = field(metadata={"identifier": True})
-    src: Path = field(metadata={"identifier": False})
+    path_type: CopyConfigType
+    src: Path
     dst: str
-    src_name: str = field(init=False)
+    src_name: str
 
     def __post_init__(self):
         if self.path_type not in (0, 1):
             raise ValueError(f"Invalid path_type {self.path_type}, must be 0 (file) or 1 (directory)")
-        object.__setattr__(self, "src_name", self.src.name)
 
     def validate(self):
         if not self.src.exists():
@@ -382,9 +402,6 @@ class Image:
     platform: Tuple[Architecture, ...] = field(default=("linux/amd64",))
     python_version: Tuple[int, int] = field(default_factory=_detect_python_version)
 
-    # For .auto() images. Don't compute an actual identifier.
-    _identifier_override: Optional[str] = field(default=None, init=False)
-
     # Layers to be added to the image. In init, because frozen, but users shouldn't access, so underscore.
     _layers: Tuple[Layer, ...] = field(default_factory=tuple)
 
@@ -417,34 +434,6 @@ class Image:
         cls.__init__(obj, **kwargs)  # run dataclass generated __init__
         return obj
 
-    @cached_property
-    def identifier(self) -> str:
-        """
-        This identifier is a hash of the layers and properties of the image. It is used to look up previously built
-        images. Why is this useful? For example, if a user has Image.from_uv_base().with_source_file("a/local/file"),
-        it's not necessarily the case that that file exists within the image (further commands may have removed/changed
-        it), and certainly not the case that the path to the file, inside the image (which is used as part of the layer
-        hash computation), is the same. That is, inside the image when a task runs, as we come across the same Image
-        declaration, we need a way of identifying the image and its uri, without hashing all the layers again. This
-        is what this identifier is for. See the ImageCache object for additional information.
-
-        :return: A unique identifier of the Image
-        """
-        if self._identifier_override:
-            return self._identifier_override
-
-        # Only get the non-None values in the Image to ensure the hash is consistent
-        # across different SDK versions.
-        # Layers can specify a _compute_identifier optionally, but the default will just stringify
-        image_dict = asdict(
-            self,
-            dict_factory=lambda x: {k: v for (k, v) in x if v is not None and k not in ("_layers", "python_version")},
-        )
-        layers_str_repr = "".join([layer.identifier() for layer in self._layers])
-        image_dict["layers"] = layers_str_repr
-        spec_bytes = image_dict.__str__().encode("utf-8")
-        return base64.urlsafe_b64encode(hashlib.md5(spec_bytes).digest()).decode("ascii").rstrip("=")
-
     def validate(self):
         for layer in self._layers:
             layer.validate()
@@ -507,9 +496,6 @@ class Image:
                     image = image.with_pip_packages(f"flyte=={flyte_version}")
         if not dev_mode:
             object.__setattr__(image, "_tag", preset_tag)
-        # Set this to auto for all auto images because the meaning of "auto" can change (based on logic inside
-        # _get_default_image_for, acts differently in a running task container) so let's make sure it stays auto.
-        object.__setattr__(image, "_identifier_override", "auto")
 
         return image
 
@@ -550,9 +536,6 @@ class Image:
         if registry or name:
             return base_image.clone(registry=registry, name=name)
 
-        # # Set this to auto for all auto images because the meaning of "auto" can change (based on logic inside
-        # # _get_default_image_for, acts differently in a running task container) so let's make sure it stays auto.
-        # object.__setattr__(base_image, "_identifier_override", "auto")
         return base_image
 
     @classmethod
@@ -849,16 +832,23 @@ class Image:
         new_image = self.clone(addl_layer=Env.from_dict(env_vars))
         return new_image
 
-    def with_source_folder(self, src: Path, dst: str = ".") -> Image:
+    def with_source_folder(self, src: Path, dst: str = ".", copy_contents_only: bool = False) -> Image:
         """
         Use this method to create a new image with the specified local directory layered on top of the current image.
         If dest is not specified, it will be copied to the working directory of the image
 
         :param src: root folder of the source code from the build context to be copied
         :param dst: destination folder in the image
+        :param copy_contents_only: If True, will copy the contents of the source folder to the destination folder,
+            instead of the folder itself. Default is False.
         :return: Image
         """
-        new_image = self.clone(addl_layer=CopyConfig(path_type=1, src=src, dst=dst))
+        src_name = src.name
+        if copy_contents_only:
+            src_name = "."
+        else:
+            dst = str("./" + src_name)
+        new_image = self.clone(addl_layer=CopyConfig(path_type=1, src=src, dst=dst, src_name=src_name))
         return new_image
 
     def with_source_file(self, src: Path, dst: str = ".") -> Image:
@@ -870,7 +860,7 @@ class Image:
         :param dst: destination folder in the image
         :return: Image
         """
-        new_image = self.clone(addl_layer=CopyConfig(path_type=0, src=src, dst=dst))
+        new_image = self.clone(addl_layer=CopyConfig(path_type=0, src=src, dst=dst, src_name=src.name))
         return new_image
 
     def with_dockerignore(self, path: Path) -> Image:
@@ -923,6 +913,45 @@ class Image:
         )
         return new_image
 
+    def with_poetry_project(
+        self,
+        pyproject_file: str | Path,
+        poetry_lock: Path | None = None,
+        extra_args: Optional[str] = None,
+        secret_mounts: Optional[SecretRequest] = None,
+    ):
+        """
+        Use this method to create a new image with the specified pyproject.toml layered on top of the current image.
+        Must have a corresponding pyproject.toml file in the same directory.
+        Cannot be used in conjunction with conda.
+
+        By default, this method copies the entire project into the image,
+        including files such as pyproject.toml, poetry.lock, and the src/ directory.
+
+        If you prefer not to install the current project, you can pass through `extra_args`
+        `--no-root`. In this case, the image builder will only copy pyproject.toml and poetry.lock
+        into the image.
+
+        :param pyproject_file: Path to the pyproject.toml file. A poetry.lock file must exist in the same directory
+            unless `poetry_lock` is explicitly provided.
+        :param poetry_lock: Path to the poetry.lock file. If not specified, the default is the file named
+            'poetry.lock' in the same directory as `pyproject_file` (pyproject.parent / "poetry.lock").
+        :param extra_args: Extra arguments to pass through to the package installer/resolver, default is None.
+        :param secret_mounts: Secrets to make available during dependency resolution/build (e.g., private indexes).
+        :return: Image
+        """
+        if isinstance(pyproject_file, str):
+            pyproject_file = Path(pyproject_file)
+        new_image = self.clone(
+            addl_layer=PoetryProject(
+                pyproject=pyproject_file,
+                poetry_lock=poetry_lock or (pyproject_file.parent / "poetry.lock"),
+                extra_args=extra_args,
+                secret_mounts=_ensure_tuple(secret_mounts) if secret_mounts else None,
+            )
+        )
+        return new_image
+
     def with_apt_packages(self, *packages: str, secret_mounts: Optional[SecretRequest] = None) -> Image:
         """
         Use this method to create a new image with the specified apt packages layered on top of the current image