Skip to content

Latest commit

 

History

History
149 lines (106 loc) · 4.31 KB

modules.md

File metadata and controls

149 lines (106 loc) · 4.31 KB

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

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.star for an example.

Pixlet module: Secret

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

Function Description
decrypt(value) Decrypts and returns the value when running in Tidbyt cloud. Returns None when running locally. Decryption will fail if the name of the app doesn't match the name that was passed to 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")

Pixlet module: Sunrise

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

Function Description
sunrise(lat, lng, date) Calculates the sunrise time for a given location and date.
sunset(lat, lng, date) Calculates the sunset time for a given location and date.

Example:

See examples/sunrise.star for an example.