External (source) packages

You might encounter a situation where you have to incorporate your own modules or third-party package(not on PyPi) into your truss. Truss has a few different mechanisms to support this.

1. Using the packages directory
2. Using the external packages directory

Let’s look at using the packages directory first.

​

Using the packages directory

Each truss, when initialized, comes with a packages directory. This directory is at the same level as the model directory in the hierarchy. Inside this directory, you can place any additional python packages that your would like to reference inside your truss. For example, your packages directory might look like this:

stable-diffusion/
    packages/
        package_1/
            subpackage/
                script.py
        package_2/
            utils.py
            another_script.py
    model/
        model.py
        __init__.py
    config.yaml

You can import these packages inside your model.py like so:

from package_1.subpackage.script import run_script
from package_2.utils import RandomClass

class Model:
    def __init__(self, **kwargs):
        random_class = RandomClass()

    def load(self):
        run_script()

    ...
    ...
    ...

These packages get bundled with your truss at build time. Because of this, it’s ideal to use this method when your packages are small.

But what if you have multiple trusses that want to reference the same package? This is where the external_package_dirs comes in handy. The external_package_dirs allows you to import packages that are outside your truss and hence allows multiple trusses to reference the same package.

Let’s look at an example.

​

Using the external packages directory

Let’s say you have the following setup:

stable-diffusion/
    model/
        model.py
        __init__.py
    config.yaml
super_cool_awesome_plugin/
    plugin1/
        script.py
    plugin2/
        run.py

In this case the package you want to import, super_cool_awesome_plugin, is outside the truss. You could move the super_cool_awesome_plugin directory inside the packages directory if you wanted to, but there is another option. Inside the config.yaml you can specify the path to external packages by using the key external_package_dirs. Under this key, you can provide a list of external packages that you would like to use in your truss. Here is what that would look like for the example above:

environment_variables: {}
external_package_dirs:
- ../super_cool_awesome_plugin/
model_name: Stable Diffusion
python_version: py39
...
...
...

Here’s how you can reference your packages inside model.py:

from plugin1.script import cool_constant
from plugin2.run import AwesomeRunner

class Model:
    def __init__(self, **kwargs):
        awesome_runner = AwesomeRunner()

    def load(self):
        awesome_runner.run(cool_constant)

    ...
    ...
    ...

Depending on the use-case either of these techniques can be used. If you have a one-off package that your truss needs, consider using the packages directory. On the other hand, if you have a common package that will get used by multiple trusses, external_package_dirs is the better option.