A code location is collection of Dagster definitions loadable and accessible by Dagster's tools, such as the CLI, Dagit, and Dagster Cloud. A code location comprises:
Definitions at the "defs" variable.Definitions within a code location have a common namespace and must have unique names. This allows them to be grouped and organized by code location in tools.
Before the introduction of the DefinitionsAPI, definitions were grouped into repositories, and there could be many repostories in a particular code location. See the guide on Repositories for this previous API and mental model.
| Name | Description |
|---|---|
Definitions | The object that contains all the definitions defined within a code location |
| --- |
To define a code location, one first has to create a Definitions object in the defs variable of a python module. This can be is vanilla python file (e.g. foo.py). In that case the Definitions object can go in that file itself. Or it can be an installed python package in which case the definitions object should be defined in the defs symbol in that package's top-level __init__.py file.
defs = Definitions( assets=[an_asset, another_asset], schedules=[a_schedule], sensors=[a_sensor], resources=some_resources )
Example: $ dagit -f foo.py
dagit and other Dagster tools can load a file directly as a code location. The command dagit -f foo.py is loading a code location: it will load the definitions in foo.py as a code location in the same python environment where Dagit resides.
Example: $ dagit -m your_package_name
Installed python packages can also be loaded by Dagster tools. It will load the definitions defined as the top-level of that package, in its root __init__.py file. For Dagster projects deployed to production we recommend this style of development, as it eliminates an entire class of python import errors. Create a Dagster project with the dagster project scaffold command or by using one of our templates. This project can then be installed using pip install -e . to make it an editable install for local development.
Once installed, this package can be loaded typing dagit -m your_package_name. This should be read as "load definitions in the defs symbol in this package (defined as its root __init__.py file) in the same virtual environment as Dagit itself.
Example: $ dagit
Our project templates also create a pyproject.toml file with a tool.dagster section an assignment to the python_package variable in that section. This allows users to type just dagit without any parameters and the package name is defined in that variable. This is very convenient for local development.
[tool.dagster] python_package = "your_package_name"
When one runs a dagster CLI in the same directory as this toml file, it is equivalent of running dagit -m your_package_name.