Objects

Listing & Accessing¶

Objects can be accessed using the objects property in Apps, Plugins, or Users:

Sync

App

app = heedy.App("your_access_token","http://localhost:1324")
objs = app.objects() # list objects that belong to the app
print(objs)

User

app = heedy.App("your_access_token","http://localhost:1324")
myuser = app.owner # Gets the user that owns this app
objs = myuser.objects() # list all permitted objects belonging to the user
print(objs)

Plugin

p = heedy.Plugin(session="sync")
objs = p.objects() # access objects of any user on the server
print(objs)

Async

App

app = heedy.App("your_access_token","http://localhost:1324",session="async")
objs = await app.objects() # list all objects that belong to the app
print(objs)

User

app = heedy.App("your_access_token","http://localhost:1324",session="async")
myuser = await app.owner # Gets the user that owns this app
objs = await myuser.objects() # list all objects that belong to the user
print(objs)

Plugin

p = heedy.Plugin()
objs = await p.objects() # list all objects on the server
print(objs)

The list returned from the objects function can be constrained, usually by object type, tags, or app key. The tags are space-separated, and will match all objects with their superset.

Sync

app.objects(tags="steps fitbit",type="timeseries")

Async

await app.objects(tags="steps fitbit",type="timeseries")

[Timeseries{'access': 'read',
  'app': 'acf85b01-3c87-4813-9538-3c1120ecb2a3',
  'created_date': '2021-03-12',
  'description': '',
  'id': 'e1f4d4c2-d4f0-431a-bcaf-58c512fc7564',
  'key': 'steps',
  'meta': {'schema': {'type': 'number'}},
  'modified_date': '2021-09-27',
  'name': 'Steps',
  'owner': 'test',
  'owner_scope': 'read',
  'tags': 'fitbit steps charge5',
  'type': 'timeseries'}]

Creating & Deleting¶

One can create new objects of a given type by calling the create method in objects:

Sync

obj = app.objects.create("My Timeseries",
                    type="timeseries",
                    meta={"schema":{"type":"number"}},
                    tags="myts mydata",
                    key="myts")

Async

obj = await app.objects.create("My Timeseries",
                    type="timeseries",
                    meta={"schema":{"type":"number"}},
                    tags="myts mydata",
                    key="myts")

Only the first argument, the object name, is required. If not explicitly specified, the object type will be timeseries, and all other fields will be empty.

When creating an object for an app, it is useful to give it a key. Keys are unique per-app, meaning that the app can have only one object with the given key. The object then can be retrieved using:

Sync

obj = app.objects(key="myts")[0]

Async

obj = (await app.objects(key="myts"))[0]

Finally, to delete an object and all of its data, one can use the delete method:

Sync

obj.delete()

Async

await obj.delete()

Note

Plugins have administrative access to the database, but to create an object belonging to the app when logged in using an App token, the app must have self.objects:create scope. Similarly, deleting an object requires the self.objects:delete scope. Finally, editing the object’s properties requires the self.objects:update scope. Writing an object’s content/data requires the self.objects:write scope. To give an app full access to manage its own objects, you can give it self.objects super-scope.

Reading & Updating Properties¶

All properties available on the object can be accessed directly as properties in Python in two ways:

Sync

# Reads the key property from the server
assert obj.key == "myts"
# Uses the previously read cached data, avoiding a server query
assert obj["key"] == "myts"

Async

# Reads the key property from the server
assert (await obj.key) == "myts"
# Uses the previously read cached data, avoiding a server query
assert obj["key"] == "myts"

When trying to access cached properties for an object that was not yet read from the server, obj["key"] will return a KeyError. To refresh the cache, it is sufficient to run:

Sync

obj.read()
assert obj["key"]=="myts"

Async

await obj.read()
assert obj["key"]=="myts"

The read function returns a dict containing the props. Any read or update for the object will also refresh the cache with new data.

To update properties, the update method can be used, or the props can directly be set if in a sync session:

Sync

