Guild packages with setup.py

How To
1

The package command is used to generate an installable package that includes Guild models and operations. For more information, see Packages. This command simplifies the process of packaging. However, it cannot be used in conjunction with a project’s setup.py script. To support Guild packages using setup.py you must make a few changes to that script.

The steps below assume a standard Python distribution created with setup.py.

You can use Cookiecutter to generate a Python project that supports such distributions.

cookiecutter https://github.com/audreyr/cookiecutter-pypackage

The steps below are used to add Guild model operation support to such projects.

Add guild.yml to the project within the Python package directory

Here’s a simple Guild file.

# guild.yml located within the Python package dir

op:
  description: A sample operation

The file op.py looks like this:

# op.py

print("Hello from a Guild package")

The Guild file must be located within the package directory in order to be installed with the package.

Add Guild models as entry points in setup.py

Guild models are discovered using entry points under guild.models. Add them in the format:

MODEL_NAME=guild.model:PackageModel

If the model name is empty (i.e. the anonymous model) use the special string __anonymous__. The example above therefore is added like this:

setup(
    ...
    entry_points=[
        'guild.models': [
            '__anonymous__=guild.model:PackageModel',
        ],
    ],
    ...

Add guild.yml to MANIFEST.in

The distribution must contain guild.yml. This file is not added by setup.py by default. You must add it by including it in MANIFEST.in, which is located in the project root.

Add it like this:

include <package name>/guild.yml

Replace <package name> with the applicable package.

Note that if the package requires any other files, they must be included here as well.

Build a distribution

Create a wheel using the bdist_wheel command with setup.py:

python setup.py bdist_wheel

This generates a wheel distribution in dist that you can distribute to others.

You can inspect this file using a zip compatible viewer, e.g. unzip. The file should contain guild.yml within the Python package. The package entry_points.txt should contain the entries you make above.

Test the package in a separate virtual environment

Create a virtual environment, activate the environment, and install the wheel created in the previous step.

You should be able to list and run the packaged Guild operations.

guild ops

<sample package>/op  A sample operation

Running the op:

guild run op -y

Hello sample Guild package!

Distribute the distribution

You can upload the wheel file in dist to PyPI for others to install. They have access to the Guild operations provided by the package.