Users

A heedy instance can have multiple users, all of which have different apps, and their own objects. This page describes accessing users and their properties from the Heedy Python client.

Listing & Accessing

There are two modes of access to users. The first, which allows listing and accessing arbitrary users in the Heedy instance is only available to plugins. A list of all users in the instance can be retrieved with the plugin.users() function from Users:

p = heedy.Plugin(session="sync")
p.users() # Returns a list of all users
p = heedy.Plugin()
await p.users() # Returns a list of all users

To get a specific user by username, it is sufficient to access the users object as a dict:

p = heedy.Plugin(session="sync")
p.users["myuser"] # Returns user w/ username "myuser"
p = heedy.Plugin()
p.users["myuser"] # Returns user w/ username "myuser"

On the other hand, when accessing from an app, the user that owns of the app can be accessed directly (if the app has the owner:read scope!):

app = heedy.App("your_access_token","http://localhost:1324")
app.owner # Returns the User object of the app's owner
app = heedy.App("your_access_token","http://localhost:1324",session="async")
await app.owner # Returns the User object of the app's owner

Each App and Object element has a corresponding owner property/attribute, which can be read by both plugins and apps.

Creating & Deleting

A Heedy plugin can create/delete users, but an app cannot. Users can be added using the create() method:

usr = p.users.create("myusername","mypassword")
usr = await p.users.create("myusername","mypassword")

Likewise, once a User object is retrieved, the user can be deleted by calling its delete() method:

usr.delete()
await usr.delete()

Reading & Updating Properties

Properties available on a user can be accessed directly as properties or attributes in the User object:

# Does not use a server query, since username is the user object's ID
print(usr.username) 
# Reads the user's display name from the server
print(usr.name)
# Uses the previously read cached data, avoiding a server query
print(usr["name"])
# Does not use a server query, since username is the user object's ID
print(usr.username) 
# Reads the user's display name from the server
print(await usr.name)
# Uses the previously read cached data, avoiding a server query
print(usr["name"])

To update the corresponding properties, the update function can be used, or if in a sync session, the properties can also be directly set:

usr.name = "Alan Turing" # Sets the user's display name
# The update function allows setting multiple properties in a single query
usr.update(description="I like computers")
# The update function allows setting properties for the user:
await usr.update(name="Alan Turing", description="I like computers")

Updating User Password

Since heedy plugins have full access to the Heedy database, they can also change a user’s password. Passwords in Heedy are hashed, so it is not possible to read an existing password, but it can be updated like a normal property:

usr.password= "newpassword"
await usr.update(password="newpassword")

API

Users

class heedy.Users(constraints, session)[source]

Bases: heedy.base.APIList

Users is a class implementing a list of users. It is accessed by plugins as a property of the heedy.Plugin object. It is not currently possible to list users as an app.

plugin.users() # list of all users in heedy
await plugin.users() # list of all users in heedy
__call__(**kwargs)[source]

Gets the list of users:

# list of all users in heedy, including their icons
p.users(icon=True)
# list of all users in heedy, including their icons
await p.users(icon=True)
Parameters

icon (bool,False) – Whether to include the user’s icon in the response.

Returns

A list of User objects.

Throws:

HeedyException: If insufficient permissions or the request fails.

__getitem__(item)[source]

Gets a user by their username. The username can be seen in the URL of the user’s page in the frontend.

usr= p.users["myuser"]
usr = await p.users["myuser"]
Returns

The User with the given username (or promise for the user)

Throws:

HeedyException: If the user does not exist, or insufficient permissions

create(username, password, **kwargs)[source]

Creates a new user with the given username and password.

usr = p.users.create("myusername", "mypassword",
        name="Steve",
        description="I like cake",
        icon="person",
        users_read=True,
    )
usr = await p.users.create("myusername", "mypassword",
        name="Steve",
        description="I like cake",
        icon="person",
        users_read=True,
    )
Parameters
  • username (str) – The username of the new user. Required.

  • password (str) – The password of the new user. Required.

  • name (str,"") – The display name for the new user.

  • description (str,"") – A description for the user.

  • icon (str,"") – The icon to use for the user.

  • public_read (bool,False) – Whether the user can be seen by anyone visiting this heedy instance

  • users_read (bool,False) – Whether the user can be seen by other users

Returns

The User object for the new user, with all its data cached.

Throws:

HeedyException: If insufficient permissions or the request fails.

User

class heedy.User(username, session, cached_data=None)[source]

Bases: heedy.base.APIObject

props = {'description', 'icon', 'name', 'public_read', 'users_read'}

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.

apps

An Apps instance associated with the user, allowing to interact with the apps belonging to the user. For example, listing the user’s apps can be done with user.apps().

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.

property kv

The key-value store associated with this user. For details of usage, see KV.

Returns

A heedy.kv.KV object for the element.

notifications

A Notifications object that allows you to access the notifications associated with this element. See Notifications for details.

notify(*args, **kwargs)

Shorthand for self.notifications.notify (see Notifications).

objects

An Objects instance associated with the user, allowing to interact with the user’s objects. For example, listing the objects that are owned by the user can be done with usr.objects().

property password

The user’s password is hashed in Heedy, and cannot be retrieved. However, a user’s password can be changed by a plugin:

usr.password = "newpassword"
await usr.update(password="newpassword")
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.

update(**kwargs)[source]

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.

property username

The user’s username. This is directly available, so does not need to be awaited in async sessions:

print(myuser.username)