Python quickstart

In this quick start guide, we will write our first script in Python.

This tutorial covers how to create a simple script through the Orvanta web IDE. See the dedicated page to develop scripts locally and other methods of handling dependencies in Python.

Scripts are the basic building blocks in Orvanta. They can be run and scheduled as standalone, chained together to create Flows or displayed with a personalized User Interface as Apps.

Scripts consist of 2 parts:

• Code: for Python scripts, it must have at least a main function.
• Settings: settings & metadata about the Script such as its path, summary, description, and JSON Schema of its inputs (inferred from its signature).

When stored in a code repository, these 2 parts are stored separately at <path>.py and <path>.script.yaml.

Orvanta automatically manages dependencies for you. When you import libraries in your Python script, Orvanta parses these top-level imports upon saving the script and automatically generates a list of dependencies. For automatic dependency installation, Orvanta will only consider these top-level imports. It then spawns a dependency job to associate these PyPI packages with a lockfile, ensuring that the same version of the script is always executed with the same versions of its dependencies.

Settings

As part of the settings menu, each script has metadata associated with it, enabling it to be defined and configured in depth.

• Summary (optional) is a short, human-readable summary of the Script. It will be displayed as a title across Orvanta. If omitted, the UI will use the path by default.
• Path is the Script’s unique identifier that consists of the script’s owner, and the script’s name. The owner can be either a user, or a group (folder).
• Description is where you can give instructions through the auto-generated UI to users on how to run your Script. It supports markdown.
• Language of the script.
• Script kind: Action (by default), Trigger, Approval, Error handler or Preprocessor. This acts as a tag to filter appropriate scripts from the flow editor.

This menu also has additional settings on Runtime, Generated UI and Triggers.

Code

Orvanta provides an online editor to work on your Scripts. The left side is the editor itself. The right side previews the UI that Orvanta will generate from the Script’s signature — this will be visible to the users of the Script. You can preview that UI, provide input values, and test your script there.

As Python is selected for this example, Orvanta provided some Python boilerplate. In Orvanta, scripts need to have a main function that will be the script’s entrypoint.

Important things to note about the main function:

• The main arguments are used for generating the input spec of the Script and the frontend that you see when running the Script as a standalone app.
• Type annotations are used to generate the UI form, and help pre-validate inputs. While not mandatory, they are highly recommended.
• Orvanta supports Pydantic BaseModel and @dataclass classes as parameter types. When a parameter is typed with a Pydantic model or dataclass, Orvanta infers the JSON schema from the class fields and generates a structured input form. Nested models, Optional, List, and Dict types are supported.

Pydantic and dataclass support

You can use Pydantic BaseModel or Python @dataclass as parameter types for your main function. Orvanta will parse the class definition and generate a structured input form with proper field types.

from pydantic import BaseModel
from typing import Optional, List

class Address(BaseModel):
    street: str
    city: str
    zip_code: Optional[str] = None

class User(BaseModel):
    name: str
    age: int
    addresses: List[Address] = []

def main(user: User):
    return f"Hello {user.name}, age {user.age}"

Dataclasses work the same way:

from dataclasses import dataclass

@dataclass
class Config:
    host: str
    port: int = 8080
    debug: bool = False

def main(config: Config):
    return f"Connecting to {config.host}:{config.port}"

Instant preview & testing

Look at the UI preview on the right: it was updated to match the input signature. Run a test (Ctrl + Enter) to verify everything works.

You can change how the UI behaves by changing the main signature. For example, if you add a default for the name argument, the UI won’t consider this field as required anymore.

def main(name: str = "you"):

Generated UI

From the Settings menu, the “Generated UI” tab lets you customize the script’s arguments.

The UI is generated from the Script’s main function signature, but you can add additional constraints here. For example, you could use the Customize property: add a regex by clicking on Pattern to make sure users are providing a name with only alphanumeric characters.

Workflows as code

One way to write distributed programs that execute distinct jobs is to use flows that chain scripts together.

Another approach is to write a program that defines the jobs and their dependencies, and then execute that program directly in your script. This is known as workflows as code. Use the @workflow decorator on your orchestration function and @task on task functions. Each task runs as a separate job with its own logs and timeline entry, while the workflow suspends between tasks (releasing its worker slot).

Run!

We’re done! Now let’s look at what users of the script will do. Click on the Deploy button to load the script. You’ll see the user input form we defined earlier.

Note that Scripts are versioned in Orvanta, and each script version is uniquely identified by a hash.

Fill in the input field, then hit “Run”. You should see a run view, as well as your logs. All script runs are also available in the Runs menu on the left.

You can also choose to run the script from the CLI with the pre-made command-line interface call.

Select Python version

You can annotate the version of Python you would like to use for a script using the following annotations: py310, py311, py312, or py313:

# py312
type Foo = str

def main():
    foo: Foo = "Foo"
    return foo

Python version specifiers

You can also use more advanced version specifiers with the shortcut format to specify exact version requirements:

# py: >=3.12
def main():
    return "Hello from Python 3.12+"

# py: ==3.12.*
def main():
    return "Hello from any Python 3.12 version"

# py: >=3.11,<3.14
def main():
    return "Hello from Python 3.11 to 3.13"

These version specifiers use PEP 440 syntax and provide more precise control over Python version requirements than the simple annotations. This is especially useful when you need to ensure compatibility with specific Python features or avoid known issues in certain versions.

Alternatively, you can set a global version by configuring the INSTANCE_PYTHON_VERSION environment variable to one of the mentioned versions or unset it to use “Latest Stable”. If you leave INSTANCE_PYTHON_VERSION empty it will inherit the “Latest Stable” version, which depends on Orvanta.

For newly deployed scripts, the annotated or instance version will be assigned to the lockfile, and all future executions will adhere to that specified version.

For scripts that are already deployed and have no version specified in the lockfile, Python 3.11 will be used by default, even if the instance version is changed to a different one.

During test runs or deployments, if there are imported scripts, Orvanta will search through all of them to find an annotated version, which will be used as the final version. If no annotated version is found, the instance version will be used instead.

Note

For Enterprise Edition customers, S3 cache tarballs will be organized and separated by Python version.

Caching

Every dependency on Python is cached on disk by default. Furthermore, if you use the Distributed cache storage, it will be available to every other worker, allowing fast startup for every worker.

What’s next?

This script is a minimal working example, but there are a few more steps that can be useful in a real-world use case:

• Pass variables and secrets to a script.
• Connect to resources.
• Trigger that script in many ways.
• Compose scripts in Flows, low-code apps or full-code apps.
• You can share your scripts with the community on the Orvanta Hub. Once submitted, they will be verified by moderators before becoming available to everyone right within Orvanta.

Scripts are immutable and there is a hash for each deployment of a given script. Scripts are never overwritten and referring to a script by path is referring to the latest deployed hash at that path.

For each script, a UI is autogenerated from the JSON schema inferred from the script signature, and can be customized further as a standalone or embedded into rich UIs using the App builder.

In addition to the UI, sync and async webhooks are generated for each deployment.