# Both of these lines do the same thing.
obj.description = "My description"
obj.update(description="My description")

Async

#
#
await obj.update(description="My description")

Updating Metadata¶

Each object has a meta property, which is defined separately for every object type. For example, the timeseries object type defines meta to contain a JSON schema describing the data type of each datapoint in the series:

[Timeseries{...
  'meta': {'schema': {'type': 'number'}},
  ...
  'type': 'timeseries'}]

Since the meta property is a dict that can contain multiple sub-properties, it has special handling in the API. For example, updating an object to set its meta property will merge the new values with the old ones:

Sync

obj.meta() # Read meta from server ={"a": 1,"b":2,"c":3}
obj.meta = {"c": 4,"b": None} # Update the b,c values
print(obj.meta) # {"a": 1,"c":4} # The update results are cached

Async

await obj.meta() # Read meta from server ={"a": 1,"b":2,"c":3}
await obj.update(meta={"c": 4,"b": None}) # Update the b,c values
print(obj.meta) # {"a": 1,"c":4} # The update results are cached

Setting a key in meta to None resets it to its default value, so deleting a timeseries schema will simply reset the schema to {} rather than removing the key.

Finally, for simplicity, the Python API supports direct modification of the meta object:

Sync

obj.meta.schema = {"type":"string"}
del obj.meta.b

Async

await obj.meta.update(schema={"type":"string"})
await obj.meta.delete("b")

Timeseries Data¶

The timeseries object type is built into heedy by default. A timeseries can be considered an array of datapoints of the form:

{
    "t": 1234556789.0, // unix timestamp in seconds,
    "d": 2, // data associated with the timestamp,
    "dt": 60, //optional duration of the datapoint in seconds, [t,t+dt)
}

One can optionally specify a JSON schema as the schema property of object metadata, which then constrains the data portion of future datapoints to the schema (see example in the metadata section above).

Writing Data¶

If we have write access (write scope), we can append a new datapoint to the timeseries directly, or write an array of data at once:

Sync

# Add a datapoint 5 with current timestamp to the series
obj.append(5)
assert obj[-1]["d"]==5

# Insert the given array of data
obj.insert_array([{"d": 6, "t": time.time()},{"d": 7, "t": time.time(), "dt": 5.3}])

Async

# Add a datapoint 5 with current timestamp to the series
await obj.append(5)
assert (await obj(i=-1))["d"]==5

# Insert the given array of data
await obj.insert_array([{"d": 6, "t": time.time()},{"d": 7, "t": time.time(), "dt": 5.3}])

Removing Data¶

Removing data from a timeseries has identical semantics to querying data. In other words, it is sufficient to specify the range:

Sync

# Remove the last month of data
obj.remove(t1="now-1mo")

# Timeseries are indexed by timestamp, so a specific datapoint can be removed
# by calling remove with its timestamp
dp = obj[-1]
obj.remove(t=dp["t"])

# This is equivalent to the above:
obj.remove(i=-1)

Async

# Remove the last month of data
await obj.remove(t1="now-1mo")

# Timeseries are indexed by timestamp, so a specific datapoint can be removed
# by calling remove with its timestamp
dp = await obj[-1]
await obj.remove(t=dp["t"])

# This is equivalent to the above:
await obj.remove(i=-1)

API¶

Objects¶

class heedy.Objects(constraints, session)[source]¶

Bases: heedy.base.APIList

Objects is a class implementing a list of objects. It is accessed as a property of users/apps/plugin to get the objects belonging to that user/app, or to query objects in all of heedy using plugin.

Sync

myuser.objects() # objects belonging to myuser
myapp.objects() # objects managed by myapp
plugin.objects() # all objects in heedy

Async

await myuser.objects() # objects belonging to myuser
await myapp.objects() # objects managed by myapp
await plugin.objects() # all objects in heedy

__call__(**kwargs)[source]¶

Gets the objects matching the given constraints. If used as a property of a user of an app, it will return only the objects belonging to that user/app (the user/app constraint is automatically added).

Sync

