Pixlet scripts have access to a couple of modules that can be very helpful in developing applets. To make use of a module, use the load statement.

The example below would load the render.star Starlark module, extract the render identifier and make it available to the script as the symbol render.

load("render.star", "render")

It's also possible to assign the identifiers to a different symbol. In this example, the render module is made available to the script as the symbol r instead of render:

load("render.star", r = "render")

Pixlet offers a subset of the modules provided by the Starlib project. For documentation of the individual modules, please refer to the Starlib documentation.

Pixlet also includes a version of the Starlib HTTP module, which has been modified to handle caching. It's very important to keep outgoing request rates at reasonable levels, and for this reason the HTTP client has been extended to accept a parameter ttl_seconds to control for how long HTTP responses should be cached.

Example:

load("http.star", "http")
def get_data(url):
    res = http.get(url, ttl_seconds=3600) # cache for 1 hour
    if res.status_code != 200:
        fail("GET %s failed with status %d: %s", url, res.status_code, res.body())
    return res.json()

In addition to the Starlib modules, Pixlet offers a cache module. Since the HTTP module comes with caching built-in, 95% of apps won't need the cache module, but it's there for those that do.

Keys and values must all be string. Serialization of non-string data is the developer's responsibility.

NOTE: The cache is unique per app and not per installation. All installations of your app will share the same cache. This is a common source of bugs!

Example:

load("cache.star", "cache")
def get_counter():
    i = cache.get("counter")
    if i == None:
        i = 0
    cache.set("counter", str(i + 1), ttl_seconds=3600)
    return i + 1
...

This module implements the HMAC algorithm as described by RFC 2104.

Example:

load("hmac.star", "hmac")

sum = hmac.md5("secret", "hello world!")
print(sum)
# Output: 0a0461e10e89506d7c31a145663bed93

The humanize module has formatters for units to human friendly sizes.

Example:

See examples/humanize.star for an example.

The xpath module lets you extract data from XML documents using XPath queries.

On an xpath object, the following methods are available:

The query_node and query_all_nodes methods allow you to recursively query the XML document, which can be useful if you need to query several tags that are nested underneath some parent tag.

Example:

load("xpath.star", "xpath")

doc = """
<foo>
    <bar>bar</bar>
    <bar>baz</bar>
</foo>
"""

def get_bars():
    x = xpath.loads(doc)
    return x.query_all("/foo/bar")

def also_get_bars():
    x = xpath.loads(doc)
    foo = x.query_node("/foo")
    return foo.query_all("/bar")
...

The render.star module is where Pixlet's Widgets live. All of them are documented in a fair bit of detail in the widget documentation.

Example:

load("render.star", r="render")
def main():
    return r.Root(child=r.Box(width=12, height=14, color="#ff0"))

The schema module provides configuration options for your app. See the schema documentation for more details.

Example:

See examples/schema_hello_world.star for an example.

The secret module can decrypt values that were encrypted with pixlet encrypt.

Example:

load("secret.star", "secret")

ENCRYPTED_API_KEY = "AV6+..." . # from `pixlet encyrpt`

def main(config):
    api_key = secret.decrypt(ENCRYPTED_API_KEY) or config.get("dev_api_key")

The sunrise module calculates sunrise and sunset times for a given set of GPS coordinates and timestamp.

Example:

See examples/sunrise.star for an example.

The random module provides a pseudorandom number generator for pixlet. The generator is automatically seeded on each execution. The seed itself changes every 15 seconds, making apps deterministic over that same time window. This behavior enables more effective caching of execution results on Tidbyt servers. Developer can reseed via random.seed if needed.

Example:

load("random.star", "random")

def main(config):
    num = random.number(0, 100)
    if num > 50:
        print("You win!")
    else:
        print("Better luck next time!")

The qrcode module provides a QR code generator for pixlet!

Sizing works as follows:

• small: 21x21 pixels
• medium: 25x25 pixels
• large: 29x29 pixels

Note: we're working with some of the smallest possible QR codes in this module, so the amount of data that can be used for the URL is extremely limited.

Example:

load("cache.star", "cache")
load("encoding/base64.star", "base64")
load("render.star", "render")
load("qrcode.star", "qrcode")

def main(config):
    url = "https://tidbyt.com?utm_source=pixlet_example"

    data = cache.get(url)
    if data == None:
        code = qrcode.generate(
            url = url,
            size = "large",
            color = "#fff",
            background = "#000",
        )
        cache.set(url, base64.encode(code), ttl_seconds = 3600)
    else:
        code = base64.decode(data)

    return render.Root(
        child = render.Padding(
            child = render.Image(src = code),
            pad = 1,
        ),
    )