Modules¶

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")

Starlib modules¶

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

Starlib HTTP¶

Pixlet includes an enhanced version of the Starlib HTTP module.

Additional features:

• HTTP client accepts a parameter ttl_seconds to optionally cache HTTP responses.
• Responses include a status property which contains the status text and the status code (e.g. "401 Unauthorized").
• Additional function http.status_text(code) allows an applet to get the status text for a given status code (e.g. "Unauthorized").

Pixlet module: Cache¶

In addition to the Starlib modules, Pixlet offers a cache module.

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

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
...

Pixlet module: File¶

The file module lets you load files from your app's directory as assets. Unlike other modules, you don't load a .star file. Instead, you load the asset path directly and alias the "file" identifier to a variable of your choosing:

load("my_image.png", img = "file")

This gives you a File object bound to img. Note that the alias (img = "file") is required since Starlark's load statement only imports named identifiers - there's no default export to grab.

File object¶

Example:

load("render.star", "render")
load("icon.png", icon_file = "file")
load("message.txt", message_file = "file")

ICON = icon_file.readall("rb")
MESSAGE = message_file.readall()

def main():
    return render.Root(
        child = render.Row(
            children = [
                render.Image(src=ICON),
                render.Text(MESSAGE),
            ],
        ),
    )

Pixlet module: HMAC¶

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

Pixlet module: Humanize¶

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

Example:

See examples/humanize/humanize.star for an example.

Pixlet module: i18n¶

The i18n module provides a single helper that formats strings using the active locale. See the Internationalization guide for creating locale files and selecting a language at runtime.

Pixlet module: XPath¶

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")
...

Pixlet module: Render¶

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"))

Canvas¶

The render.star module also provides canvas, which lets an app fetch information about the current output configuration.

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

def main(config):
    w, h = canvas.width(), canvas.height()
    return render.Root(
        child = render.Padding(
            child = render.Text("%dx%d" % (w, h)),
            pad = 1,
        ),
    )

Pixlet module: Color¶

The color.star module provides color manipulation functions and a Color object that can be passed to widgets.

Color object¶

The Color object represents a color and provides ways to manipulate and retrieve its components in different formats. It can also be passed to a widget in-place of a hex string.

Fields¶

The following fields are available on a Color object and can be both read and written:

Methods¶

Example:

load("color.star", "color")

def main():
    c = color.hex("#f00")
    c.g = 255
    print(c.hex())
    # Output: "#ff0"

    c.h = 240 # change to blue
    print(c.hex())
    # Output: "#00f"

RGB¶

Creates a color from red, green, blue, and optionally alpha components.

Parameters:

• r, g, b: Integers (0-255).
• a (optional): Integer (0-255), defaults to 255.

Example:

load("color.star", "color")

def main():
    c = color.rgb(255, 0, 0)
    print(c.r, c.g, c.b)
    # Output: 255 0 0

Hex¶

Creates a color from a hex string (e.g., #ff0000, #f00, #ff000080, or #f008).

Parameters:

• value: The hex color string.

Example:

load("color.star", "color")

def main():
    c = color.hex("#f00")
    print(c.rgba())
    # Output: (255, 0, 0, 255)

HSV¶

Creates a color from Hue, Saturation, Value, and optionally alpha components.

Parameters:

• h: Hue (0-360).
• s: Saturation (0-1).
• v: Value (0-1).
• a (optional): Integer (0-255), defaults to 255.

Example:

load("color.star", "color")

def main():
    c = color.hsv(0, 1, 1)
    print(c.hex())
    # Output: "#f00"

Pixlet module: Schema¶

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

Example:

See examples/schema_hello_world/schema_hello_world.star for an example.

Pixlet module: Sunrise¶

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

Example:

See examples/sunrise/sunrise.star for an example.

Pixlet module: Random¶

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 Tronbyt 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!")

Pixlet module: QRCode¶

The qrcode module provides a QR code generator for pixlet!

Sizing works as follows:

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

Example:

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

def main(config):
    url = "https://tronbyt.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,
        ),
    )

Pixlet module: YAML¶

The yaml module provides functions to decode and encode YAML.

Example:

load("encoding/yaml.star", "yaml")
load("render.star", "render")

EXAMPLE_YAML = "message: Hello, world!"

def main(config):
    data = yaml.decode(EXAMPLE_YAML)
    return render.Root(render.Text(data["message"]))

Pixlet module: Strings¶

The strings module provides string manipulation functions.

Pad¶

Parameters:

• text: The string to pad.
• length: The minimum length of the resulting string.
• align (optional): The alignment of the text. Can be "start" (default) or "end".
• char (optional): The character to pad with. Defaults to space.

Example:

load("strings.star", "strings")

def main():
    print(strings.pad("foo", 5))
    # Output: "foo  "

    print(strings.pad("foo", 5, "end"))
    # Output: "  foo"

Truncate¶

Parameters:

• text: The string to truncate.
• length: The maximum length of the resulting string.
• ellipsis (optional): The string to append to the truncated text. Defaults to "…".

Example:

load("strings.star", "strings")

def main():
    print(strings.truncate("hello world", 5))
    # Output: "hell…"

    print(strings.truncate("hello world", 5, "..."))
    # Output: "he..."