obj = p.objects(type="timeseries",
        key="mykey",
        tags="tag1 tag2",
        owner="myuser",
        app="")

Async

obj = await p.objects(type="timeseries",
        key="mykey",
        tags="tag1 tag2",
        owner="myuser",
        app="")

Parameters

type (str) – The type of the objects (like “timeseries”)
key (str) – The unique app key of the object (each app can only have one object with a given key)
tags (str) – The tags that the object must have, separated by spaces
owner (str) – The owner username of the object (set automatically when accessed using the objects property of a user)
app (str) – The app ID that the object belongs to. Set to empty string for objects that don’t belong to any app. (set automatically when accessing the objects property of an app)
icon (bool,False) – Whether to include the icons of the returned objects’ data.

Returns

A list of Object matching the given constraints.

Throws:: HeedyException: If the request fails.

__getitem__(objectId)[source]¶

Gets an object by its ID. Each object in heedy has a unique string ID, which can then be used to access the object. The ID can be seen in the URL of the object’s page in the frontend.

Sync

obj = p.objects["d233rk43o6kkle43kl"]

Async

obj = await p.objects["d233rk43o6kkle43kl"]

Returns: The Object with the given ID (or promise for the object)

Throws:: HeedyException: If the object does not exist

create(name, meta={}, type='timeseries', **kwargs)[source]¶

Creates a new object of the given type (timeseries by default). Only the first argument, the object name is required.

Sync

obj = app.objects.create("My Timeseries",
    description="This is my timeseries",
    icon="fas fa-chart-line",
    type="timeseries",
    meta={"schema":{"type":"number"}},
    tags="myts mydata"
    key="myts")

Async

obj = await app.objects.create("My Timeseries",
    description="This is my timeseries",
    icon="fas fa-chart-line",
    type="timeseries",
    meta={"schema":{"type":"number"}},
    tags="myts mydata"
    key="myts")

When creating an object for an app, it is useful to give it a key. Keys are unique per-app, meaning that the app can have only one object with the given key.

Parameters

name (str,"") – The name of the object
description (str,"") – A description of the object
icon (str,"") – The icon of the object, either a base64 urlencoded image or fontawesome/material icon id.
owner (str) – The owner of the object (set automatically when accessed using the objects property of a user or app).
app (str) – The app ID that the object belongs to (set automatically when accessing the objects property of an app).
meta (dict,{}) – The metadata of the object.
type (str,"timeseries") – The type of the object
key (str) – The unique per-app key of the object
tags (str,"") – The tags assigned to the object, separated by spaces
owner_scope (str,"*") – The space-separated scopes to give the owner of the object if it is managed by an app.

Returns

The newly created Object, with its data cached.

Throws:: HeedyException: if the object could not be created.

Registering New Types¶

heedy.objects.registry.registerObjectType(objectType, objectClass)[source]¶

If implementing a plugin which creates a new object type in Heedy, it might be useful to add support for the object type in the heedy python client. This is done by creating a subclass of heedy.objects.Object, and then registering it:

from heedy.objects import Object,registerObjectType

class MyType(Object):
    def myfunction(self):
        # Returns the result of a REST API call for the object
        return self.session.get(self.uri + "/mytype/my_rest_endpoint")

registerObjectType("mytype",MyType)

Then, when reading objects, the object type is automatically detected and the correct class is used:

Sync

mtobjs = app.objects(type="mytype")

for mtobj in mtobjs:
    print(mtobj.myfunction())

Async

mtobjs = await app.objects(type="mytype")

for mtobj in mtobjs:
    print(await mtobj.myfunction())

Heedy

Contents

Objects¶

Listing & Accessing¶

Creating & Deleting¶

Reading & Updating Properties¶

Updating Metadata¶

Timeseries Data¶

Reading Data¶

PipeScript Transforms¶

Output DatapointArray¶

Writing Data¶

Removing Data¶

API¶

Objects¶

Object¶

ObjectMeta¶

Timeseries¶

DatapointArray¶

Registering New Types¶