Packages

Documentation
1

Overview

Guild lets you package and distribute your work to make deployment and reuse easier for others.

To see how Guild packages work, you can experiment with a pre-packaged Guild package gpkg.hello.

Install a sample package:

pip install gpkg.hello

List available operations:

guild ops gpkg.hello

gpkg.hello/hello:default           Print a default message
gpkg.hello/hello:from-file         Print a message from a file
gpkg.hello/hello:from-file-output  Print output from last file-output operation
gpkg.hello/hello:from-flag         Print a message

Run an operation:

guild run gpkg.hello/hello:default -y

Hello Guild!

Uninstall the package.

pip uninstall gpkg.hello

This is a simple “hello world” operation. You can deploy and use your own packages just as easily.

Note Guild packages are standard Python wheel distributions. They are deployed using any of the supported methods for deploying Python packages, including installation with pip from PyPI.

Use Guild packages to:

  • Delpoy models for production
  • Let others easily use your work (e.g. for reproducibility)
  • Release your work as an installable program, using Guild as the CLI

Build a Package

Build a package for your project by running guild package. The project must contain a Guild file to run this command.

guild package

If the project does not contain a top-level package object, Guild uses a number of default values when generating a package.

If you intend to distribute the package, define a package object using a full format Guild file.

- package: gpkg.my-model
  version: 0.0.1

- model: model-1
  ...

- model: model-2
  ...

Note To avoid name collisions with other packages in PyPI, prefix the package name with gpkg. or another namespace.

This minimal configuration lets you name and version the package. For a full list of supported package attributes, see Guild File Reference.

To upload a package to PyPI use the --upload option. Specify your PyPI user name and password using the --user and --password options respectively. Refer to package command help for more information.

Note To upload packages, you need the twine package. Install it using pip install twine.

Install a Package

If you upload the package to PyPI, you can install it using pip and the package name.

pip install gpkg.my-model

To install the wheel directly, use pip to install the applicable file created in the dist project subdirectory.
Project
guild.yml
build Temporary directory containing package build artifacts
*.egg-info Temporary egg info directories
dist Directory containing generated wheels
*.whl Generated wheels — install using pip install dist/*.whl

Tip Avoid storing package related files your git repository by adding the following items to the .gitignore file:

build
dist
*.egg-info

Use Installed Packages

Installed Guild packages provide models and operations that you can run from any directory on your system. Think of these like programs that you install and interact with using Guild commands.

List installed packages:

guild packages

Show help for an installed package:

guild help PACKAGE

List installed models:

guild models -i

List installed operations:

guild operations -i

Tip You can omit the -i when running either of the above commands from outside a project directory. The -i option is required when running witint a project directory to include installed models and operations, which are otherwie omitted.

Packages and Remote Operations

Guild uses the packaging facility when running remote operations. Generally the package object is not necessary to support remote runs. Guild’s default packaging support is sufficient to package and install a project on a remote system.

In cases where the default packaging support is not sufficient, you can create a package object as described above.

Data Files

If an operation requires project files, those files must be included in a package for remote runs.

Use the data-files package attribute to list files for inclusion in the package.

The hello-package example illustrates how this works:

Refer to this example to include a directory of files in the generated package.

Tip You can list files in a Python wheel using any zip-compatible tool. To view package files using the unzip command, run unzip -l dist/*.whl. Use this to verify that the package contains the expected source code and data files.