modules.md

Module reference

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.

Module	Description
encoding/base64.star	Base 64 encoding and decoding
encoding/json.star	JSON encoding and decoding
http.star	HTTP client
math.star	Mathematical functions and constants
re.star	Regular expressions
time.star	Time operations

Pixlet module: Cache

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

Function	Description
set(key, value, ttl_seconds=60)	Writes a key-value pair to the cache, with expiration as a TTL.
get(key)	Retrieves a value by its key. Returns None if key doesn't exist or has expired.

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: XPath

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

Function	Description
loads(doc)	Parses an XML document and returns an xpath object

On an xpath object, the following methods are available:

Method	Description
query(path)	Retrieves text of the first tag matching the path
query_all(path)	Retrieves text of all tags matching the path

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

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