Using Packages

NOTE

Before you begin, make sure you’ve set up your authentication

And installed a Steamship client library with:

pip install steamship

npm install --save @steamship/client

Steamship packages are listed in our package directory (opens in a new tab). To use one, instantiate it with Steamship.use, giving it a package handle and an instance handle.

from steamship import Steamship
 
instance = Steamship.use("package-handle", "instance-handle")

import { Steamship } from "@steamship/client"
 
const instance = Steamship.use("package-handle", "instance-handle")

The package handle references the package you’d like to use. The instance handle creates a private stack for data and infrastructure that package depends on.

Once you have a package instance, invoke a method by calling invoke. The method name is the first argument. All other arguments are passed as keyword args.

result = instance.invoke('method_name', arg1=val1, arg2=val2)

const result = await instance.invoke('method_name', {arg1: val1, arg2: val2})

The method will run in the cloud, and you’ll get back the response as a Python object. Packages can also be used as HTTP APIs.

Package FAQ

What is a Package Handle?

A Package Handle identifies a Steamship package, in the same way that NPM and PyPI packages have identifiers.

from steamship import Steamship
instance = Steamship.use("package-handle", "instance-handle")

import { Steamship } from "@steamship/client"
const instance = Steamship.use("package-handle", "instance-handle")

Package handles always composed of lowercase letters and dashes.

What is an Instance Handle?

An Instance Handle identifies a particular instance of the package.

from steamship import Steamship
instance = Steamship.use("package-handle", "instance-handle")

import { Steamship } from "@steamship/client"
const instance = Steamship.use("package-handle", "instance-handle")

Steamship packages manage their own configuration, data, endpoints, and infrastructure in the cloud. Your instance handle of a package creates a scope, private to you, to contain that.

Do I need an Instance Handle?

If you do not provide an Instance Handle, the default value will be identical to the Package Handle.

from steamship import Steamship
instance1 = Steamship.use("package-handle")
instance1_copy = Steamship.use("package-handle")
instance1_copy2 = Steamship.use("package-handle")

import { Steamship } from "@steamship/client"
 
const instance1 = Steamship.use("package-handle")
const instance1_copy = Steamship.use("package-handle")
const instance1_copy2 = Steamship.use("package-handle")

The above code loads three copies of the same instance, bound to the same data and infrastructure. It is equivalent to having run this code:

from steamship import Steamship
instance = Steamship.use("package-handle", "package-handle")
instance1_copy = Steamship.use("package-handle", "package-handle")
instance1_copy2 = Steamship.use("package-handle", "package-handle")

import { Steamship } from "@steamship/client"
 
const instance1 = Steamship.use("package-handle", "package-handle")
const instance1_copy = Steamship.use("package-handle", "package-handle")
const instance1_copy2 = Steamship.use("package-handle", "package-handle")

Can I reload the same instance?

You can reload a package instance by providing the same instance handle again. All of the correct configuration, data, and models will be bound to the instance.

In the below code,

instance1 and instance1_copy are operating upon the same data and infrastructure.
instance2 is operating upon a different set of data and infrastructure

instance1 = Steamship.use("package-handle", "instance-handle")
instance1_copy = Steamship.use("package-handle", "instance-handle")
instace2 = Steamship.use("package-handle", "some-other-handle")

import { Steamship } from "@steamship/client"
 
const instance1 = Steamship.use("package-handle", "instance-handle")
const instance1_copy = Steamship.use("package-handle", "instance-handle")
const instance2 = Steamship.use("package-handle", "some-other-handle")

How do I specify a package version?

When instantiating a package, you can pin it to a particular version with the version keyword argument.

instance = Steamship.use("package-handle", "instance-handle", version="1.0.0")

import { Steamship } from "@steamship/client"
 
const instance = Steamship.use("package-handle", "instance-handle", "1.0.0")

If you do not specify a version, the last deployed version of that package will be used.

How do I provide package configuration?

When instantiating a package, you can provide configuration with the config keyword argument.

instance = Steamship.use("package-handle", "instance-handle", config=config_dict)

import { Steamship } from "@steamship/client"
 
const instance = Steamship.use("package-handle", "instance-handle", undefined, {key: "value"})

To learn what configuration is required, consult the README.md file in the package’s GitHub repository.

How do I know what methods to call?

To learn what methods are available on a package, consult the README.md file in the package’s GitHub repository.

We are working on a more streamlined way to generate and publish per-package documentation.

In the meantime, you can also explore a package’s methods from your REPL with:

instance = Steamship.use("package-handle")
instance.invoke("__dir__")

const instance = Steamship.use("package-handle")
instance.invoke("__dir__")

Can I access my package over HTTP?

Every instance of your package exposes an HTTP API that you can call. The Instance Base URL is:

https://{userHandle}.steamship.run/{workspaceHandle}/{instanceHandle}/

In that URL:

{userHandle} is your user handle (not the handle of the person who create the package)
{workspaceHandle} is the handle of the workspace that package is running in. It is usually equal to the instanceHandle
{instanceHandle} is the name you gave your instance

You can always find out your Instance Base URL via the Python Client with the PackageInstance.invocation_url property:

instance = Steamship.use('some-package', 'my-handle')
print(instance.invocation_url)

Prints:

https://{you}.steamship.run/my-handle/my-handle/

Calling this URL is simple with a few conventions:

Set the Content-Type header to application/json
Set the Authorization header to Bearer {api-key}, replacing {api-key} with your API Key
Default to HTTP POST if you’re not sure which verb to use. The package documentation should specify.
Add the method name you wish to invoke as the path.
Add the arguments as a JSON-encoded POST Body

For example, the HTTP equivalent of:

instance.invoke('greet', name='Beautiful')

would be:

POST /{workspace-handle}/{instance-handle}/greet
Content-Type: application/json
Authorization: Bearer {api-key}

{"name": "Beautiful"}

Packages Developing Packages