Command Line Interface
Contents
Command Line Interface¶
Dask provides a dask
executable for a command line interface.
Dask’s CLI is designed to be extensible allowing
other projects in the Dask ecosystem (such as distributed
) to
add subcommands.
Built-in commands¶
dask
comes with the following commands.
Extending the Dask CLI¶
Note
This section is intended for library authors who want to
integrate their library with the dask
CLI.
Third party packages can extend the dask
command line tool via
entry points and Click. Dask will discover click.Command
and
click.Group
objects registered as entry points under the
dask_cli
namespace. Below you’ll find two examples which augment
the dask
CLI by adding a dask_cli
entry point to a project.
Click provides great documentation for writing commands; more documentation on entry points can be found at:
Example: PEP-621¶
Since PEP-621, if starting a
new project, the canonical way to add an entry point to your Python
project is to use the [project.entry-points]
table in the
pyproject.toml
file. This method should be picked up by any Python
build system that is compatible with PEP-621
’s project
configuration. Hatch, Flit, and setuptools (version 61.0.0 or
later) are three example build systems which are PEP-621 compatible
and use [project.entry-points]
.
For example, if your project is called mypackage
, and it contains
a cli.py
module under the mypackage
namespace with the
following contents:
# in the file mypackage/cli.py
import click
@click.command(name="mycommand")
@click.argument("name", type=str)
@click.option("-c", "--count", default=1)
def main(name, count):
for _ in range(count):
click.echo(f"hello {name} from mycommand!")
You can create an entry point that will be discovered by Dask by
adding to pyproject.toml
:
[project.entry-points."dask_cli"]
mycommand = "mypackage.cli:main"
After installing mypackage
, the mycommand
subcommand should be
available to the dask
CLI:
$ dask mycommand world
hello world from mycommand!
$ dask mycommand user -c 3
hello user from mycommand!
hello user from mycommand!
hello user from mycommand!
Example: setup.cfg and setup.py¶
Note
If you are starting a new project the recommendation from the Python Packaging Authority (PyPA) is to use PEP-621, these setuptools instructions are provided for existing projects.
If your project already uses setuptools
with a setup.cfg
file
and/or a setup.py
file, we can create an entry point for the same
mycommand.cli:main
function introduced in the previous section. If
using setup.cfg
, the entry point can be registered by adding the
following block to the file:
[options.entry_points]
dask_cli =
mycommand = mypackage.cli:main
Or the entry point can be registered directly in setup.py
with:
from setuptools import setup
setup(
...
entry_points="""
[dask_cli]
mycommand=mypackage.cli:main
""",
)