Is it bad practice to specify DeploymentSpec in the same file as the flow?

In the docs, I see only flow_location documented at Deployments - Prefect 2.0

DeploymentSpec(
    name="leonardo-deployment",
    flow_location="./leo_flow.py",
    tags=['tutorial','test'],
    parameters={'name':'Leo'}
)

And it only mentions that required:
“”"
A deployment specification includes the settings that will be used to create a deployment in the Prefect database and to create flow runs based on the flow code and deployment settings. A deployment specification consists of the following pieces of required information:

The deployment name
The flow_location or the path to a flow definition
You can additionally include the following optional information:

tags to attach to the flow runs generated from this deployment
parameters whose values will be passed to the flow function when it runs
a schedule for auto-generating flow runs
“”"

But I noticed DeploymentSpec also allows specifying flow=, like below

DeploymentSpec(
    name="leonardo-deployment",
    flow=leonardo_dicapriflow,
    tags=['tutorial','test'],
    parameters={'name':'Leo'}
)
1 Like

You are asking hard questions @ahuang11 :smile:

The flow object or flow_location?

I’d consider it best practice to use the flow object rather than the flow_location since it’s cleaner and you don’t have to worry about paths (which can be complicated, especially when switching between various OS - e.g. local development on Mac or Windows and deploying to a Linux machine)

btw the flow argument is the flow object (your function name) rather than a string of that flow name - it means that instead of:

DeploymentSpec(
    name="leonardo-deployment",
    flow="leonardo_dicapriflow",
    tags=['tutorial','test'],
    parameters={'name':'Leo'}
)

you’d need:

DeploymentSpec(
    name="leonardo-deployment",
    flow=leonardo_dicapriflow,
    tags=['tutorial','test'],
    parameters={'name':'Leo'}
)

Same file or different ones?

This is a matter of preference - I believe it can be convenient for some users to import all flow objects into one deployment file and create all deployments in one go:

prefect deployment create deployments.py

However, if you want to frequently redeploy a single flow rather than all of them, it makes sense to have each deployment defined in the flow file directly - that’s actually my personal preference, but we are not opinionated on that

1 Like

I agree, so should docs be updated to reflect this? It also probably reduces friction for starting users if they can just copy + paste rather than saving the file and opening another file to save the deployment

1 Like

100%, I would vote for it. But generally speaking, we tend to be “unopinionated” so not sure whether we should recommend one way over the other, usually we just show to people that both options are possible and they can choose - hard to say

Okay so I think it just needs a mention in documentation.