Source code for heedy.users

from typing import Dict
from .base import APIObject, APIList, Session, q
from .kv import KV

from . import apps
from . import objects
from .notifications import Notifications


[docs]class User(APIObject): props = {"name", "description", "icon", "public_read", "users_read"} def __init__(self, username: str, session: Session, cached_data=None): super().__init__( f"api/users/{q(username)}", {"user": username}, session, cached_data=cached_data, ) self.cached_data["username"] = username #: An :class:`~heedy.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()``. self.apps = apps.Apps({"owner": username}, self.session) #: An :class:`~heedy.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()``. self.objects = objects.Objects({"owner": username}, self.session) self._kv = KV(f"api/kv/users/{q(username)}", self.session) @property def kv(self): """ The key-value store associated with this user. For details of usage, see :ref:`python_kv`. Returns: A :class:`heedy.kv.KV` object for the element. """ return self._kv @kv.setter def kv(self, v): return self._kv.set(**v) @property def username(self): """ The user's username. This is directly available, so does not need to be awaited in async sessions:: print(myuser.username) """ return self.cached_data["username"] @property def password(self): """ The user's password is hashed in Heedy, and cannot be retrieved. However, a user's password can be changed by a plugin: .. tab:: Sync :: usr.password = "newpassword" .. tab:: Async :: await usr.update(password="newpassword") """ raise PermissionError("A user's password is not readable") @password.setter def password(self, v): return self.update(password=v)
[docs] def update(self, **kwargs): def remPass(x): # Remove the password from the updated cache self.cached_data.pop("password", None) return x return self.session.f(super().update(**kwargs), remPass)
[docs]class Users(APIList): """ Users is a class implementing a list of users. It is accessed by plugins as a property of the :class:`heedy.Plugin` object. It is not currently possible to list users as an app. .. tab:: Sync :: plugin.users() # list of all users in heedy .. tab:: Async :: await plugin.users() # list of all users in heedy """ def __init__(self, constraints: Dict, session: Session): super().__init__("api/users", constraints, session)
[docs] def __getitem__(self, item): """Gets a user by their username. The username can be seen in the URL of the user's page in the frontend. .. tab:: Sync :: usr= p.users["myuser"] .. tab:: Async :: usr = await p.users["myuser"] Returns: The :class:`~heedy.User` with the given username (or promise for the user) Throws: HeedyException: If the user does not exist, or insufficient permissions """ return self._getitem( item, f=lambda x: User(x["username"], session=self.session, cached_data=x) )
[docs] def __call__(self, **kwargs): """ Gets the list of users: .. tab:: Sync :: # list of all users in heedy, including their icons p.users(icon=True) .. tab:: Async :: # list of all users in heedy, including their icons await p.users(icon=True) Args: icon (bool,False): Whether to include the user's icon in the response. Returns: A list of :class:`~heedy.User` objects. Throws: HeedyException: If insufficient permissions or the request fails. """ return self._call( f=lambda x: [ User(xx["username"], session=self.session, cached_data=xx) for xx in x ], **kwargs, )
[docs] def create(self, username, password, **kwargs): """ Creates a new user with the given username and password. .. tab:: Sync :: usr = p.users.create("myusername", "mypassword", name="Steve", description="I like cake", icon="person", users_read=True, ) .. tab:: Async :: usr = await p.users.create("myusername", "mypassword", name="Steve", description="I like cake", icon="person", users_read=True, ) Args: 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 :class:`~heedy.User` object for the new user, with all its data cached. Throws: HeedyException: If insufficient permissions or the request fails. """ return self._create( f=lambda x: User(x["username"], session=self.session, cached_data=x), **{"username": username, "password": password, **kwargs}, )