Notifications#

API#

Notifications#

class heedy.notifications.Notification(cached_data, session)[source]#

Bases: APIObject

__getitem__(i)#
delete(**kwargs)#

Calls the element’s URI with the DELETE method. This is a method available for all subclasses of APIObject (objects, apps, users, etc), and removes all associated data from Heedy.

o.delete()
o.read() # Throws error - it longer exists!

await o.delete()
await o.read() # Throws error - it no longer exists!
Parameters

**kwargs – Arguments to pass as query parameters to the server (usually empty)

Raises

HeedyException – If the server returns an error, or when the app does not have permission to delete.

props = {'key'}#

Each element has the above properties available as attributes. In synchronous sessions, they allow you to update the properties directly:

o.name = "My new name"
assert o.name == "My new name"

The above is equivalent to:

o.update(name="My new name")
assert o["name"] == "My new name"

Note that each time you access the properties, they are fetched from the server. In non-interactive scripts it is useful to avoid redundant querying, so each read of data is cached. To use this cached data, you can access the property as a key. Instead of o.name, use o["name"], and call o.read() to create/update the cache. Accessing o["name"] will only work after the data was initially read, otherwise it will lead to a KeyError.

read(**kwargs)#

Sends a GET request to the element’s URI with function arguments as query parameters. This method is available for all subclasses of APIObject (objects, apps, users, etc), and is used to read element’s properties in heedy.

data = o.read(icon=True)

data = await o.read(icon=True)

Caches the result of the read accessible as dict keys:

assert data["name"] == o["name"]

The read or update functions both update the cached data automatically.

Parameters

**kwargs – The url parameters to send with the request.

Returns

The server’s response dict, namely a dict of the element’s properties.

Raises

HeedyException – If the server returns an error.

read_qparams = {}#
update(**kwargs)#

Sends a PATCH request to element’s URI with arguments as a json object. This method is available for all subclasses of APIObject (objects, apps, users, etc), and is used to update the element’s properties in heedy.

o.update(name="My new name",description="my new description")
assert o["name"] == "My new name"

await o.update(name="My new name",description="my new description")
assert o["name"] == "My new name"
Parameters

**kwargs – The properties to update, sent as the json body of the request.

Returns

The server’s response as a dict, namely the updated element’s properties.

Raises

HeedyException – If the server returns an error, such as when there are insufficient permissions.

class heedy.notifications.Notifications(constraints, session)[source]#

Bases: APIList

Heedy supports notifications for users, apps and objects. Notifications can be limited to the related app/object, or can be displayed globally in the notification area.

Notifications are also the main way plugins interact with Heedy’s frontend, allowing buttons that call the backend or display forms that the user can fill in.

__call__(**kwargs)[source]#

Returns a list of notifications satisfying the given constraints. All arguments are optional, and constrain the returned results.

notifications = app.notifications(seen=False,type="md")

notifications = await app.notifications(seen=False,type="md")

When querying notifications for a specific user or app, all notifications of apps and objects owned by the user/app can be returned in a single query by specifying the object or app constraint to be *.

# Get notifications for all objects belonging to the app
notifications = app.notifications(objects="*")
# Get all notifications for the objects belonging to the app,
# AND notifications for the app itself
notifications = app.notifications(objects="*",include_self=True)

# Get notifications for all objects belonging to the app
notifications = await app.notifications(objects="*")
# Get all notifications for the objects belonging to the app,
# AND notifications for the app itself
notifications = await app.notifications(objects="*",include_self=True)
Parameters

  • key (str) – The key of the notifications to return.

  • user (str) – Return notifications belonging to the given user.

  • app (str) – Return notifications belonging to the given app.

  • object (str) – Return notifications belonging to the given object.

  • global (bool) – Return notifications that are global or not

  • seen (bool) – Return only seen/unseen notifications

  • dismissible (bool) – Return only dismissible/undismissible notifications

  • type (str) – Return only notifications of the given type (link/md/post)

  • include_self (bool) – Whether to include the notifications of a constrained user/app when using ‘*’.

Returns

A list containing the data of all matching notifications.

Throws:

HeedyException: If the server returns an error.

__getitem__(key)[source]#

Returns a notification by its key. This is to be used only when constrained to a single user/app/object’s notifications, since keys are not globally unique.

try:
    notification = app.notifications["my_notification"]
except KeyError:
    print("No such notification")

try:
    notification = await app.notifications["my_notification"]
except KeyError:
    print("No such notification")
create(notification, overwrite=False)[source]#

Creates a new notification. Returns an error if the notification already exists. If overwrite is True, then replaces the existing notification.

delete(key=None, **kwargs)[source]#

Deletes notifications satisfying the given constraints. Most common usage is deleting a specific notification for a user/app/object identified by its key:

app.notifications.delete("my_notification")

await app.notifications.delete("my_notification")

The delete method has identical arguments as the __call__ method, so given a set of constraints, it removes all the notifications that would be returned by __call__.

Raises

HeedyException – If the server returns an error.

notify(key, title=None, **kwargs)[source]#

Equivalent to create(kwargs,overwrite=True)

update(data, key=None, **kwargs)[source]#

Modifies all notifications satisfying the given constraints.